launch-stackwright-pro

🚢 Scaffold a new Stackwright Pro project in one command — complete with OpenAPI integration, RBAC auth, mock users, and the otter raft ready to build your site for you.

How It Works

This package uses the scaffold hooks system (@stackwright-pro/scaffold-hooks) to automatically wire up Pro features:

1. Import hooks → Auto-registers Pro packages during scaffolding
2. Call scaffold() → Hooks automatically add:
   • Pro dependencies (@stackwright-pro/mcp, @stackwright-pro/otters, etc.)
   • MCP server configuration in .code-puppy.json
   • Role-based dev scripts (dev:admin, dev:analyst, dev:viewer)
3. Post-processing → Copies Pro templates, adds auth config, generates README
4. Auto-install → pnpm install runs automatically after scaffolding — citizen developers get a project ready to use without knowing what a package manager is

Quick Start

# Works — project created in $cwd/my-app
pnpx @stackwright-pro/launch-stackwright-pro --name my-app -y
# Dependencies install automatically (~7s)
cd my-app
npx @stackwright-pro/raft   # Start the otter raft

# Equivalent explicit form
pnpx @stackwright-pro/launch-stackwright-pro my-app --name my-app -y

With an OpenAPI Spec

npx launch-stackwright-pro my-app --spec ./my-api.yaml --yes

The spec gets copied into specs/ and wired into stackwright.yml. The prebuild script generates types & a client on the first pnpm dev.

What Gets Created

my-app/
├── pages/
│   ├── _app.tsx              # Pro _app with AuthProvider
│   ├── _document.tsx
│   ├── index.ts
│   └── [...slug].tsx
├── lib/
│   └── mock-auth.ts          # Dev-mode mock users (admin/analyst/viewer)
├── scripts/
│   └── prebuild.js           # Reads stackwright.yml → runs OpenAPI plugin
├── specs/                    # Only if --spec was provided
│   └── <your-spec>.yaml
├── node_modules/
│   ├── @stackwright/otters/       # 🦦 OSS otters (brand, theme, page, foreman)
│   └── @stackwright-pro/otters/   # 🦦 Pro otters (api, data, dashboard, foreman)
├── stackwright.yml           # Theme + auth + integrations config
├── next.config.js            # Pro config (transpile pro pkgs + yaml-loader)
├── yaml.d.ts                 # TS declarations for YAML imports
└── package.json              # OSS + Pro dependencies (via scaffold hooks)

CLI Options

launch-stackwright-pro [directory]

Options:
  --name <name>        Project name (used in package.json)
  --title <title>      Site title shown in the app bar and browser tab
  --theme <themeId>    Theme ID (e.g., corporate, creative, minimal)
  --force              Overwrite existing directory
  --skip-otters        Skip otter raft setup
  -y, --yes            Skip prompts, use defaults
  --spec <paths...>    Paths to OpenAPI specs (can be specified multiple times)
  --spec-name <name>   Name for the API integration (default: derived from filename)
  -V, --version        Output the version number
  -h, --help           Display help

Role-Based Dev Scripts

The scaffolded project includes convenience scripts for developing against different mock roles:

pnpm dev            # No mock auth — unauthenticated
pnpm dev:admin      # MOCK_USER=admin
pnpm dev:analyst    # MOCK_USER=analyst
pnpm dev:viewer     # MOCK_USER=viewer

What's Different from OSS launch-stackwright?

| Feature | OSS | Pro | | ------------------- | --- | --- | | Base scaffold | ✅ | ✅ | | Otter raft | ✅ | ✅ | | RBAC auth | ❌ | ✅ | | Mock users | ❌ | ✅ | | OpenAPI integration | ❌ | ✅ | | Prebuild code-gen | ❌ | ✅ | | YAML config loading | ❌ | ✅ |

Scaffold Hooks

The @stackwright-pro/scaffold-hooks package handles Pro package injection automatically via the hooks system:

| Hook | What It Does | | ------------------------- | -------------------------------------------------------- | | pro-dependencies | Adds @stackwright-pro/* packages, fixes workspace refs | | pro-mcp-config | Configures Pro MCP server in .code-puppy.json | | verify-pro-installation | Prints success message after install |

Docs

See the main Stackwright Pro documentation for architecture details, auth deep-dives, and deployment guides.

Starting the Otter Raft

cd my-app
npx @stackwright-pro/raft

The raft verifies otter integrity, loads project context from .stackwright/init-context.json, and spawns code-puppy in foreman mode. Tell the foreman about your specs in natural language — it coordinates the API, auth, data, and page otters to build your app.

All state lives in .stackwright/ — you can interrupt and resume at any time.