Home
Relevant source files
The following files were used as context for generating this wiki page:
This project is a modern, full-stack TypeScript monorepo designed for building type-safe applications. It utilizes Turborepo as a high-performance build system to manage the different parts of the repository, which include a React frontend, a Hono API server, and several shared local packages. The architecture emphasizes a "contract-first" approach, where a shared contract package defines the API, ensuring type safety between the frontend and backend.
The core technologies include React 19 for the frontend, Hono for the backend API, oRPC for type-safe remote procedure calls, and Drizzle ORM for database interactions with PostgreSQL. It is noted that the project is a work in progress, and the connection between the frontend and backend is not yet fully implemented.
Sources: README.md:3-7
Core Technologies & Architecture
The project is built on a foundation of modern TypeScript tooling. It requires Node.js version 22 or higher and uses pnpm as its package manager. The entire monorepo is managed by Turborepo to optimize build and development workflows.
Sources: README.md:9-15, package.json:4-7
The high-level architecture separates concerns into distinct applications (apps) and shared libraries (packages). The web application communicates with the api application, which in turn interacts with the database via the shared db package.
This diagram illustrates the high-level interaction between the main components of the monorepo.
Sources: README.md:43-52
Technology Stack
The following table summarizes the core technologies used across the project.
| Category | Technology | Purpose |
|---|---|---|
| Core | TypeScript | Statically typed JavaScript at scale. |
| Turborepo | High-performance build system for monorepos. | |
| pnpm | Fast, disk space efficient package manager. | |
| Node.js 22+ | JavaScript runtime environment. | |
| Web | React 19, TanStack Router, TanStack Query | Building user interfaces with type-safe routing and state. |
| API | Hono, oRPC | Ultrafast web framework with type-safe RPC. |
| DB | Drizzle ORM, PostgreSQL | TypeScript ORM for a relational database. |
| Tools | Biome | Fast linter and formatter. |
Sources: README.md:9-39, package.json, apps/web/package.json, apps/api/package.json
Project Structure
The monorepo is organized into two main directories: apps for deployable applications and packages for shared code. This structure promotes code reuse and clear separation of concerns.
Sources: README.md:43-52
This diagram shows the directory structure and dependencies within the monorepo.
Directory Overview
| Directory | Description |
|---|---|
apps/api | The Hono API server, which implements the oRPC contract. |
apps/web | The React frontend application, built with TanStack Router. |
packages/contract | Defines the shared API contract and schemas using oRPC and Zod. |
packages/db | Contains the Drizzle ORM schema and database access layer. |
packages/ui | A collection of shared, unstyled UI components based on Radix UI. |
Sources: README.md:43-52
Applications
Frontend (apps/web)
The frontend is a React 19 single-page application. It uses the TanStack ecosystem extensively for routing, state management, and data fetching.
- Routing: Handled by TanStack Router, which uses a file-based routing system. Routes are defined as files within the
src/routesdirectory. The main entry point for the application issrc/routes/index.tsx. - Styling: Utilizes Tailwind CSS for utility-first styling, along with Radix UI for unstyled, accessible component primitives.
- State Management: Employs TanStack Query for asynchronous state and TanStack Form for type-safe form state.
Sources: README.md:17-23, apps/web/package.json:12-36, apps/web/README.md:30-32, apps/web/src/routes/index.tsx:4-6
Backend (apps/api)
The backend is an "ultrafast" web server built with Hono, designed for edge environments.
- API Layer: Uses oRPC to create a type-safe RPC layer that is defined in the
packages/contractpackage. - Authentication: Implements
better-authfor authentication logic. - API Documentation: Automatically generates OpenAPI documentation, which is served using Scalar at the
/api/docsendpoint.
Sources: README.md:25-29, apps/api/package.json:11-23, README.md:93-94
Development & Tooling
Development Environment
The recommended development setup uses a VS Code DevContainer. This configuration automatically provisions a Docker environment with Node.js 22, a PostgreSQL database, and all necessary dependencies installed via pnpm.
The DevContainer forwards the following ports:
3000: Web frontend3001: API server4983: Drizzle Studio5432: PostgreSQL database
Sources: README.md:58-77, README.md:112-117
Scripts
The root package.json provides several pnpm scripts for managing the monorepo.
| Script | Description |
|---|---|
pnpm dev | Runs all applications in development mode via Turborepo. |
pnpm build | Builds all applications for production. |
pnpm lint | Lints and auto-fixes files using Biome. |
pnpm format | Formats files using Biome. |
pnpm check | Runs both linting and formatting with Biome. |
pnpm type:check | Runs TypeScript type checking across all packages. |
Sources: package.json:8-16
Linting & Formatting
The project uses Biome as an all-in-one tool for linting and formatting, replacing the need for ESLint and Prettier. The configuration is defined in biome.json and is set to ignore build artifacts and node_modules.
Sources: README.md:103-105, biome.json:1-33
API Documentation
The Hono API server provides interactive API documentation out-of-the-box using Scalar. The OpenAPI specification is dynamically generated from the shared contract package, ensuring the documentation is always in sync with the API's definition.
The documentation can be accessed at http://localhost:3001/api/docs after starting the API server.
Sources: README.md:93-94, apps/api/src/handlers/openapi.ts:1-29
Conclusion
The contract-based-monorepo project serves as a template for building modern, type-safe, full-stack TypeScript applications. Its architecture, centered around a shared API contract and managed by Turborepo, provides a robust foundation for scalable development. By leveraging technologies like React, Hono, oRPC, and Drizzle, it offers a cohesive and efficient developer experience from the frontend to the database.
Sources: README.md