@pantoken/scaffold

Scaffold a starter project — with pantoken (Instructure design tokens and icons) already installed and wired in.

Built on Bingo presets: each platform package exports a preset defining its scaffold structure, enabling decentralized template ownership and consistent multi-platform scaffolding.

Usage

npx @pantoken/scaffold components      # plain HTML/CSS (Vite + TS) + @pantoken/components
npx @pantoken/scaffold react           # Vite + React + @pantoken/react
npx @pantoken/scaffold vue             # Vite + Vue 3 + @pantoken/vue
npx @pantoken/scaffold web-components  # Vite + @pantoken/web-components (no framework)
npx @pantoken/scaffold canvas-theme-editor  # Canvas Theme Editor uploads + RCE template starter

# Target a directory other than the current one:
npx @pantoken/scaffold react ./my-app

# Omit the platform (and/or directory) on a TTY to be prompted interactively:
npx @pantoken/scaffold

# Non-interactive (CI-safe): errors instead of prompting for a missing platform/directory
npx @pantoken/scaffold react --dir ./my-app --yes

# Override the auto-detected display language
npx @pantoken/scaffold --lang hu

npx works regardless of which package manager you use. Substitute pnpm dlx, yarn dlx, bunx, or deno run npm: for npx if you prefer — dependencies are installed automatically with whichever one invoked the CLI (detected from npm_config_user_agent), leaving "start the dev server" as the only manual step. Pass --no-install to skip the automatic install.

Run npx @pantoken/scaffold --help for the full flag reference, or npx @pantoken/scaffold completion <shell> to generate a bash/zsh/fish/PowerShell completion script.

Or use it programmatically:

import { scaffoldProject, SCAFFOLD_PLATFORMS } from "@pantoken/scaffold";

await scaffoldProject("react", "./my-app");

API

• scaffoldProject(platform, dir?): Promise<string[]> — write a starter project template for a ScaffoldPlatform into dir (defaults to "."). Its basename (or "pantoken-app" for ".") is passed as the project name to the Bingo preset. Returns the paths written.
• SCAFFOLD_PLATFORMS: readonly ScaffoldPlatform[] — every scaffoldable platform key (discovered from available presets at build time, plus legacy template-only platforms like canvas-theme-editor that aren't backed by a preset yet).
• ScaffoldPlatform — the platform union, derived from the preset registry and the legacy template map.

CLI flags

| Flag | Description | | --------------------- | ------------------------------------------------------------------------- | | [platform] | Platform to scaffold (prompted interactively if omitted on a TTY) | | -d, --dir <path> | Target directory (prompted interactively if omitted on a TTY) | | -y, --yes | Never prompt; error instead of prompting for a missing platform/directory | | --no-install | Skip automatically installing dependencies after scaffolding | | -l, --lang <tag> | Language for the CLI and the scaffolded project (e.g. "hu") | | --theme <name> | Token theme: rebrand (default), canvas, canvasHighContrast | | --theme-mode <mode> | Rebrand token mode: light (default) or adaptive | | -v, --version | Print the installed version | | -h, --help | Print usage | | completion <shell> | Generate a bash/zsh/fish/PowerShell completion script |

The CLI auto-detects its language from --lang > LC_ALL/LANG > the runtime's Intl locale > English, falling back to English for any untranslated string. Region subtags survive when pantoken supports them (pt_BR.UTF-8 resolves to pt-BR) and narrow to the base language when it doesn't (es_MX resolves to es).

The resolved locale also shapes the generated project: entry markup gets a matching lang/dir pair (so --lang ar scaffolds <html lang="ar" dir="rtl">), and the project README is written in that language where a translation exists. An explicit --lang must name a supported locale — it errors rather than silently falling back, since the value is written into the scaffolded files.

Architecture

Bingo Preset System

Each platform package (@pantoken/components, @pantoken/react, @pantoken/vue, @pantoken/web-components) exports a Bingo preset via ./scaffold-preset entry point. Presets are:

• Built on @pantoken/scaffold-base: a shared Bingo Base defining common options (projectName) and blocks (cssdoc.json configuration, wrapper app-shell layout context).
• Auto-discovered at build time: scripts/scan-presets.ts scans packages and generates a static preset-ledger.ts registry.
• Decentralized ownership: each platform defines its own preset, templates, and scaffold behavior without coordination.

Template Rendering

scaffoldProject uses bingo-stratum's producePreset to render presets:

1. Validate the platform against the preset ledger.
2. Invoke the preset with the project name as an option.
3. Write the produced files to the target directory.
4. Fall back to the legacy SCAFFOLDS template system if preset rendering fails (for backward compatibility).

Wrapper Layout

Every scaffolded starter's entry markup follows the wrapper app-shell layout from @pantoken/plugin-layouts — the container/header/content skeleton is generated at build time from that package's wrapper.css cssdoc (@part/@slot tags), so every platform stays in sync automatically when the layout changes. See scripts/wrapper-layout.ts.

Integration with @pantoken/ai

@pantoken/ai's pantoken-ai scaffold <platform> command wraps this package and additionally installs pantoken's agent assets (AGENTS.md, editor/agent rules, and skills for maintained apps and standalone browser/email mockups) into the same directory.

License

MIT