@stackable-labs/cli-app-extension

CLI for scaffolding new Stackable App Extension projects.

Quick Start

npx @stackable-labs/cli-app-extension@latest create my-extension

Or run interactively with no arguments:

npx @stackable-labs/cli-app-extension@latest create

Important: Always include @latest to ensure you get the most recent version. Both npx and pnpm dlx aggressively cache packages.

Interactive Mode

When run without all required flags, the CLI guides you through a step-by-step prompt flow:

| Step | Prompt | Description | |---|---|---| | 1 | App | Select the App you are building an Extension for (fetched live from the API) | | 2 | Name | Display name for your Extension (e.g. My Commerce Extension) | | 3 | Targets | Multiselect from the Surface targets/slots exposed by the selected app | | 4 | Extension Port | Dev server port for the Extension (default: 6543) | | 5 | Preview Port | Dev server port for the Preview host (default: 6544) | | 6 | Directory | Output directory path (default: kebab-case of name) | | 7 | Confirm | Review all selections before scaffolding |

CLI Flags

Usage: create-extension [name] [options]

Options:
  --extension-port <port>    Extension dev server port (skips port prompt)
  --preview-port <port>      Preview host dev server port (skips port prompt)
  --skip-install             Skip package manager install after scaffolding
  --skip-git                 Skip git initialization
  -h, --help                 Display help

Local Development

To run the CLI locally from source against the live API:

pnpm build
pnpm cli

Or pass flags directly:

pnpm cli -- --skip-install --skip-git

Scaffolded Project Structure

my-extension/
├── packages/
│   ├── extension/           ← Extension source (Vite + React)
│   │   ├── src/
│   │   │   ├── index.tsx    ← Extension entry point
│   │   │   └── surfaces/    ← One component per selected target slot
│   │   ├── manifest.json    ← Extension manifest (id, targets, permissions)
│   │   └── .env             ← EXTENSION_PORT, PREVIEW_PORT
│   └── preview/             ← Preview host app (Vite + React)
│       └── src/
│           └── App.tsx      ← Host app wiring up the extension
├── turbo.json
└── package.json

dev Command

Start local dev servers with a public Cloudflare tunnel for testing:

pnpm preview

Usage: stackable-app-extension dev [options]

Options:
  --dir <path>               Project root (default: cwd)
  --extension-port <port>    Override Extension port
  --preview-port <port>      Override Preview port
  --no-tunnel                Skip tunnel, just run vite dev
  -h, --help                 Display help

The dev command:

1. Reads .env.stackable for cached App/Extension context (prompts if missing)
2. Starts Cloudflare tunnels for both extension and preview servers
3. Starts Vite dev servers with hot-reload
4. Displays a Host App Query Param you can append to your host app URL to test against the real deployed host

Host App Override

The dashboard displays a query param like:

?_stackable_dev=ext-123%3Ahttps%3A%2F%2Fabc.trycloudflare.com

Append this to your deployed host app URL to override the extension's bundleUrl in your browser session only. The @stackable-labs/embeddables SDK detects this param and loads from your tunnel instead of the production bundle. No DB changes, no shared state — each developer gets isolated overrides.

Note: The dev command never updates the bundleUrl in the database. It is purely local.

Development Workflow

cd my-extension
pnpm install     # if --skip-install was used
pnpm dev         # starts both Extension + Preview with hot-reload

The preview host runs at the configured preview port and hot-reloads whenever the Extension changes.

Troubleshooting

Stale CLI version after update

Both npx and pnpm dlx cache downloaded packages. If you're seeing an older version after a new release:

npx — Always use @latest and clear the cache if needed:

npx @stackable-labs/cli-app-extension@latest create

# If still stale, clear the npx cache:
npx clear-npx-cache

pnpm dlx — Force a fresh resolve:

pnpm dlx --recreate-lockfile @stackable-labs/cli-app-extension@latest create

Note: After a new version is published to npm, there may be a brief delay (up to ~15 minutes) before the npm CDN propagates the update.

Requirements

• Node 20+
• pnpm (recommended) or npm/yarn