ts-template

An opinionated, AI-first TypeScript project template. Batteries included: structured LLM output via AI SDK, markdown prompt templating, PostgreSQL via Drizzle, structured logging, and CLI scripting.

Quick Start

pnpm install
cp .env.example .env
# edit .env with your OPENROUTER_API_KEY and DATABASE_URL
pnpm dev

Project Structure

ts-template/
├── app/                  Next.js App Router (pages, layouts, API routes)
├── lib/
│   ├── ai/               AI SDK utilities (provider, prompts, structured, stream)
│   ├── config/           Zod-validated environment config
│   ├── db/               Drizzle ORM (connection, schema, migrations)
│   ├── concurrency.ts    Bounded parallel execution (p-limit)
│   ├── errors.ts         Application error types
│   ├── log.ts            Pino structured logger
│   └── retry.ts          Exponential backoff with jitter
├── prompts/              Markdown prompt templates
├── scripts/              CLI scripts (run with tsx)
├── Dockerfile            Multi-stage: deps, builder, production
└── compose.yaml          App + opt-in PostgreSQL

Development

Command	Description
pnpm dev	Start Next.js dev server
pnpm build	Production build
pnpm lint	Lint with ESLint
pnpm lint:fix	Lint and apply fixes
pnpm format	Format with Prettier
pnpm test	Run Vitest
pnpm typecheck	Type check without building
pnpm check	Typecheck, lint, format check, test

Database

Command	Description
pnpm db:generate	Generate migration from schema
pnpm db:migrate	Apply pending migrations
pnpm db:push	Push schema directly (dev only)
pnpm db:studio	Open Drizzle Studio GUI

Start PostgreSQL locally with Docker:

docker compose --profile postgres up -d

Scripts

Run CLI scripts with the script helper (loads .env if present via --env-file-if-exists):

pnpm script scripts/example.ts --input "your text here"

Or invoke tsx directly if you need different env loading:

pnpm tsx --env-file=.env scripts/example.ts --input "your text here"

Docker

docker compose up        # start app (requires built image)
docker compose down      # stop all services

Configuration

Configured via environment variables. Copy .env.example to .env to get started.

Variable	Required	Default	Description
DATABASE_URL	Yes	—	PostgreSQL connection URL
OPENROUTER_API_KEY	Yes	—	OpenRouter API key
LOG_LEVEL	No	info	debug, info, warn, error
NODE_ENV	No	development	development, production, test
SKIP_ENV_VALIDATION	No	—	Set to true to bypass env validation at startup (CI / next build without runtime secrets)