Quick start

You need Matter running on your computer and signed in, and Node with npm for your app’s build.

Put matter on your PATH

The matter command comes with Matter. Add its folder to your shell’s PATH, for example in ~/.zshrc:

export PATH="$HOME/.matter/bin:$PATH"

On Windows, add %USERPROFILE%\.matter\bin to your Path.

Agent threads in Matter already have it, so you can also ask an agent to run these commands. matter app --help lists every command.

Create the app

matter app create pipeline --space Sales --name "Pipeline" --icon 📈
cd pipeline

This creates the app in the space, and scaffolds an empty project in the folder you name (the current folder if you leave it out):

• matter.json: the manifest, with the new app’s id and the oldest Matter it runs on;
• schema.json: the tables the app needs;
• package.json for Vite and TypeScript, vite.config.ts with the SDK plugin, and tsconfig.json;
• index.html, src/main.ts and src/style.css: a page that greets the member in Matter’s theme;
• .gitignore and a README.

With --worker, it adds a worker too, in src/worker.ts.

Then it writes src/matter-app.d.ts, the types for the SDK and your space’s tables (the same as matter app types). The dev server gets a port of the app’s own, between 5200 and 5799, so it doesn’t collide with other projects. create never overwrites a file that’s already there.

You can also create an app in Matter itself: choose New app in the space’s settings under Apps, or the + beside the sidebar’s Apps heading once the space has an app. Deploy to it from a project with matter app deploy --app <id>, or put its id in matter.json as app.

Install and develop

npm install
matter app dev

matter app dev starts your dev server (dev.command in matter.json), waits for it to answer, and shows it in Matter in place of the deployed app. Open the app from the sidebar. Changes reload as you save, and the app’s header shows a Dev pill with the dev server’s address. Press Ctrl-C to stop: the app goes back to its deployment. To keep it running after you close the terminal, use matter app dev --background, and matter app dev --stop later.

This works before the app’s first deploy too: until then, Matter shows only your dev server.

Add your tables

Describe the tables in schema.json and apply it:

{
  "tables": [
    {
      "name": "Deals",
      "fields": [
        { "name": "Name", "type": "title" },
        { "name": "Stage", "type": "select", "options": ["Lead", "Won", "Lost"] },
        { "name": "Amount", "type": "number" }
      ],
      "indexes": [
        { "name": "by_stage", "match": ["Stage"], "order": [{ "field": "Amount", "direction": "desc" }] }
      ]
    }
  ]
}

matter table apply schema.json

It creates what’s missing in the app’s space and changes nothing else. While matter app dev runs, your types follow the tables, so matter.table('Deals') is typed a few seconds later. See Tables and indexes.

Read and write

In src/main.ts:

import matter from '/_matter/sdk.js'

const deals = matter.table('Deals')
const root = document.querySelector<HTMLElement>('#app')!
const list = document.createElement('ul')
const add = Object.assign(document.createElement('button'), { textContent: 'Add a lead' })
root.append(add, list)

// A live read: it answers now, and again whenever the leads change.
deals.watch({ index: 'by_stage', eq: { Stage: 'Lead' }, limit: 50 }, (state) => {
  if (state.status !== 'ready') return
  list.replaceChildren(
    ...state.value.rows.map((row) => Object.assign(document.createElement('li'), { textContent: row.title })),
  )
})

add.onclick = () => deals.insert({ title: 'Acme', values: { Stage: 'Lead', Amount: 12000 } })

A new row appears in the list at once, and in the table in Matter. Its title is its Name: reads give it as row.title and as row.values.Name.

Deploy

Every version is signed with a key of yours. Make one, once:

matter keys create

It asks for a passphrase, which you can leave empty, and registers the key in your workspace. See Signing keys. Then:

matter app deploy -m "First version"

This runs your build, signs and uploads the deploy folder and makes it the current version. Members trust your key the first time they open one of your apps; you never need to. Everyone in the space who opens the app gets it. Deploy again after each change. See Developing, previewing and shipping for previews and rollbacks.