Skip to main content
A legacy expansion is a main.js with module.exports.metadata and init(), using the global api. Those still load, marked Legacy on the Expansions page, but they are deprecated and the SDK is where new work goes. Since SDK 2.1.0, every legacy API point has an SDK equivalent, so no expansion needs to stay legacy because a feature is missing.

The shape

Steps:
  1. Move metadata into meta.json. Add sdkVersion (^2.1.0) and permissions (see below). Add config.json.
  2. Replace init() with top-level code in the start file, or a class if you prefer.
  3. Replace path strings with imports: __dirname + '/pages/X.jsx' becomes import X from './pages/X'.
  4. In components, replace the props api, useComponents() and useProjectState with imports from sdk and sdk/ui.
  5. Delete api.expansion.call(...): logic and UI are one module graph now, so just import the function.

Point by point

Everything in the right column from getProjectList down is new in 2.1. See the sdk reference for each.
extendExistingFormat’s exporter-specific output mapping objects have no direct equivalent: exports run outside the window, where your functions cannot be passed. Rewrite items before the exporter with export.transform, or its output with export.transformFile or modules.export.

Permissions

Legacy expansions had none: api could reach the whole project and the filesystem. In the SDK, declare what you use:
  • reading items or project files: project:read
  • writing them, or running an export: project:write
  • fetch, WebSocket, opening links: network
  • clipboard: clipboard
  • opening or saving files on the user’s computer: files
  • the test server’s console and controls: server
  • asking Echo: echo
See Permissions for exactly what each one unlocks.

What the SDK deliberately cannot do

Legacy could reach arbitrary paths on disk, spawn processes and require Node modules. The SDK cannot, by design. Use the project APIs for project files, sdk.storage.files for your own data, and sdk.dialog.pickFile / saveFile for files the user chooses.

Things that change quietly

  • Ids are namespaced. A page registered as counter is my_expansion.counter, and its route changes to match. Anything you hard-coded needs updating.
  • Imports are real. Helpers, shared files and CSS work now, which is usually a chance to delete the workarounds the old modulars needed.
  • Cleanup is automatic. Anything you registered is removed on reload or disable; remove hand-rolled teardown.
  • No Node. Any require('fs') or child process work has no equivalent and must go through the SDK.