Quick start
Create a pracht app, run it locally, and ship your first production build.
On this page
Requirements
Node 22.18 or newer. Scaffolded apps include an .nvmrc and an engines.node
field, so hosts and CI pick a supported version.
Create a project
pnpm create pracht my-appnpm create pracht@latest my-appyarn create pracht my-appbunx create-pracht my-appThe CLI asks for:
- an adapter: Node.js, Cloudflare Workers, Netlify, Vercel, or a static export
(you can switch later in
vite.config.ts); - a router: the explicit
src/routes.tsmanifest, or file-systemsrc/pages/; - whether to add Tailwind CSS;
- whether to add agent tooling.
Pick the pages router if file-based routing is enough. You can eject it to a manifest later when you need per-route shells or middleware, explicit route ids, path-prefix groups, or webhook ISG; see Pages router.
To skip the prompts in CI or scripts, pass the choices as flags:
pnpm create pracht my-app --adapter=node --router=manifest --template=tailwind --yes
pnpm create pracht my-app --adapter=cf --router=pages --no-tailwind --no-agent-tools --yes
pnpm create pracht my-app --adapter=vercel --skip-install --yesnpm create pracht@latest my-app -- --adapter=node --router=manifest --template=tailwind --yes
npm create pracht@latest my-app -- --adapter=cf --router=pages --no-tailwind --no-agent-tools --yes
npm create pracht@latest my-app -- --adapter=vercel --skip-install --yesyarn create pracht my-app --adapter=node --router=manifest --template=tailwind --yes
yarn create pracht my-app --adapter=cf --router=pages --no-tailwind --no-agent-tools --yes
yarn create pracht my-app --adapter=vercel --skip-install --yesbunx create-pracht my-app --adapter=node --router=manifest --template=tailwind --yes
bunx create-pracht my-app --adapter=cf --router=pages --no-tailwind --no-agent-tools --yes
bunx create-pracht my-app --adapter=vercel --skip-install --yes| Flag | Effect |
|---|---|
--adapter=<target> |
node (default), cf, netlify, vercel, or static |
--router=<router> |
manifest (default) or pages |
--template=<template> |
minimal or tailwind; --tailwind and --no-tailwind set the same thing |
--agent-tools[=<set>] |
Add .claude/skills/, .mcp.json, and AGENTS.md; core (default) or full skills |
--no-agent-tools |
Skip agent files |
--yes, -y |
Accept defaults and skip all prompts |
--skip-install, --no-git |
Skip dependency install, or git init and the initial commit |
--json |
Print a JSON summary instead of prose |
--dry-run |
List the files that would be created without writing them |
Project structure
A manifest-router scaffold:
my-app/
src/
routes.ts # Route manifest (the central wiring file)
routes/home.tsx # First page component + loader
routes/not-found.tsx # Not-found page, wired from the manifest
shells/public.tsx # Layout wrapper
api/health.ts # Sample API endpoint (not in static exports)
vite.config.ts # Vite + pracht plugin config
package.jsonA pages-router scaffold uses src/pages/ instead:
my-app/
src/
pages/_app.tsx # App shell
pages/index.tsx # First page component + loader
pages/404.tsx # Not-found page, wired automatically
api/health.ts # Sample API endpoint (not in static exports)
vite.config.ts # Vite + pracht plugin config
package.jsonDepending on your choices, the starter also includes Tailwind's
src/styles/global.css, an adapter file (wrangler.jsonc, netlify.toml, or
Dockerfile), and agent files under .claude/skills/ plus .mcp.json.
TypeScript settings pracht requires
Set moduleResolution to "bundler" (or "node16" / "nodenext").
pracht's packages are ESM-only and publish their types through exports:
{
"compilerOptions": {
"moduleResolution": "bundler",
"jsx": "react-jsx",
"jsxImportSource": "preact",
"types": ["vite/client", "@pracht/vite-plugin/virtual"]
}
}With the legacy "moduleResolution": "Node" the app still builds and runs, but
tsc fails every @pracht/core import with TS2307. create-pracht
scaffolds the right value, and pracht doctor warns about the old one.
See Import paths for the matching
tsconfig.client.json.
pnpm typecheck checks both tsconfig files with
tsrs, a tsc-compatible Rust port of the
TypeScript 7 compiler that create-pracht installs in place of typescript.
To use tsc instead, install typescript and replace tsrs with tsc in the
typecheck script.
Development
cd my-app
pnpm devcd my-app
npm run devcd my-app
yarn devcd my-app
bun run devOpen http://localhost:3000 and edit the first page: src/routes/home.tsx
with the manifest router, src/pages/index.tsx with the pages router. The
browser updates on save. Set --port or PORT to use another port.
The dev script generates typed routes, API calls, and capabilities before
starting, then keeps those types current while you edit. Run pnpm typecheck
locally or in CI to regenerate the app types and check both server and browser
code. After --skip-install, install dependencies before running either script.
Build output
pnpm buildnpm run buildyarn buildbun run buildThe build writes dist/client/ (static assets and prerendered SSG pages) and
dist/server/ (the server bundle in the shape your adapter needs). For a
Node.js target, run the server directly:
node dist/server/server.jsDeploy
Cloudflare, Netlify, and Vercel scaffolds include the platform config and a
deploy script.
Cloudflare Workers
pnpm create pracht my-app --adapter=cf --yes
cd my-app
pnpm run deploynpm create pracht@latest my-app -- --adapter=cf --yes
cd my-app
npm run deployyarn create pracht my-app --adapter=cf --yes
cd my-app
yarn deploybunx create-pracht my-app --adapter=cf --yes
cd my-app
bun run deployThe script runs pracht build && wrangler deploy. The first run opens a browser
to authorize Wrangler (in CI, set CLOUDFLARE_API_TOKEN instead), then prints
your https://my-app.<your-subdomain>.workers.dev URL.
Add KV, D1, R2, or cron triggers in wrangler.jsonc; bindings arrive as
context.env in loaders and API routes. pracht preview serves the built app
locally through Wrangler.
Vercel
pnpm create pracht my-app --adapter=vercel --yes
cd my-app
pnpm run deploynpm create pracht@latest my-app -- --adapter=vercel --yes
cd my-app
npm run deployyarn create pracht my-app --adapter=vercel --yes
cd my-app
yarn deploybunx create-pracht my-app --adapter=vercel --yes
cd my-app
bun run deployThe script runs pracht build && vercel deploy --prebuilt. The first deploy asks
which Vercel project to link.
Other targets
Node.js (including Docker), Netlify, and static hosts are each one adapter swap
in vite.config.ts. See Deployment for per-platform
commands and Adapters for what each adapter emits.
Next steps
Build your first shared operation: a validated note form, session protection, an agent call, and a production build in the runnable example.
- Routing: declare routes, shells, middleware, and render modes in
src/routes.ts. - Rendering modes: choose SSR, SSG, ISG, or SPA per route.
- Data loading: fetch data in loaders and handle mutations in API routes.
- Adapters: deploy to Node.js, Cloudflare Workers, Netlify, Vercel, or a static host.
- Agents overview: expose typed operations to agents and to your own UI.
- Coding agents: connect a coding agent to these docs with
claude mcp add --transport http pracht-docs https://pracht.resynapse.dev/mcp.