Building Extensions

Use the source catalogue when you want to add or change an extension.

Scaffold

npm run new -- my-extension
npm run new -- my-extension

This creates packages/extensions/src/my-extension/ from _template, regenerates the catalogue (npm run catalog) and prints the checklist below. The untouched scaffold passes npm run verify (tests/new-extension-smoke.ts).

Implement

Edit:

  • packages/extensions/src/my-extension/index.ts
  • packages/extensions/src/my-extension/extension.json

Keep the extension self-contained. Runtime code may import Node built-ins and declared package peers, but it must not import from sibling extensions or packages/core/lib.

Add to a Profile

The template declares "profiles": [], so a new extension ships in no profile. To include it in a profile (for example lite), add its stable extension name to the profile's include list in packages/kit/profiles/<profile>.json, then run npm run catalog: it derives the profiles field of every extension.json from the profile files, so that one edit is the whole change (and npm run verify fails if the two ever differ). Then check:

npm run profile:check -- --profile lite
npm run smoke:package

Update the Catalogue

After editing extension.json, regenerate the catalogue:

npm run catalog
npm run catalog

The generated catalogue appears in Extension Catalogue.

Verify

npm run verify
npm run verify

For the full extension-writing reference, see Writing Extensions.