Developing, previewing and shipping

Developing with matter extension dev

matter extension dev runs your project in Matter as you work on it:

• It starts dev.command from matter.json, your dev server, and once dev.url answers, shows the extension’s pages from it instead of the deployment. They keep the extension’s usual origin, so the SDK, the context and cookies work as they will once deployed, and hot reload works. The extension’s header shows a Dev pill with the dev server’s address.
• It starts dev.worker, your dev worker, if the project has one.
• The routines matter.json declares become your dev routines: copies of each, yours alone, titled “(dev)”, that run on this computer from your project, with its tools. Your pages in dev run and list these, not the live ones.
• Your generated types follow the space’s tables while it runs.

The deployed version keeps running alongside: its worker, its routines, everyone else’s extension. Only you see your dev server.

In the foreground, matter extension dev shows your dev server’s and dev worker’s output until you press Ctrl-C. That stops them, and the extension goes back to its deployment.

matter extension dev --background   # keeps running after you close the terminal
matter extension logs dev-server -f # its output, whenever you want it
matter extension dev --stop

In the background it lasts until matter extension dev --stop, across closing the terminal and restarting Matter.

If your dev server is already running, use matter extension dev --no-command; --no-worker leaves your worker out. If nothing answers within a minute, dev stops and shows the dev server’s last output.

Use the extension menu’s Developer tools to inspect pages, as in a browser. To run a worker or tools by hand, see the environment.

Deploying

matter extension deploy -m "What changed" builds the extension, signs it with your signing key, uploads deploy.dir and makes the new version current. The first time, make a key with matter keys create. Members with the extension open see a New version button in its header, which reloads it. Workers restart on the new version.

Static files are served as they are, and any route without a file extension, like /deals/123, loads index.html, so client-side routing works.

Previews

A preview is a version that isn’t current. Only people who open it see it.

matter extension deploy --preview -m "Try the new Today page"
matter extension open --preview <deploymentId>

The link matter://app/<extension id>?preview=<deploymentId> opens it too. The extension’s header shows a Preview pill.

Versions and rollbacks

Versions in the extension’s menu lists every version, newest first, with who deployed it and its message. Each has Preview and Make current. Making an older version current is how you roll back.

From the command line:

matter extension deployments          # the 30 most recent, * marks the current one
matter extension promote <deploymentId>

Matter keeps an extension’s current version, the 20 before it, and anything from the last 30 days. Older versions, and previews more than 30 days old, are deleted.

Managing extensions

In a space’s settings, Extensions lists the space’s extensions. Each extension’s menu there has:

• Open and Versions;
• Rename, to change its name and icon;
• Move to space: the extension moves, and its tables stay behind;
• Run extension routines on this computer: the runner computer for its extension-scope routines;
• Archive: the extension leaves the sidebar, stops, and its routines wait, until you Unarchive it;
• Delete: deletes the extension, its versions and its routines for everyone. Its tables stay in the space.

Manage extensions in an extension’s own menu opens the same list. Workspace guests can’t manage extensions.