The development loop

dev vs run

crisptastic dev [dir]     # watch + recompile + live browser reload
crisptastic run [dir]     # serve once, no watch (closer to a CI check)
crisptastic serve [dir]   # same as run, explicit

Both use the same interpreter, the same routing, the same effect model as a production host. dev only adds file watching, automatic reload, and no-store cache headers. There is no separate "dev build".

Default bind is 127.0.0.1:6174; override with --bind. The dev server is loopback-only and is not meant to face the internet — that is what a host behind a proxy is for.

The loop

1. Edit a .crisp file, a partial, an asset, or crisptastic.toml.
2. The watcher recompiles the affected routes and pushes a reload.
3. A compile error is shown in the terminal with a stable code and never serves a half-rendered page — the previous good version keeps serving until the error is fixed.

Use crisptastic check . and crisptastic routes . anytime for a one-shot compile report and the full resolved route list.

Local configuration

crisptastic.toml holds local defaults; CLI flags override it. The values a simple site needs:

name   = "my-site"
root   = "."
assets = "./assets"
bind   = "127.0.0.1:6174"
sessions = "./.crisptastic/sessions"

[env]
SITE_NAME = "My Site"

[env] values are plain, non-secret, and readable as context.env.KEY. Sessions are written under sessions as local files in development.

Local secrets

Crisptastic reads only the variable names you declare — never your whole environment.

[env_from_process]
STRIPE_SECRET_KEY = "STRIPE_SECRET_KEY"

Provide the value however your OS prefers. On macOS the recommended flow keeps it in the Keychain and exposes it only to the child process:

macrun set my-site dev STRIPE_SECRET_KEY
macrun run my-site dev -- crisptastic dev .

On Linux or CI, export the same name from your platform's secret facility. Nothing is written to a second local store, and secret values never enter the page context or diagnostics.

Capability fakes

Every capability has a deterministic local fake. You can build and click through a page that logs a user in or starts a checkout with no live account and no network. The fake and the real adapter share one contract, so a flow that works locally works on a host.

Running several sites at once

Each site is just a folder with its own crisptastic.toml. Run more than one by giving each a different port:

crisptastic dev ./marketing --bind 127.0.0.1:6174
crisptastic dev ./app       --bind 127.0.0.1:6175

To exercise real domain routing locally — one process, many sites, chosen by Host — run a local host instead and deploy each site into it. That is the same path you use in production, just on loopback.

Telemetry while developing

crisptastic dev . --debug                 # request tracing + events to stdout
crisptastic dev . --debug-file trace.ndjson