tostada-cli

Scaffold full-stack Phoenix + Vite projects with your choice of client framework, from the tostada boilerplate.

Quick start

npx tostada-cli@latest create

This launches an interactive wizard that walks you through:

1. Project name — enter a CamelCase or lowercase name (e.g. SpaceInvaders, acme)
2. Deployment hostname — optional, replaces example.com throughout the project
3. Variant — pick the client framework (see Variants)
4. Addon selection — toggle features like Threlte (3D), Docker, etc.
5. Confirmation — review derived names, variant, and selected addons before proceeding

The CLI then downloads the boilerplate, renames everything to match your project, overlays the chosen client variant, applies addon configuration, installs dependencies, and verifies compilation.

Variants

Every variant ships the same JSON auth flow, the same WebSocket plumbing, and the same /login and /register SPA routes. You pick the client framework; the rest stays consistent.

| Variant | Stack | Default? | | --- | --- | --- | | sveltekit-threlte | SvelteKit 2 + Threlte 8 + Three.js | ✅ | | sveltekit | Plain SvelteKit 2 (no 3D) | | | sveltekit-sv | SvelteKit via npx sv create + Phoenix overlay | | | react-shadcn | Vite + React 19 + Tailwind + shadcn/ui | |

See the installer docs for what each variant includes.

Non-interactive mode

Pass the project name as an argument to skip the prompts and use defaults:

npx tostada-cli@latest create MyApp                              # default variant (sveltekit-threlte)
npx tostada-cli@latest create MyApp --variant react-shadcn
npx tostada-cli@latest create MyApp --variant sveltekit --addons docker

You can customize non-interactive runs with flags:

npx tostada-cli@latest create MyApp \
  --variant react-shadcn \
  --host app.mysite.com \
  --addons "-threlte,docker" \
  --no-install \
  --no-verify

Flags

| Flag | Description | | --- | --- | | --variant <id> | Pick a client variant (one of the four above; defaults to sveltekit-threlte) | | --host <hostname> | Set the deployment hostname (replaces example.com in config files) | | --addons <modifiers> | Comma-separated addon modifiers (see Addon modifiers) | | --no-install | Skip mix deps.get and npm install | | --no-verify | Skip post-install compilation checks |

What it does

When you run tostada create, the CLI performs these steps in order:

1. Download the boilerplate

Fetches the latest tarball from gamedev-company/tostada on GitHub and extracts it into a new directory named after your project (in snake_case).

2. Rename the project

Your project name is derived into three forms:

| Input | snake_case | ModuleCase | Human Readable | | --- | --- | --- | --- | | SpaceInvaders | space_invaders | SpaceInvaders | Space Invaders | | acme | acme | Acme | Acme |

These are used to rename Phoenix server directories and replace placeholder names across all source files. The replacement order is specific to avoid partial matches:

1. TostadaWeb → {Module}Web
2. Tostada → {Module}
3. :tostada → :{snake_name} (Elixir atom)
4. tostada → {snake_name}
5. example.com → {hostname} (if provided)

Replacements are applied to .ex, .exs, .heex, .eex, .js, .ts, .json, .md, .sh, .yml, .yaml, .toml, .css, .html, and .svelte files. Build artifacts (_build, deps, node_modules, .svelte-kit) are skipped.

3. Overlay the client variant

The selected variant's client tree is written into client/ (or, for sveltekit-sv, generated via npx sv create and overlaid with the Phoenix auth wiring).

4. Apply addons

Each addon defines actions that run when it is enabled or disabled. See Addons below.

5. Install dependencies

Unless --no-install is passed:

• Runs mix deps.get in the server/ directory
• Runs npm install in the client/ directory

6. Verify compilation

Unless --no-verify or --no-install is passed:

• Runs mix compile --warnings-as-errors (non-fatal if warnings exist)
• Runs the variant's check command (e.g. npm run check) (non-fatal if issues exist)

Addons

Addons are toggled during project creation. Each addon defines what happens when it is enabled and when it is disabled. Available addons depend on the selected variant.

Available addons

| Addon | Default | Depends on | Description | | --- | --- | --- | --- | | threlte | on | — | Threlte / Three.js for 3D scene rendering | | model_pipeline | on | threlte | GLTF/GLB → Svelte component build pipeline | | docker | off | — | Dockerfile + docker-compose for containerized dev/deploy |

Addon modifiers

The --addons flag accepts a comma-separated string of modifiers that start from the default set:

| Modifier | Effect | | --- | --- | | -threlte | Remove threlte from defaults | | +docker | Add docker to defaults | | docker | Same as +docker |

Examples:

# Defaults minus Threlte (also removes model_pipeline due to dependency)
npx tostada-cli create MyApp --addons "-threlte"

# Defaults plus Docker
npx tostada-cli create MyApp --addons "+docker"

# Defaults minus Threlte, plus Docker
npx tostada-cli create MyApp --addons "-threlte,docker"

Dependency resolution

Addons can declare dependencies on other addons. If a dependency is disabled, the dependent addon is automatically disabled too. For example, disabling threlte also disables model_pipeline.

Addon actions

When an addon is disabled, its when_disabled actions run (e.g. removing npm packages, deleting files). When enabled, its when_enabled actions run (e.g. copying template files). Available action types:

• npm_remove / npm_dev_remove — remove packages from client/package.json
• npm_add / npm_dev_add — add packages to client/package.json
• file_copy — copy and template-substitute files from the addon templates directory
• file_replace — replace a project file with a template
• file_delete — delete files or directories
• makefile_remove_targets — remove Make targets and clean up .PHONY declarations

Prerequisites

• Node.js 18+ (uses native fetch and ES modules)
• Elixir and Mix (for Phoenix server dependencies and compilation)

Project structure after scaffolding

your_project/
  server/       # Phoenix application (headless API)
  client/       # Your chosen client variant
  Makefile      # Development commands (make dev, make test, etc.)

cd your_project
make install   # mix deps.get + npm install
make db.setup  # createdb + migrate + seed
make dev       # Phoenix on :4000 + Vite on :5173

License

MIT