Celtrix

Set up your web app first. Then build it with AI.

Celtrix is a CLI that generates a full-stack web app that already runs: frontend, API and database, connected and configured, with a guide that explains how to run it.

Quick start · What you get · Generated project · Build with AI · Contributing

npx celtrix my-app

---

Why Celtrix

Every new web app starts with the same hour of glue work: create the frontend, create the API, pick an ORM, write the env loading, get the database running, make the three talk to each other. None of it is your product, and all of it has to be right before your product can start.

AI coding assistants made features fast, but they did not make this part reliable. Ask one to set up a project and you often get:

• Stale setup. Commands, config formats and package versions remembered from older code.
• Pieces that don't connect. Wrong ports, missing proxy, CORS errors, an ORM that can't find DATABASE_URL.
• A new architecture every session. Nothing stable for the next change to stay consistent with.
• Context spent on boilerplate. Tokens and review time go to config instead of features.

Celtrix does the setup deterministically. The same choices always produce the same project, created with the frameworks' own CLIs and wired together by generators covered by an end-to-end test that builds and runs a real app. You, or your AI assistant, start from a working app with one complete example feature to build on.

Celtrix is a scaffolder, not an AI tool. It makes no AI calls, and what it generates is plain code you own, with no runtime dependency on Celtrix.

---

Contents

• Quick start
• What you get
• The generated project
• Building with AI
• Supported stacks
• CLI reference
• Troubleshooting
• Contributing

---

Quick start

Requirements: Node.js 20.19+ or 22.12+ (required by the Vite versions Celtrix installs). You also need Docker if you want Celtrix to run your database, and Bun if you pick it as the runtime.

npx celtrix my-app

Choose Custom Stack and answer seven short steps. Backspace goes back to the previous step. An abridged run:

$ npx celtrix my-app
? Choose your stack: ⚡ Custom Stack

── Customise your tech stack ──

? [1/7] Select a language: TypeScript
? [2/7] Select a frontend framework: React Router
? [3/7] Select a backend framework: Express
? [4/7] Select a runtime environment: Node.js
? [5/7] Select a database: PostgreSQL
? Select a postgres provider: Docker
? [6/7] Select an ORM: Prisma
? [7/7] Proceed with this configuration? Continue
? Choose a package manager: npm
? Do you want to install dependencies? Yes

When it finishes, Celtrix prints the next steps for the stack you picked:

👉 Next Steps:

   1. cd my-app
   2. cp .env.example .env
   3. npm run db:up   # start the database in Docker
   4. npm run db:push   # create the database tables
   5. npm run dev

   📖 Read my-app/CELTRIX_SETUP.md for the full guide to set up and run your app.

Run them and open http://localhost:5173:

---

What you get

---

The generated project

A fullstack custom project (here React Router + Express + PostgreSQL via Docker + Prisma, in TypeScript) looks like this:

my-app/
├── apps/
│   ├── api/                      # Express, Hono or Fastify API
│   │   └── src/
│   │       ├── env.ts            # loads the root .env
│   │       └── index.ts          # /api/health and /api/users
│   └── web/                      # Vite + React app
│       ├── src/
│       │   ├── App.tsx           # welcome page with the live status screen
│       │   ├── components/StackStatus.tsx
│       │   └── lib/api.ts        # typed client for the API
│       └── vite.config.ts        # proxies /api to the API, reads the root .env
├── packages/
│   ├── database/                 # @repo/database, shared by the API
│   │   ├── prisma/schema.prisma  # User model
│   │   └── src/index.ts          # db client, checkConnection(), users helpers
│   └── tsconfig/                 # shared TypeScript config
├── .env.example                  # every variable the code reads
├── docker-compose.yml            # only with the Docker provider
├── CELTRIX_SETUP.md              # how to set up and run this project
├── celtrix.config.json           # the stack you chose
├── turbo.json
└── package.json                  # dev, build and db:* scripts

How the pieces connect

flowchart LR
  Browser --> Web["apps/web<br/>Vite dev server :5173"]
  Web -- "proxies /api" --> API["apps/api<br/>API server :3001"]
  API -- "imports @repo/database" --> DB["packages/database<br/>Prisma or Mongoose"]
  DB --> Engine[("PostgreSQL · MySQL<br/>MongoDB · SQLite")]
  Env[".env at the repo root"] -.-> API
  Env -.-> DB
  Env -.-> Web

A frontend-only project (no backend) is a single app at the project root, exactly as the framework's CLI creates it, plus CELTRIX_SETUP.md and celtrix.config.json.

The proxy, typed API client and status screen are added for the React Router frontend. With the other frontends you get the same monorepo, API and database package, with the frontend exactly as its own CLI creates it.

This is the beginning of the README. Read the rest at the original. Read the full README ↗