init-tanstack-elysia - SKILL.md Agent Skill

name: init-tanstack-elysia description: Initialize a full-stack monorepo with TanStack Start + shadcn/ui frontend (Bun, Biome, tsc) and ElysiaJS backend with Better Auth (username + password), Drizzle ORM (PostgreSQL), and Eden Treaty for end-to-end type safety. Includes a justfile task runner and Docker production setup. Use when creating a new full-stack project, scaffolding a monorepo, or setting up TanStack Start with ElysiaJS. allowed-tools: Bash Read Write

Initialize TanStack Start + ElysiaJS Monorepo

Create a production-ready Bun workspace monorepo with a TanStack Start frontend and ElysiaJS backend.

For detailed configuration file contents, see references/stack-details.md.

Prerequisites

Verify these tools are installed before proceeding:

bun --version      # >= 1.2
just --version     # >= 1.0
jj --version       # >= 0.25
docker --version   # >= 24.0 (optional, for production builds)

If any required tool is missing (bun, just, jj), stop and inform the user. Docker is optional — warn if missing but continue.

Step 1: Initialize Version Control

jj git init --colocate

Create .jj/.gitignore with content /* so git ignores jj metadata.

Step 2: Scaffold the Frontend

Run the shadcn create command to scaffold a TanStack Start project:

bunx --bun shadcn@latest create \
  --preset "https://ui.shadcn.com/init?base=base&style=mira&baseColor=neutral&theme=indigo&iconLibrary=lucide&font=geist&menuAccent=subtle&menuColor=default&radius=medium&template=start&rtl=false" \
  --template start \
  frontend

After scaffolding completes:

Remove the nested git repository created by shadcn (the project uses the root-level jj/git repo):
```
rm -rf frontend/.git
```
Remove ESLint configuration if present (the project uses Biome instead):
- Delete eslint.config.js or .eslintrc.* if they exist
- Remove eslint, @eslint/*, and prettier packages from package.json devDependencies
- Remove any eslint/prettier scripts from package.json

Install Biome and additional dependencies:

cd frontend && bun add -d @biomejs/biome vitest jsdom
cd frontend && bun add @elysiajs/eden @tanstack/react-query better-auth

Create frontend/biome.json with the configuration from stack-details.md section "Biome Configuration (Frontend)".
Auto-fix the scaffolded code to conform to Biome rules (formatting, imports):
```
cd frontend && bunx biome check --write --unsafe .
```
Update the name field in frontend/package.json to "@repo/frontend".
Create frontend/src/lib/auth-client.ts with the Better Auth client from stack-details.md section "Better Auth Client".
Create frontend/src/lib/api.ts with the Eden Treaty client from stack-details.md section "Eden Treaty Client".
Create frontend/vitest.config.ts and frontend/src/__tests__/smoke.test.ts from stack-details.md section "Frontend Test Configuration".
Update frontend/tsconfig.json:
- Add "@repo/backend/*": ["../backend/*"] to compilerOptions.paths (needed for Eden Treaty type imports)
- Remove eslint.config.js and prettier.config.js from the include array if present

Merge these scripts into frontend/package.json (preserve existing scripts from scaffolding):

{
  "scripts": {
    "check": "biome check .",
    "check:fix": "biome check --write .",
    "typecheck": "tsc --noEmit",
    "test": "vitest run"
  }
}

Step 3: Create Root Workspace

Create package.json in the project root from stack-details.md section "Root Package JSON".
Run bun install from the project root to link workspaces:
```
bun install
```

Step 4: Scaffold the Backend

Create backend/package.json from stack-details.md section "Backend Package JSON".
Install backend dependencies:
```
cd backend && bun install
```

Create the backend application structure:

backend/
├── src/
│   ├── app.ts            # Elysia app (without listen)
│   ├── index.ts           # Entry point (app.listen)
│   ├── auth.ts            # Better Auth config
│   ├── db/
│   │   ├── index.ts       # Drizzle client
│   │   └── schema.ts      # App-specific schema
│   └── routes/
│       └── health.ts      # Health check endpoint
├── scripts/
│   ├── generate-openapi.ts
│   └── validate-openapi.ts
└── tests/
    └── health.test.ts

Write backend/src/db/index.ts with the Drizzle client from stack-details.md section "Drizzle Client".
Write backend/src/auth.ts with the Better Auth config from stack-details.md section "Better Auth Server Config".
Write backend/src/routes/health.ts with the health endpoint from stack-details.md section "Health Route".
Write backend/src/app.ts with the Elysia app from stack-details.md section "Elysia App".
Write backend/src/index.ts with the entry point from stack-details.md section "Backend Entry Point".
Write backend/drizzle.config.ts from stack-details.md section "Drizzle Config".
Create backend/biome.json from stack-details.md section "Biome Configuration (Backend)".
Create backend/tsconfig.json from stack-details.md section "Backend TSConfig".
Write backend/scripts/generate-openapi.ts from stack-details.md section "OpenAPI Generation Script".
Write backend/scripts/validate-openapi.ts from stack-details.md section "OpenAPI Validation Script".
Create backend/.gitignore from stack-details.md section "Backend Gitignore".
Write backend/tests/health.test.ts from stack-details.md section "Backend Tests".
Auto-fix the backend code to conform to Biome rules (formatting, imports):
```
cd backend && bunx biome check --write --unsafe .
```

Step 5: Generate Better Auth Schema & Initial Migration

Generate the Better Auth database schema:

cd backend && bunx @better-auth/cli generate --config ./src/auth.ts --output ./src/db/auth-schema.ts

Import the generated auth schema in backend/src/db/schema.ts. See stack-details.md section "App Schema" for the pattern.

Start the dev PostgreSQL database:

docker compose -f docker-compose.dev.yml up -d

Wait for PostgreSQL to be ready, then push the schema to the database:
```
cd backend && bunx drizzle-kit push
```

Step 6: Generate Initial OpenAPI Schema

cd backend && bun run scripts/generate-openapi.ts

Step 7: Create the Root Justfile

Create justfile in the project root with the content from stack-details.md section "Justfile".

Key recipes:

set dotenv-load to read .env
dev spawns dev database, frontend, and backend in parallel
dev-frontend / dev-backend / dev-db for individual services
check runs all linters, formatters, type checkers, and OpenAPI validation
fix auto-fixes lint and format issues
gen-api generates OpenAPI schema
db-push / db-migrate / db-studio for database management

Step 8: Create Docker Configuration

Create docker-compose.dev.yml from stack-details.md section "Docker Compose Dev".
Create frontend/Dockerfile from stack-details.md section "Frontend Dockerfile".
Create backend/Dockerfile from stack-details.md section "Backend Dockerfile".
Create docker-compose.yml in the project root from stack-details.md section "Docker Compose Production".
Create frontend/.dockerignore and backend/.dockerignore from stack-details.md section "Dockerignore Files".

Step 9: Create Root Configuration Files

Create .env.example from stack-details.md section "Environment Template".
Copy .env.example to .env:
```
cp .env.example .env
```
Create .gitignore from stack-details.md section "Gitignore".
Create .editorconfig from stack-details.md section "EditorConfig".
Create .vscode/extensions.json from stack-details.md section "VS Code Extensions".
Create .vscode/settings.json from stack-details.md section "VS Code Settings".
Create .github/workflows/ci.yml from stack-details.md section "GitHub Actions CI".
Create README.md from stack-details.md section "Project README".

Step 10: Run Install and Verify

Install all workspace dependencies:
```
bun install
```
Run checks:
```
just check
```
Run tests:
```
just test
```
Run dev servers:
```
just dev
```
Verify:
- Frontend at http://localhost:3000
- Backend at http://localhost:3001
- API docs at http://localhost:3001/docs
Stop the dev servers after verification.

Final Project Structure

project/
├── package.json              # Root Bun workspace
├── bun.lock
├── justfile
├── frontend/
│   ├── package.json          # @repo/frontend
│   ├── app/                  # TanStack Start app directory
│   │   └── routes/
│   ├── src/
│   │   ├── lib/
│   │   │   ├── auth-client.ts  # Better Auth client SDK
│   │   │   ├── api.ts          # Eden Treaty client
│   │   │   └── utils.ts
│   │   ├── components/
│   │   │   └── ui/             # shadcn components
│   │   └── __tests__/
│   ├── biome.json
│   ├── vitest.config.ts
│   ├── tsconfig.json
│   ├── Dockerfile
│   └── .dockerignore
├── backend/
│   ├── package.json          # @repo/backend
│   ├── src/
│   │   ├── app.ts            # Elysia app definition
│   │   ├── index.ts          # Entry point (listen)
│   │   ├── auth.ts           # Better Auth config
│   │   ├── db/
│   │   │   ├── index.ts      # Drizzle client
│   │   │   ├── schema.ts     # App schema
│   │   │   └── auth-schema.ts # Generated by Better Auth CLI
│   │   └── routes/
│   │       └── health.ts
│   ├── scripts/
│   │   ├── generate-openapi.ts
│   │   └── validate-openapi.ts
│   ├── tests/
│   │   └── health.test.ts
│   ├── drizzle/              # Migrations
│   ├── drizzle.config.ts
│   ├── biome.json
│   ├── tsconfig.json
│   ├── openapi.json          # Generated OpenAPI spec
│   ├── Dockerfile
│   └── .dockerignore
├── docker-compose.yml        # Production
├── docker-compose.dev.yml    # Dev (PostgreSQL)
├── .vscode/
│   ├── extensions.json
│   └── settings.json
├── .github/
│   └── workflows/
│       └── ci.yml
├── .editorconfig
├── .env.example
├── .env
├── .gitignore
└── README.md

Report the final status to the user, including any warnings or errors encountered during setup.