@percepta/create-surface

Scaffold and manage Mosaic packages.

Usage

# Interactive mode
npx @percepta/create-surface

# With project directory
npx @percepta/create-surface my-new-app

# Non-interactive (accept defaults)
npx @percepta/create-surface my-new-app --yes

# Skip dependency install
npx @percepta/create-surface my-new-app --skip-install

# Use a different package manager
npx @percepta/create-surface my-new-app --use-npm
npx @percepta/create-surface my-new-app --use-yarn

Options

| Option | Description | |--------|-------------| | -t, --type <type> | Package type: webapp or library | | --name <name> | Project name (defaults to directory name) | | --title <title> | Display title (defaults to title case of name) | | --skip-install | Skip dependency installation | | --use-npm | Use npm instead of pnpm | | --use-yarn | Use yarn instead of pnpm | | -y, --yes | Skip all prompts and use defaults |

Subcommands

• create (default) — scaffold a new Mosaic package
• status — show template sync status for the current app
• sync — generate downstream sync context (template → app)
• upstream — generate upstream context (app → template)
• init — add .mosaic-template.json to an existing app

What's Included

The webapp template ships with:

• Next.js 15 with App Router
• Authentication via Better Auth
• Database with PostgreSQL and Drizzle ORM
• Type-safe API with tRPC
• Background Jobs with Inngest
• Observability with OpenTelemetry, Langfuse, and Grafana Faro
• Styling with Tailwind CSS v4

Development

Building the CLI

pnpm build

Testing locally

pnpm build
npm link
create-surface test-app

Syncing template files

When the base template is updated, sync the changes:

pnpm sync-template

Publishing

Publishing is automated via changesets on merge to main. See the repo-root .changeset/README.md and .github/workflows/build-and-publish.yml.