Contract-Based Monorepo - Modern TypeScript Monorepo

Note: This project is a work in progress. The connection between the frontend and backend is not yet fully implemented.

A modern, full-stack TypeScript monorepo built with Turborepo, featuring a React frontend, Hono API server, ORPC for type-safe RPC, and Drizzle ORM.

Tech Stack

Core Technologies

• TypeScript: Statically typed JavaScript at scale
• Turborepo: High-performance build system for JavaScript/TypeScript monorepos
• pnpm: Fast, disk space efficient package manager
• Node.js 22+: JavaScript runtime built on Chrome's V8 JavaScript engine

Frontend (Web)

• React 19: Library for building user interfaces
• TanStack Router: Type-safe routing solution
• TanStack Query: Powerful asynchronous state management
• TanStack Form: Type-safe form state management
• Tailwind CSS: Utility-first CSS framework
• Radix UI: Unstyled, accessible UI components

Backend (API)

• Hono: Ultrafast web framework for the Edges
• ORPC: Type-safe RPC framework for TypeScript
• Better Auth: Authentication library
• OpenAPI: API documentation with Scalar

Database

• Drizzle ORM: TypeScript ORM for SQL databases
• PostgreSQL: Advanced open-source relational database

Development Tools

• Biome: Fast linter and formatter replacing ESLint and Prettier
• dotenv: Environment variable management
• tsx: TypeScript execution environment

Project Structure

contract-based-monorepo/
├── apps/                   # Application code
│   ├── api/                # Hono API server with ORPC
│   └── web/                # React frontend with TanStack Router
│
├── packages/               # Shared packages
│   ├── contract/           # API contracts and schemas
│   ├── db/                 # Database schema and access layer
│   └── ui/                 # Shared UI components
│
└── .env                    # Environment variables (create from example)

Getting Started

Prerequisites

• Git
• Docker and Docker Compose
• Visual Studio Code
• VS Code Remote - Containers extension

Development with DevContainer (Recommended)

This project includes a DevContainer configuration that automatically sets up the development environment with all the necessary dependencies, including Node.js 22, TypeScript, npm, eslint, and PostgreSQL.

1. Clone the repository:

git clone https://github.com/gthomas08/contract-based-monorepo.git
cd contract-based-monorepo

2. Open the project in VS Code:

code .

3. When prompted, click "Reopen in Container" or run the "Remote-Containers: Reopen in Container" command from the command palette.

4. The DevContainer will automatically:

   • Build the Docker container with Node.js 22 and TypeScript
   • Set up a PostgreSQL database container
   • Install all dependencies with pnpm install
   • Forward ports: 3000 (web), 3001 (api), 4983 (drizzle-studio), and 5432 (postgres)

5. Set up environment variables:

cp .env.example .env
# Edit .env with your database connection string and other settings

6. Push database schema:

pnpm -F @contract-based-monorepo/db push

---

API Documentation: After starting the API server, visit http://localhost:3001/api/docs for interactive API docs.

---

Development

Run all applications in development mode:

pnpm dev

Or run specific applications:

# API server only
pnpm -F @contract-based-monorepo/api dev

# Web frontend only
pnpm -F @contract-based-monorepo/web dev

Build

Build all applications:

pnpm build

Type Checking

Run type checking across all packages:

pnpm type:check

Linting & Formatting

The project uses Biome for linting and formatting instead of ESLint and Prettier:

# Lint
pnpm lint

# Format
pnpm format

# Check (lint + format)
pnpm check

DevContainer Configuration

The project includes a comprehensive DevContainer setup for VS Code:

Configuration Files

• .devcontainer/devcontainer.json: Main configuration file for the DevContainer
• .devcontainer/docker-compose.yml: Docker Compose configuration for the app and PostgreSQL services
• .devcontainer/Dockerfile: Docker configuration for the Node.js 22 and TypeScript environment

Port Forwarding

The DevContainer automatically forwards the following ports:

• 3000: Web frontend
• 3001: API server
• 4983: Drizzle Studio
• 5432: PostgreSQL database

Installed Extensions

The DevContainer automatically installs these VS Code extensions:

• Docker (ms-azuretools.vscode-docker)
• ESLint (dbaeumer.vscode-eslint)