Building and running

You need Node.js 22 or newer (CI uses 24) and npm.

npm ci              # dependencies
npm run compile     # tsc (Node and webview builds), WASM copy, bundles, contribution and l10n bundle checks
npm run watch       # tsc in watch mode while you work
npm run lint        # eslint, the layer rules and check:l10n

Running the extension#

Open the repository in VS Code and press F5 (Run Extension). The Extension Development Host opens with the extension loaded; open sample/app.design there.

The development server#

npm run dev

compiles and serves the editor in a browser at http://localhost:4173, editing sample/app.design with the same controller and webview as in VS Code. It is the quickest way to work on the webview, and the target of the headless Chromium tests and screenshots. node out/dev/server.js --file sample/app.design --locale pt-br serves the page in Brazilian Portuguese.

Translations (NFR-7)#

Every string a person reads is translatable, and the English text is the key:

• Extension host (src/host/vscode, src/extension*.ts): vscode.l10n.t("Exported {0} files", count). Modules that cannot import vscode (src/host/controller, the licence menu, the status bar texts) call the shim l10n.t(…) from src/host/controller/l10n.ts, which activation points at vscode.l10n.t (it is the identity in unit tests).
• Pages (media/): t("Bring to front"), t("Copied {0} layers", count) from media/utils/t.js. The host puts the display language’s bundle in the page’s HTML and in init; English has none. Keep one sentence per key, values in {0} placeholders and a key per plural form. Undo labels, new layer names, code, key and font names stay English.
• Manifest: command titles, view names and setting descriptions are %key% references into package.nls.json, which scripts/gen-contributions.mjs writes (npm run gen:contributions; compile runs it with --check).

npm run l10n:extract   # rebuild l10n/bundle.l10n.json from vscode.l10n.t / l10n.t (via @vscode/l10n-dev), t() in media/ and the registry
npm run check:l10n     # strings left outside t() / l10n.t(), unused or missing keys, translations missing a key

compile runs l10n:extract --check and lint runs check:l10n, so after adding or changing a string run npm run l10n:extract and add its translation to l10n/bundle.l10n.pt-br.json (and package.nls.pt-br.json for a manifest text). check:l10n is a heuristic: a literal that must stay English can end its line with // l10n-ignore, and scripts/l10n-allow.json lists product, key and font names.

The ud command from the repository#

npm run ud -- tree sample/app.design
node dist/ud.js help

Packaging#

npm run package     # vsce package, then the .vsix size check

npm run check:licences checks the third-party licences listed in THIRD-PARTY-NOTICES; npm run build:schema regenerates schemas/design-1.0.schema.json and npm run test:schema validates the sample files against it.

The documentation site#

This site is built with Hugo from docs.src/ into docs/:

npm run compile     # the generators load out/
npm run docs:gen    # specifications from planning.pb, the CLI and Plugin API reference from the source
npm run docs:build  # hugo --source docs.src --cleanDestinationDir
npm run docs:serve  # live preview at http://localhost:1313/vscode-extension-ui-designer/

The workflow .github/workflows/docs.yml builds and deploys it to GitHub Pages on every push to master that changes its inputs.