Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• .devcontainer/devcontainer.json
• pnpm-workspace.yaml
• package.json
• biome.json
• apps/api/package.json
• apps/web/package.json
• packages/db/package.json
• apps/api/src/handlers/openapi.ts

This guide provides instructions for setting up and running the contract-based-monorepo project. The project is a modern, full-stack TypeScript monorepo utilizing Turborepo for high-performance builds. It features a React frontend, a Hono API server, and a PostgreSQL database managed with Drizzle ORM. The frontend and backend communicate via a type-safe contract defined with oRPC.

The recommended setup method uses a VS Code DevContainer, which automates the environment configuration, including all necessary dependencies and services. This ensures a consistent and reproducible development environment for all contributors.

Sources: README.md:3-8

Prerequisites

Before you begin, ensure you have the following software installed on your system:

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

Sources: README.md:46-50

Project Structure

The monorepo is managed by pnpm workspaces and organized into two main directories: apps for individual applications and packages for shared code.

# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"

Sources: pnpm-workspace.yaml:2-4

This diagram illustrates the high-level structure of the monorepo.

Development Setup

The recommended method for setting up the development environment is by using the provided DevContainer configuration.

DevContainer Setup (Recommended)

This process automates the entire environment setup, including Node.js, PostgreSQL, and all project dependencies.

1. Clone the repository:

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

2. Open in VS Code:

   code .
   

3. Reopen in Container: When prompted by VS Code, click "Reopen in Container". This will trigger the DevContainer build process.

The following diagram shows the automated workflow when the DevContainer starts.

The DevContainer automatically forwards the following ports:

Port	Service	Description
3000	Web	React frontend application
3001	API	Hono API server
4983	Drizzle Studio	Database GUI
5432	PostgreSQL	Database server
Sources: README.md:65-66, .devcontainer/devcontainer.json:13-18

Post-Setup Configuration

After the DevContainer is running, complete the setup with these steps:

1. Set up environment variables: Copy the example file and edit it with your database connection string and other settings.

   cp .env.example .env
   

2. Push the database schema: This command applies the Drizzle ORM schema to the PostgreSQL database.

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

Sources: README.md:68-75, packages/db/package.json:15

Running the Application

You can run all applications simultaneously or start them individually.

Command	Description
pnpm dev	Runs all applications (api and web) in development mode.
pnpm -F @contract-based-monorepo/api dev	Runs only the API server.
pnpm -F @contract-based-monorepo/web dev	Runs only the web frontend.
Sources: README.md:82-91, package.json:10, apps/api/package.json:6, apps/web/package.json:8

Once the API server is running, interactive API documentation is available at http://localhost:3001/api/docs. This is served using Scalar.

Sources: README.md:78-79, apps/api/src/handlers/openapi.ts:31-39

Common Development Commands

The project includes several scripts for common development tasks, managed by Turborepo and pnpm.

Building for Production

To create a production-ready build of all applications and packages, run:

pnpm build

Sources: package.json:9, README.md:94-96

Type Checking

To run TypeScript type checking across the entire monorepo without emitting files, use:

pnpm type:check

Sources: package.json:14, README.md:99-101

Linting and Formatting

The project uses Biome for fast linting and formatting, replacing the need for ESLint and Prettier.

Command	Description
pnpm lint	Lints the codebase and applies safe fixes.
pnpm format	Formats the codebase.
pnpm check	Runs both linting and formatting.
Sources: README.md:104-113, package.json:11-13, biome.json

The Biome configuration enforces a recommended set of rules, with specific settings for import organization and class sorting.

{
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2
  },
  "organizeImports": {
    "enabled": true
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  }
}

Sources: biome.json:14-29