Skip to content
BranchesTags

Repository files navigation

Theo

create-theo · the Build (scaffold) layer of the Theo ecosystem

One command. Seven languages. A real backend in 60 seconds.

npm create theo@latest — production-ready scaffolding for AI agents and the apps around them.

The scaffold verb of Chat. Build. Deploy. — chat with TheoCode, scaffold here, ship on TheoCloud. Multi-language, multi-runtime, no vendor lock-in.

npm version monthly downloads license

npm create theo@latest

Pick the language. We'll ship the boilerplate.

There is a version of starting a new project that doesn't involve a checklist.

No copy-pasting CORS middleware. No reinventing graceful shutdown. No wiring up health probes for the third time this quarter. No remembering whether it's tsc --noEmit or npm run typecheck. No "wait, what was the npm script for migrations again?"

You pick a language. You pick a stack. You get a project — with the things every real backend needs already wired in. Then you build the only part that matters: your product.

What you'd ship

  • A real backend, in any language. Pick Go, Python, Rust, or Java for the team's strengths. Pick Node for shared types with the frontend. TheoCreate doesn't force TypeScript to get nice scaffolding.
  • A multi-tenant SaaS in a weekend. monorepo-turbo (Express + Next.js) or monorepo-go (Go workspaces). Auth, queue, Postgres — three flags. Deploy to TheoCloud in 4 minutes.
  • An API for your AI agent. node-fastify + --add auth-jwt,queue and you have a job-queue-backed API the agent can hit. Pair with TheoKit for the frontend surface.
  • A migration off a 2022 starter. Modern toolchain — Next.js 16, Tailwind v4, ESLint flat config, strict TypeScript. Replace one file at a time.
  • Internal microservices. go-api for performance, python-fastapi for ML, rust-axum for safety — all with the same operational shape (logging, health, shutdown, CI).
  • Worker / job-runner. node-worker, optionally with BullMQ or Asynq for jobs. Same Dockerfile, same health probes, same deploy story as the API.

Why TheoCreate

The create-X ecosystem has one shape per framework. create-next-app ships Next.js. create-vite ships Vite. create-t3-app ships Next.js + tRPC. Pick a different language and you're back to copy-paste boilerplate or a half-maintained generator.

TheoCreate is one CLI across the languages your team actually uses.

Capability TheoCreate create-next-app create-vite create-t3-app Roll your own
Languages covered Node · Go · Python · Rust · Java · Ruby · PHP Node Node Node (you)
Frameworks per language Multiple (Express, Fastify, NestJS, FastAPI, Axum, Spring, Sinatra, Slim, …) Next.js only Frontend-only Next.js only (you)
Composable modules (Redis, auth, queue) Flag-driven DIY DIY Pre-bundled DIY
Database + ORM + docker-compose wired --database flag DIY DIY Yes (Prisma) DIY
Monorepo templates 7 (Turbo · Go · Python · Rust · Java · Ruby · PHP) DIY DIY Limited DIY
Health probes + graceful shutdown by default Yes DIY DIY DIY DIY
Package-manager auto-detect npm · pnpm · yarn · bun Limited Limited Limited DIY
--dry-run preview Yes No No No N/A
License Apache-2.0 MIT MIT MIT N/A

create-next-app ships Next.js. TheoCreate ships the project you'd actually build.

How it works

Below this line, full technical vocabulary is in play. Quick Start, the 19 templates, CLI flags, styling options, modules, database, package-manager auto-detection, preview mode.

Quick Start

npm create theo@latest
cd my-project
npm run dev

Pick a stack, answer a few prompts, start building. Deploy to any platform — Theo, Docker, Railway, Fly.io, or your own infra.

Other package managers

The CLI auto-detects your package manager and adapts all commands accordingly.

# pnpm
pnpm create theo

# yarn
yarn create theo

# bun
bun create theo

Templates

API / Backend

Template Stack Default Port
node-express Node.js + Express 3000
node-fastify Node.js + Fastify 3000
node-nestjs NestJS (TypeScript) 3000
go-api Go stdlib (net/http) 8080
python-fastapi Python + FastAPI 8000
rust-axum Rust + Axum + Tokio 8080
java-spring Java + Spring Boot 8080
ruby-sinatra Ruby + Sinatra + Puma 4567
php-slim PHP + Slim Framework 8000

Frontend / Fullstack

