@zappar/mattercraft-cli

A CLI (and programmatic API) for building Mattercraft projects. Export your project from the Mattercraft editor, run a single command, and get production-ready output — no bundler config needed.

Under the hood it uses Vite 8 with the @zappar/mattercraft-vite-plugin preconfigured. You don't need to think about any of that.

Installation

npm install @zappar/mattercraft-cli

Or just run it directly with npx — no install required:

npx @zappar/mattercraft-cli

CLI Usage

Point it at a directory containing your exported Mattercraft project:

mattercraft ./my-project

That's it. Built files end up in ./my-project/dist.

Options

mattercraft [root] [options]

Arguments:
  root                   Project root directory (default: ".")

Options:
  -o, --out <dir>        Output directory (default: "dist")
  -b, --base <path>      Base public path (default: "/")
  -a, --alias <from=to>  Module resolution alias (repeatable)
  -h, --help             Show this help message

Aliases

Use --alias to redirect import specifiers at build time. This is useful when a dependency uses deep imports that aren't permitted by the package's exports field, or when you want to swap one module for another. Each --alias is a from=to pair and the flag may be repeated:

npx @zappar/mattercraft-cli ./my-project \
  --alias 'lodash=lodash-es' \
  --alias '@/utils=./src/utils'

Aliases are forwarded to Vite's resolve.alias, so prefix matching follows Vite's rules (the match must end at a / or end of string).

CI/CD

Drop this into your pipeline and you're done:

npx @zappar/mattercraft-cli ./my-project --out ./build

TypeScript & Decorators

TC39 decorators are supported out of the box — no extra config needed. The Mattercraft plugin automatically transforms them during the build.

If your project has a tsconfig.json, Vite will use it automatically. If you'd like to add one, we recommend:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2020",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "strictNullChecks": true,
    "declaration": false,
    "jsx": "react-jsx"
  }
}

Programmatic Usage

If you'd rather call it from your own scripts or tooling:

import { build } from '@zappar/mattercraft-cli';

await build({
  root: './my-project',
  outDir: 'build',
  base: '/my-app/',
});

build(options?)

Builds the project and writes output to disk.

| Option | Type | Default | Description | | -------- | ------------------------ | ------- | ------------------------------------------ | | root | string | "." | Project root containing index.html | | outDir | string | "dist"| Where to write the built files | | base | string | "/" | Base public path for asset URLs | | alias | Record<string, string> | — | Forwarded to Vite's resolve.alias |

Throws if no index.html is found in the root directory.

Requirements

• Node 24 or later

License

Proprietary - Zappar Limited