Figma development installation

This guide is for authorized developers/operators of the Localisync hosted service. The plugin is in local validation; this is not a Community installation or a general self-hosted endpoint selector. Figma Desktop and a permanent development plugin ID are required.

Prepare the local plugin

Create a Figma Design development plugin with Custom UI in Figma Desktop. Keep the assigned ID. In the Localisync source checkout, use the repository’s pinned Node/pnpm tools:

pnpm install --frozen-lockfile
FIGMA_PLUGIN_ID=YOUR_FIGMA_PLUGIN_ID pnpm build:figma

Import apps/figma/dist/manifest.json with Figma’s development plugin command. The output contains code.js, ui.html and dependency license notices. Import the generated manifest, not Figma’s original TypeScript template: its placeholder code.js deliberately refuses to run. Keep the template and any existing design files intact.

The normal build only allows https://app.localisync.com. Its hosted interface and API must be enabled and compatible before connection will work. Never point an unreviewed build at customer data. Rebuild/reimport after changing the document adapter or protocol.

For an isolated loopback environment only:

FIGMA_DEVELOPMENT=true FIGMA_UI_ORIGIN=http://localhost:3011 \
  FIGMA_PLUGIN_ID=YOUR_FIGMA_PLUGIN_ID pnpm build:figma

Use the hostname localhost, not a numeric loopback address: Figma’s manifest validator rejects the numeric address with a port. Set the local API/panel PANEL_ORIGIN and the test identity client’s callback/logout URLs to the same localhost origin. Changing only the manifest leaves the UI message origin and authentication checks inconsistent.

The local interface must already be running on that exact origin. Desktop/browser local network policies may require the operator to allow the development connection. Do not disable browser security globally. A loopback development build is not a customer distribution.

If the UI loads but remains waiting for the document, an operator can temporarily set FIGMA_DIAGNOSTICS=true for both the local plugin build and local panel process. This is accepted only for localhost development. Console messages prefixed Localisync bridge: report startup, hello/ready delivery and bounded origin/source checks; they never include design text, message payloads, tokens or document identifiers. Turn this off after diagnosis and rebuild/restart the local environment. Do not widen the manifest or message origins to make a connection succeed.

Enable the matching service

Apply the additive Figma migration with the existing migration operator, separately from application startup. Upgrade API and panel together. Set FIGMA_ENABLED=true and the same FIGMA_PLUGIN_ID in their runtime configuration. The feature is disabled by default. Production configuration accepts only the hosted panel origin.

Only /figma/plugin allows framing by the documented Figma origins. Keep its route-specific CSP intact through the reverse proxy. Do not remove frame protection from sign-in, approval, connections or the normal panel. No wildcard CORS or global iframe allowance is required. The API accepts versioned Figma credentials only at its dedicated content boundary.

Existing image/assistance worker configuration, private image capacity, provider connections and the OpenBao vault are reused. The plugin cannot manage provider secrets. Maintenance barriers cover its writes. Recovery invalidates parent sessions before reopening and therefore invalidates restored plugin credentials as well. No automatic paid assistance resumes.

Verification and rollback

Run pnpm test:figma, root checks/build and the documented isolated browser tests. Then verify mapping, font/style failure, three-way conflicts, ICU samples, language copies and Undo in real Figma Desktop. Automated document adapters do not replace this acceptance.

To withdraw the feature, set FIGMA_ENABLED=false in API and panel and revoke connections. Preserve mapping, completed receipts and history. Do not downgrade by deleting the new tables or bypass current language permissions. Community publication and production enablement require separate release approval.