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
- Move
metadataintometa.json. AddsdkVersion(^2.1.0) andpermissions(see below). Addconfig.json. - Replace
init()with top-level code in the start file, or a class if you prefer. - Replace path strings with imports:
__dirname + '/pages/X.jsx'becomesimport X from './pages/X'. - In components, replace the props
api,useComponents()anduseProjectStatewith imports fromsdkandsdk/ui. - 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
What the SDK deliberately cannot do
Legacy could reach arbitrary paths on disk, spawn processes andrequire 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
counterismy_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.