Template Stack Type Default Port
node-nextjs Next.js 16 (App Router, TypeScript) Frontend / SSR 3000
fullstack-nextjs Next.js 16 + API Routes (TypeScript) Fullstack 3000

Monorepo

Template Stack Apps Ports
monorepo-turbo Turborepo (Express + Next.js) API + Web 3001 / 3002
monorepo-go Go Workspaces API + Worker 8080 / 8081
monorepo-python uv Workspace (FastAPI + Worker) API + Worker 8000 / 8001
monorepo-rust Cargo Workspaces (Axum + Tokio) API + Worker 8080 / 8081
monorepo-java Gradle multi-project (Spring Boot) API + Worker 8080 / 8081
monorepo-ruby Bundler (Sinatra + WEBrick) API + Worker 4567 / 4568
monorepo-php Composer (Slim + CLI) API + Worker 8000 / 8001

Worker

Template Stack Default Port
node-worker Node.js 3000

External Templates

Use any GitHub repository as a template:

npm create theo@latest my-app --template user/repo
npm create theo@latest my-app --template user/repo#branch

Every template is production-ready out of the box: CORS, structured JSON logging, error handling, graceful shutdown, health endpoints (GET /health + GET /ready), Dockerfile, linting, example test, and a CI workflow.

CLI Options

Flag Description
--template, -t Skip template prompt (node-express, go-api, php-slim, user/repo, etc.)
--styling, -s Styling for frontend templates (tailwind, shadcn, daisyui, etc.)
--database, -d Add PostgreSQL with ORM (Prisma, GORM, SQLAlchemy, Diesel, Spring Data JPA, Sequel, or Doctrine)
--add, -a Add modules: redis, auth-jwt, auth-oauth, queue (comma-separated)
--dry-run Preview what would be created without writing any files
--verbose, -v Show detailed output during scaffolding
--help Show help 
# Interactive (prompts for everything)
npm create theo@latest

# Non-interactive
npm create theo@latest my-api --template go-api

# With database + modules
npm create theo@latest my-app -t node-express -d --add redis,auth-jwt

# Full stack: database + Redis + Auth + Queue
npm create theo@latest my-app -t node-express -d --add redis,auth-jwt,queue

# Frontend with Tailwind + shadcn/ui
npm create theo@latest my-app -t node-nextjs -s shadcn

# Preview without creating files
npm create theo@latest my-app -t node-express -d --add redis --dry-run

# External GitHub template
npm create theo@latest my-app -t user/repo

# CI mode (no prompts, no install, no git init)
CI=true npx create-theo my-app --template node-express

Frontend Templates

Frontend templates (node-nextjs, fullstack-nextjs, monorepo-turbo) are TypeScript-first and include modern tooling out of the box:

