Importing the SDK

The SDK is one module for pages and for the worker, tools and run server. In a page it calls the app’s own origin. In Node it calls Matter with the token Matter gives the process.

In a page

Pages import the SDK from their own origin:

import matter from '/_matter/sdk.js'

Tell your bundler to leave that import alone. With Vite:

import { defineConfig, type Plugin } from 'vite'

const matterSdk: Plugin = {
  name: 'matter-sdk',
  enforce: 'pre',
  resolveId: (id) => (id === '/_matter/sdk.js' ? { id, external: true } : null),
}

export default defineConfig({
  plugins: [matterSdk],
  build: { rollupOptions: { external: ['/_matter/sdk.js'] } },
})

matter app create writes this for you. During matter app dev, Vite may log that it couldn’t pre-transform /_matter/sdk.js. That’s harmless: Matter serves the file itself.

In Node

The worker, tools and run server import the file that MATTER_SDK names:

const { default: matter } = await import(process.env.MATTER_SDK)

In TypeScript, type it with the generated types:

const { default: matter } = (await import(process.env.MATTER_SDK!)) as typeof import('@matter/app-sdk')

For tests outside Matter, matter app sdk writes a copy of the module.

Who’s using the app

In a page, the context is there before your code runs:

Property	What it is
matter.user	{ id, memberId, name, role, timezone }
matter.role	owner, admin, member or guest
matter.app	{ id, name }
matter.space	{ id, name }
matter.workspace	{ id, name }

await matter.context() gives all of these, plus:

• deployment: { id, preview, local }, the version showing. preview is true for a version that isn’t current.
• setup: the member’s setup, { deviceId, thisDevice }, or null if they haven’t set the app up.
• device: { id }, this computer.

In Node, call await matter.context() first. Until then the properties are undefined.

matter.onContextChange(listener) hears renames, role changes and setup moves. It returns a function that stops listening.

const stop = matter.onContextChange((context) => renderHeader(context.user.name))

Errors

Calls that fail reject with a MatterError, which has a code, a message and the HTTP status. Codes include:

• invalid: the request is wrong; the message says how.
• not_found: no such table, routine or route.
• precondition_failed: a conditional update’s condition didn’t hold.
• conflict: a unique index already has a row with those values.
• forbidden: the member isn’t allowed to do this.
• unavailable: Matter can’t answer this here, or the SDK isn’t running inside Matter.

Workspace lookups

• await matter.tables(): the tables of the app’s space, with their fields ({ id, name, type, options? }).
• await matter.members(): the workspace’s active members, { id, name, role }.