Upgrade from 1.x

Handoff 2 changes the runtime requirements, the declaration API, the Figma settings, and the output directories. Upgrades within 2.x are covered in each release note.

Before you start

1. Make sure the project builds with its current Handoff version.
2. Commit the project files, the package version, and the lockfile.
3. Install the 2.x version you plan to use: npm install handoff-app@^2.1.0.
4. Apply the sections below that affect your project.

Node.js 22

Handoff 2 requires Node.js 22 or newer and npm 10 or newer. Update Node.js, CI images, and hosting runtimes first. Projects that init created in 1.x declare the old minimum. Change it:

"engines": {
  "node": ">=22",
  "npm": ">=10"
}

Figma settings

The Figma file ID and access token moved to integrations.figma. Handoff ignores the old top-level figmaProjectId, figma_project_id, devAccessToken, and dev_access_token. If you use HANDOFF_FIGMA_PROJECT_ID and HANDOFF_DEV_ACCESS_TOKEN and set no Figma values in config, no change is needed.

The access token accepts only an environment reference. A literal token throws HandoffConfigError, in TypeScript, JavaScript, and JSON configs alike.

import { defineConfig, fromEnv } from 'handoff-app'

export default defineConfig({
  integrations: {
    figma: {
      projectId: 'your-figma-file-id',
      accessToken: fromEnv('HANDOFF_DEV_ACCESS_TOKEN'),
    },
  },
})

In JSON, write "accessToken": { "$env": "HANDOFF_DEV_ACCESS_TOKEN" }.

Catalog items

Handoff 2 requires defineCatalogItem for components and compositions.

Register catalog directories

Move component and pattern directories from entries to catalog.include. Global entries.js and entries.scss still work.

entries: { components: ['components'], patterns: ['patterns'], scss: 'styles/main.scss' }

catalog: { include: ['components', 'patterns'] },
entries: { scss: 'styles/main.scss' }

Rename declaration files

• Use <name>.handoff.ts, .handoff.tsx, .handoff.js, or .handoff.cjs.
• Replace legacy file names such as button.json or button.js.
• JSON declarations, including .handoff.json, are no longer read. handoff.config.json still works.
• If runtime.workspace.declarationFormat is json, change it to ts, js, or cjs.

Replace the helpers

Remove the renderer, entries.component, entries.template, and entries.story fields; the implementation supplies them. Keep entries.js, entries.scss, entries.schema, and entries.templates if the item uses them.

Export previews

Remove the inline previews map. Export each preview next to the default export, rename preview title to name, and rename values to args:

export const Primary = { name: 'Primary action', args: { children: 'Save' } }

• Keep a preview key's spelling if it is a valid export name. Rename it otherwise, and update the composition references to it.
• Previews appear in source export order.
• In CommonJS, use exports.default for the item and exports.Primary for each preview.

Replace removed types

Output directories

1.x named directories after the project id (the Figma file ID, or a name from the project path). 2.x uses fixed names:

1. Update deploy scripts and CI steps that read out/<projectId>. With sitesOutputDirectory or HANDOFF_SITES_DIR set, the site is in static under that directory.
2. Move exported/<projectId> up to exported, or run npm run fetch again. Commit the result.
3. Merge public-<projectId> into public, then remove it.

A repository that builds several Figma files sets HANDOFF_SITES_DIR and HANDOFF_OUTPUT_DIR, or the matching config values in a profile, per build.

Removed features

• The make:template command.
• The legacy /assets pages. The foundation pages show logos and icons.

Verify the upgrade

1. Build the project.
2. Check that every catalog item appears, with the expected preview order, args, and composition references.
3. Run npm run start, edit a declaration, and check that its previews update.
4. With a registry: publish the migrated items, check them out into a scratch workspace, and build that workspace.