tostada-cli

CLI for scaffolding full-stack Phoenix + SvelteKit projects from the tostada boilerplate.

Quick start

npx tostada-cli 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. Addon selection — toggle features like Threlte (3D), Docker, etc.
4. Confirmation — review derived names and selected addons before proceeding

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

Non-interactive mode

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

npx tostada-cli create MyApp

You can customize non-interactive runs with flags:

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

Flags

| Flag | Description | | --- | --- | | --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. Apply addons

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

4. Install dependencies

Unless --no-install is passed:

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

5. Verify compilation

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

• Runs mix compile --warnings-as-errors (non-fatal if warnings exist)
• Runs npm run check via SvelteKit (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

| 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
  client/       # SvelteKit application
  Makefile      # Development commands (make dev, make test, etc.)

License

MIT