@web-to-figma/desktop

Local capture server for Web to Figma Lifetime users. Runs on your machine and stores exports on disk instead of the cloud.

Requirements

• Node.js 18+ (node --version)
• macOS or Windows (Linux may work but is not officially supported)

Quick start

npx @web-to-figma/desktop start

The server listens on http://127.0.0.1:17345 by default. If that port is in use, it tries the next ports up to 17355.

Leave the terminal open while importing in the Figma plugin.

Commands

| Command | Description | |---------|-------------| | npx @web-to-figma/desktop start | Start the local server | | npx @web-to-figma/desktop start --verbose | Start with auth and request logging | | npx @web-to-figma/desktop start --port 17347 | Use a specific port | | npx @web-to-figma/desktop capture | Open Chrome with the bundled extension for manual capture | | npx @web-to-figma/desktop capture <url> | Same, but open directly on the given URL | | npx @web-to-figma/desktop doctor | Check Node version, port availability, and Chrome setup | | npx @web-to-figma/desktop version | Print installed version |

Global install

npm install -g @web-to-figma/desktop@latest
web-to-figma start

Press Ctrl+U while the server is running to check for updates.

Data location

| Path | Contents | |------|----------| | ~/.web-to-figma/ | Config, SQLite database, captured files | | ~/.web-to-figma/logs/ | Server logs |

Troubleshooting

1. Plugin shows “Waiting for server” — confirm the start command is running and the terminal has no errors.
2. Port in use — stop other desktop processes or run npx @web-to-figma/desktop doctor.
3. 401 errors from plugin — plugin and desktop JWT secrets must match (production builds inject the same secret at publish time).
4. Capture fails — run doctor and ensure Chrome can be downloaded (corporate proxies may block downloads).

For support workflows, see 17-support-runbook.md.

Environment variables

| Variable | Default | Purpose | |----------|---------|---------| | WTF_DESKTOP_PORT | 17345 | HTTP port | | WTF_DATA_DIR | ~/.web-to-figma | Data directory | | WTF_CHROME_PATH | auto | Chrome binary override | | WTF_CHROMEDRIVER_PATH | auto | ChromeDriver override | | WTF_SENTRY_DSN | from package.json | Sentry DSN override | | WTF_ENV | production | Sentry environment tag | | DESKTOP_JWT_SECRET | .env.development for local dev; embedded at release build | JWT secret (must match plugin renderer) |

For local development, copy or edit .env.development (loaded when NODE_ENV is not production). Use .env.production for production-mode local runs. Put machine-specific overrides in .env.local or .env.development.local — those files are gitignored.

Development

From this repository:

cd desktop
npm install
npm run dev          # build + start with --verbose
npm test             # unit tests
npm run build:release  # reads JWT secret from .env.production, inject + obfuscate

Extension CRX files for capture are built in CI from extension/ and bundled into assets/extension/. For local capture without CI artifacts, build the extension:

cd extension
npm run build-desktop-headless
cp build/chrome-mv3-prod.crx ../desktop/assets/extension/chrome-mv3-headless.crx
npm run build-desktop-headed
cp build/chrome-mv3-prod.crx ../desktop/assets/extension/chrome-mv3-headed.crx

See assets/extension/README.md for details.

Publishing

Package: @web-to-figma/desktop on the public npm registry under the web-to-figma organization.

Before each release

1. Bump version in package.json (semver). Published versions are immutable — ship a patch for fixes.
2. Confirm DESKTOP_JWT_SECRET matches the production plugin renderer secret (injected at build time).
3. Ensure GitHub repo secrets are set: NPM_TOKEN (org publish token), DESKTOP_JWT_SECRET.

Publish via CI (recommended)

The Desktop Publish workflow builds extension CRXs, runs release build (inject + obfuscate), tests, smoke test, pack check, and publishes.

Option A — git tag

git tag desktop-v1.0.1
git push origin desktop-v1.0.1

Option B — manual dispatch

GitHub → Actions → Desktop Publish → Run workflow → check Publish to npm.

Tag format: desktop-v* (e.g. desktop-v1.0.1 matches package.json version 1.0.1).

Publish locally (fallback)

Requires npm login or token with publish access to @web-to-figma/*, plus built extension CRXs (see Development above).

cd desktop
export DESKTOP_JWT_SECRET="..."   # same secret as CI / plugin production
npm run build:release
npm run pack:check                # inspect tarball contents
npm publish --access public

After publish

• Verify: npm view @web-to-figma/desktop version and npx @web-to-figma/desktop@latest doctor
• To pull a bad release: npm deprecate @web-to-figma/[email protected] "reason" then publish a fixed version

More detail: 13-npm-distribution-and-obfuscation.md.