nextjs-contract-based-monorepo

Modern TypeScript monorepo with a Next.js web app, a Hono server using oRPC, shared contracts, Drizzle ORM, and PostgreSQL.

Features

• TypeScript-first across apps and packages
• Next.js 15 (Turbopack) frontend
• Hono server with oRPC (RPC + OpenAPI) and Better-Auth
• Drizzle ORM with PostgreSQL and Docker Compose helpers
• TailwindCSS + shadcn/ui components
• Biome + Ultracite for formatting/linting and Husky + lint-staged

Prerequisites

• Node.js and pnpm installed
• Docker (optional, recommended for local PostgreSQL)

Getting Started

1. Install dependencies

pnpm install

2. Configure environment variables

Create apps/server/.env:

DATABASE_URL=postgresql://postgres:password@localhost:5432/nextjs-contract-based-monorepo
CORS_ORIGIN=http://localhost:3001
# Optional, required for /ai endpoint
OPENAI_API_KEY=your-openai-api-key

Create apps/web/.env.local:

NEXT_PUBLIC_SERVER_URL=http://localhost:3000

3. Start PostgreSQL (via Docker Compose)

pnpm db:start

4. Apply the database schema

pnpm db:push

5. Run the apps in development

pnpm dev

• Web: http://localhost:3001
• API: http://localhost:3000

API Endpoints

• GET / → Health check: returns "OK"
• POST /ai → AI text streaming (requires OPENAI_API_KEY)
• POST/GET /api/auth/** → Better-Auth routes
• POST/GET /rpc/** → oRPC endpoints
• POST/GET /api/** → OpenAPI HTTP endpoints generated from contract

Project Structure

nextjs-contract-based-monorepo/
├── apps/
│   ├── web/             # Next.js frontend
│   └── server/          # Hono + oRPC backend (Drizzle, Better-Auth)
└── packages/
	└── contract/        # Shared oRPC contract and Zod schemas

Scripts

Root-level scripts (run from repo root):

• pnpm dev: Run all apps in dev mode
• pnpm build: Build all apps
• pnpm check-types: Check types across packages
• pnpm dev:web: Run just the web app
• pnpm dev:server: Run just the server

Database helpers (proxy to apps/server):

• pnpm db:push: Push Drizzle schema
• pnpm db:studio: Open Drizzle Studio
• pnpm db:generate: Generate migrations
• pnpm db:migrate: Apply migrations
• pnpm db:start: Start Postgres via Docker Compose
• pnpm db:watch: Attach to logs (foreground)
• pnpm db:stop: Stop containers
• pnpm db:down: Remove containers and volumes

Code Quality

• Format/lint with Biome (writes fixes):

pnpm check

• Check with Ultracite (no write):

pnpm dlx ultracite check

Husky + lint-staged automatically run formatting on commits.

Notes

• Make sure CORS_ORIGIN matches the web app URL in development (default http://localhost:3001).
• The web app reads NEXT_PUBLIC_SERVER_URL to reach the server (default http://localhost:3000).

Acknowledgements

This project was initially bootstrapped with Better-T-Stack.

Getting Started

First, install the dependencies:

pnpm install

Database Setup

This project uses PostgreSQL with Drizzle ORM.

1. Make sure you have a PostgreSQL database set up.

2. Update your apps/server/.env file with your PostgreSQL connection details.

3. Apply the schema to your database:

pnpm db:push

Then, run the development server:

pnpm dev

Open http://localhost:3001 in your browser to see the web application. The API is running at http://localhost:3000.

Project Structure

nextjs-contract-based-monorepo/
├── apps/
│   ├── web/         # Frontend application (Next.js)
│   └── server/      # Backend API (Hono, ORPC)

Available Scripts

• pnpm dev: Start all applications in development mode
• pnpm build: Build all applications
• pnpm dev:web: Start only the web application
• pnpm dev:server: Start only the server
• pnpm check-types: Check TypeScript types across all apps
• pnpm db:push: Push schema changes to database
• pnpm db:studio: Open database studio UI