Feature Implementation
TypeScript .tsx/.ts throughout, strict mode (noUnusedLocals, noUnusedParameters, noUncheckedIndexedAccess), @/* path aliases
React 19.2 Latest stable with Server Components support
Next.js 16 App Router, Turbopack (default), proxy.ts, standalone output
Tailwind CSS v4 @import "tailwindcss" — zero config, no tailwind.config.js
ESLint ESM flat config (eslint.config.mjs) with eslint-config-next/core-web-vitals + typescript rules
Dark mode ThemeProvider with next-themes, system preference detection
shadcn/ui ready components.json (radix-nova style) — run npx shadcn add button
cn() utility lib/utils.ts with clsx + tailwind-merge
Prettier prettier-plugin-tailwindcss with tailwindStylesheet + tailwindFunctions for class sorting in cn()/cva()
Type checking npm run typecheck via tsc --noEmit
Node.js engines.node >= 20.9 declared (Next.js 16 requirement)

Project structure (node-nextjs)

my-app/
├── src/
│   ├── app/
│   │   ├── layout.tsx          # Root layout with ThemeProvider
│   │   ├── page.tsx            # Home page
│   │   ├── error.tsx           # Error boundary
│   │   ├── not-found.tsx       # 404 page
│   │   └── api/
│   │       ├── health/route.ts # Liveness probe
│   │       └── ready/route.ts  # Readiness probe
│   ├── proxy.ts                # Request logging (Next.js 16 proxy)
│   └── instrumentation.ts     # Logger + graceful shutdown
├── components/
│   └── theme-provider.tsx      # Dark mode provider
├── lib/
│   └── utils.ts                # cn() utility
├── hooks/                      # Custom hooks (empty, ready to use)
├── components.json             # shadcn/ui CLI config (radix-nova)
├── eslint.config.mjs           # ESLint flat config (Next.js + TypeScript rules)
├── tsconfig.json               # TypeScript strict with @/* aliases
├── next.config.mjs             # ESM config, standalone output
├── .prettierrc                 # Tailwind class sorting + tailwindStylesheet
├── Dockerfile                  # Production-optimized
└── theo.yaml                   # Deploy config

Monorepo structure (monorepo-turbo)

my-mono/
├── apps/
│   ├── api/                    # Express API (JavaScript)
│   └── web/                    # Next.js 16 frontend (TypeScript)
├── packages/
│   ├── shared/                 # Shared utilities (TypeScript)
│   ├── eslint-config/          # Centralized ESLint config
│   └── typescript-config/      # Centralized TypeScript config (base + nextjs)
├── turbo.json                  # Build orchestration + caching
└── package.json                # npm workspaces root

Styling

Pass --styling to choose a CSS framework for frontend templates. Applied at scaffold time with full configuration.

Option What you get
none Plain CSS (default)
tailwind Tailwind CSS v4 with @tailwindcss/postcss
shadcn Tailwind v4 + shadcn/ui (OKLCH colors, dark mode, @theme inline, tw-animate-css)
daisyui Tailwind v4 + daisyUI component classes
chakra Chakra UI with emotion + ChakraProvider
mantine Mantine with PostCSS preset + MantineProvider
bootstrap Bootstrap 5
bulma Bulma CSS

shadcn/ui integration

When you choose shadcn, the template comes fully configured:

# Scaffold with shadcn
npm create theo@latest my-app -t node-nextjs -s shadcn

# Then add components
cd my-app
npx shadcn add button
npx shadcn add card dialog

The generated globals.css includes a complete OKLCH color system with 44 CSS custom properties for light and dark modes, mapped to Tailwind utilities via @theme inline.

Add-on Modules

Composable modules added at scaffold time via --add or interactive checkbox prompt.

Module What it generates Languages
redis Redis client + connection helper + docker-compose service Node.js, Go, Python, Rust, Java, Ruby, PHP
auth-jwt JWT middleware + token generation helpers Node.js, Go, Python, Rust, Java, Ruby, PHP
auth-oauth OAuth/OIDC token validation middleware Node.js, Go, Python, Rust, Java, Ruby, PHP
queue Job queue + worker setup (auto-includes Redis) Node.js (BullMQ), Go (Asynq), Python (arq), PHP (Symfony Messenger)

auth-jwt and auth-oauth are mutually exclusive — pick one or the other.

Generated per language

Module Node.js Go Python Rust Java Ruby PHP
Redis ioredis go-redis redis-py redis crate Spring Data Redis redis gem Predis
Auth JWT jsonwebtoken golang-jwt pyjwt jsonwebtoken crate JJWT ruby-jwt firebase/php-jwt
Auth OAuth openid-client go-oidc authlib openidconnect Spring OAuth2 omniauth Guzzle
Queue BullMQ Asynq arq — — — Symfony Messenger

Database

Pass --database to get a fully configured database layer:

Language ORM What you get
Node.js Prisma Schema, client, migration scripts
Go GORM Connection helper, User model
Python SQLAlchemy Engine, session, User model
Rust Diesel Connection helper, config
Java Spring Data JPA Entity, Repository, auto-DDL
Ruby Sequel Connection, User model
PHP Doctrine DBAL Connection helper

All database setups include:

  • docker-compose.yml with Postgres 16 (healthcheck, persistent volume)
  • .env pre-configured for local development
  • Ready to run: docker compose up -d

When combined with --add redis, both Postgres and Redis appear in the same docker-compose.yml.

Build artifacts

theo-stacks templates ship application source code (manifests, source files, configuration). They do not ship Dockerfiles. The Theo build pipeline runs theo-packs which detects each template's language/framework and generates an optimized multi-stage Dockerfile at deploy time.

If you fork a template and want to deploy outside Theo, run theopacks-generate yourself, or write your own Dockerfile and use a non-theo-packs build path.

Committing a Dockerfile inside a template directory is an enforced contract violation — a CI test fails the PR (see tests/no_dockerfiles_test.sh).

What's Included in Every Template

Feature Implementation
CORS Language-native middleware (cors, CORSMiddleware, tower-http, etc.)
Structured logging JSON output (pino, slog, logging, tracing, Logback, etc.)
Error handling Central middleware + 404 handler
Graceful shutdown SIGTERM/SIGINT handlers with timeout
Health check GET /health — liveness probe
Readiness check GET /ready — readiness probe (customize for dependency checks)
Dockerfile Generated at deploy time by theo-packs — not committed
.dockerignore Generated at deploy time by theo-packs (per-language template)
Example test Health endpoint test (Jest, Go testing, pytest, cargo test, JUnit, Minitest, PHPUnit)
Linting ESLint, go vet, ruff, clippy, Spotless, RuboCop, PHPStan
CI GitHub Actions workflow
theo.yaml Project config for deployment (apps, framework, ports)

Package Manager Detection

The CLI auto-detects which package manager invoked it and adapts:

Package Manager Detection Install flags
npm Default --no-fund --no-audit --loglevel=error
pnpm npm_config_user_agent Standard
yarn npm_config_user_agent --no-fund
bun npm_config_user_agent or runtime Standard

Output instructions adapt automatically (e.g., pnpm run dev instead of npm run dev). Install noise (funding, audit, ads) is suppressed for a clean experience.

Preview Mode

Preview what a scaffold would create without writing any files:

npm create theo@latest my-app -t node-express -d --add redis,auth-jwt --dry-run
  Dry run — no files will be created

  Project:  my-app
  Template: Node.js — Express
  Database: PostgreSQL (Prisma)
  Modules:  Redis, Auth (JWT)

  Files that would be created in ./my-app/

    .dockerignore
    .env
    .env.example
    .github/workflows/ci.yml
    .gitignore
    Dockerfile
    README.md
    docker-compose.yml
    package.json
    prisma/schema.prisma
    src/index.js
    src/lib/db.js
    src/lib/queue.js
    src/lib/redis.js
    src/middleware/auth.js
    tests/health.test.js
    theo.yaml

  Total: 17 files

Prerequisites

  • Node.js 20.9+ (required to run create-theo and Next.js 16 templates)
  • Docker (optional, for local database/Redis via docker-compose)
  • Theo CLI (optional, for one-command deploy to Kubernetes)

Contributing

We welcome contributions! Whether it's a new template, a module, a bug fix, or documentation improvement.

Adding a template

  1. Create templates/<template-id>/ with all required files
  2. Include theo.yaml, Dockerfile, dockerignore (without dot), gitignore (without dot), and README.md
  3. Implement GET /health, GET /ready, PORT env support
  4. Add CORS, structured JSON logging, error handling, and graceful shutdown
  5. Add linting config and at least one example test
  6. Use {{project-name}} as the placeholder everywhere the project name appears
  7. Register it in create-theo/src/templates.ts
  8. Run the validation suite:
cd create-theo && npm install && npm test
bash scripts/validate-templates.sh

Development

# Install and build the CLI
cd create-theo && npm install && npm run build

# Run tests (205 tests across 12 suites)
npm test

# Stub mode (fast rebuild during development)
npm run dev

# Check that shared configs haven't drifted between frontend templates
bash scripts/check-consistency.sh

# Full smoke test (scaffolds all 19 templates, verifies structure)
bash scripts/validate-templates.sh

Examples

The examples/ directory contains scaffolded projects generated by the CLI — base templates + variants with addons (database, Redis, auth, queue). Browse them to see exactly what create-theo generates.

Status

Honest claims only.

  • Production. 19 templates, 8 styling options, 4 add-on modules, 7 ORMs, package-manager auto-detection, dry-run preview, external GitHub templates — all shipped on npm. Apache-2.0. Validation suite (scripts/validate-templates.sh) covers every template.
  • 205 tests across 12 suites — scaffolding, hooks, error paths, module combinations.
  • CLAUDE.md per scaffolded project. TheoCreate writes a tailored CLAUDE.md (AI assistant instructions) into every scaffolded project — keyed by language, framework, and selected addons.
  • TheoCloud deploy — templates ship with theo.yaml; theo deploy is the canonical PaaS path. TheoCloud itself is pre-release.

License

Apache-2.0

Community

About

Scaffold a production-ready project and deploy it to Kubernetes — no YAML, no Docker, no cluster config.

usetheo.dev

Resources

Readme
Apache-2.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages