Developing, previewing and shipping

Developing with matter app dev

matter app 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 app’s pages from it instead of the deployment. They keep the app’s usual origin, so the SDK, the context and cookies work as they will once deployed, and hot reload works. The app’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 app. Only you see your dev server.

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

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

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

If your dev server is already running, use matter app 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 app menu’s Developer tools to inspect pages, as in a browser. To run a worker or tools by hand, see the environment.

Deploying

matter app deploy -m "What changed" builds the app, 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 app 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 app deploy --preview -m "Try the new Today page"
matter app open --preview <deploymentId>

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

Versions and rollbacks

Versions in the app’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 app deployments          # the 30 most recent, * marks the current one
matter app promote <deploymentId>

Matter keeps an app’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 apps

In a space’s settings, Apps lists the space’s apps. Each app’s menu there has:

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

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