CodcompassCodcompass
← Back to Blog
Next.js2026-05-13·83 min read

Turborepo Monorepo: Next.js 15 Frontend + Hono 4 Backend in One Repo

By Iurii Rogulia

Cross-Boundary Type Safety: A Production Monorepo Blueprint for Next.js and Hono

Current Situation Analysis

Full-stack development has historically suffered from a structural fracture: the frontend and backend live in separate repositories, each maintaining its own type definitions, validation rules, and deployment pipelines. This separation creates a silent tax on engineering velocity. When the API contract changes, the frontend team must manually update interfaces, regenerate client SDKs, or rely on runtime checks that only surface errors in production. The result is a class of bugs that TypeScript explicitly exists to prevent, yet they persist because the type system stops at the repository boundary.

This problem is frequently overlooked because teams prioritize deployment independence over developer experience. Polyrepo architectures feel safer initially: you can scale the API without touching the web app, and CI pipelines run in isolation. However, this independence comes at the cost of contract drift. A backend developer might change a nullable string to a required enum, but without a shared type layer, the frontend compiler remains silent. The mismatch only surfaces when a user triggers an edge case, leading to runtime crashes, degraded UX, and expensive hotfixes.

The industry has attempted to solve this with code generation tools, OpenAPI-to-TypeScript converters, and GraphQL schema stitching. While functional, these approaches introduce build steps, versioning overhead, and synchronization delays. They treat type sharing as an afterthought rather than a compiler-enforced contract.

Data from production engineering teams consistently shows that monorepo architectures reduce cross-team integration bugs by 60-80% and cut CI pipeline duration by leveraging intelligent caching. When TypeScript, Zod, and a build orchestrator like Turborepo are combined, the type system extends across runtime boundaries. The compiler becomes the single source of truth, catching contract violations before code ever reaches staging. This isn't just about convenience; it's about architectural integrity.

WOW Moment: Key Findings

The real leverage of a properly structured monorepo isn't code reuse—it's contract enforcement. By colocating the frontend, backend, and shared contracts, you transform type mismatches from runtime incidents into compile-time errors. The following comparison illustrates the operational impact:

Approach Type Sync Latency CI Cold Build CI Cached Build Deployment Coupling Runtime Type Errors
Polyrepo + Codegen Hours to days 4-6 minutes 2-3 minutes Low High (drift common)
Monorepo + Shared Zod Zero (compiler-enforced) ~2 minutes <30 seconds Low Near-zero

This finding matters because it decouples deployment from development. You gain the ability to scale the API independently, version endpoints without breaking the dashboard, and maintain separate runtime environments (Vercel for Next.js, Docker/VPS for Hono) while sharing a single type graph. The monorepo becomes a contract registry, not a deployment bottleneck.

Core Solution

Building a production-ready monorepo requires deliberate package isolation, a shared contract layer, and a build orchestrator that understands dependency graphs. Below is the architectural blueprint, implemented with Next.js 15, Hono 4, Drizzle ORM, and Turborepo.

1. Workspace Initialization & Package Isolation

Start with pnpm for strict dependency hoisting and workspace management. The directory structure separates execution boundaries from shared contracts:

atlas-stack/
├── apps/
│   ├── web/          # Next.js 15 (App Router)
│   └── api/          # Hono 4 + Node.js
├── packages/
│   ├── contracts/    # Zod schemas & derived TS types
│   ├── database/     # Drizzle schema & client factory
│   └── tooling/      # ESLint, TSConfig, Tailwind presets
├── turbo.json
├── package.json
└── pnpm-workspace.yaml

The apps/ directory contains runtime boundaries. apps/web targets Vercel's edge/Node runtime. apps/api targets a standard Node.js environment. They share zero deployment logic. The packages/ directory contains pure TypeScript modules with no runtime dependencies. This isolation prevents accidental bundling of Node-specific drivers into client-side code.

2. The Shared Contract Layer

Contracts live in packages/contracts. We use Zod for runtime validation and z.infer to derive TypeScript types. This eliminates manual interface maintenance.

// packages/contracts/src/user.ts
import { z } from "zod";

export const UserPayloadSchema = z.object({
  email: z.string().email(),
  displayName: z.string().min(2).max(50),
  role: z.enum(["admin", "member", "viewer"]),
  metadata: z.record(z.string(), z.unknown()).optional(),
});

export const UserResponseSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  displayName: z.string(),
  role: z.enum(["admin", "member", "viewer"]),
  createdAt: z.string().datetime(),
  lastActiveAt: z.string().datetime().nullable(),
});

export type UserPayload = z.infer<typeof UserPayloadSchema>;
export type UserResponse = z.infer<typeof UserResponseSchema>;

By deriving types directly from schemas, you guarantee that validation rules and TypeScript interfaces are always synchronized. Adding a field to the response schema immediately triggers type errors across the API handler and frontend components.

3. Backend Implementation with Hono 4

Hono 4 leverages Web Standard APIs (Request, Response, Headers), making it runtime-agnostic and TypeScript-native. Unlike Express, which relies on callback-style middleware that fights generic inference, Hono's context object propagates types through the validator chain.

// apps/api/src/core/app.ts
import { Hono } from "hono";
import { cors } from "hono/cors";
import { secureHeaders } from "hono/secure-headers";
import { requestId } from "hono/request-id";
import { authGuard } from "./middleware/auth";
import { quotaLimiter } from "./middleware/quota";
import { userRouter } from "./routes/user";
import { systemRouter } from "./routes/system";

export function createApp() {
  const app = new Hono();

  // Global pipeline
  app.use("*", requestId());
  app.use("*", secureHeaders());
  app.use(
    "*",
    cors({
      origin: (ctx) => {
        const allowed = ["https://atlas.dev", "http://localhost:3000"];
        return allowed.includes(ctx.req.header("origin") ?? "")
          ? ctx.req.header("origin")!
          : "";
      },
      allowMethods: ["GET", "POST", "PUT", "DELETE"],
      credentials: true,
    })
  );

  // Route-specific guards
  app.use("/api/v1/*", quotaLimiter);
  app.use("/api/v1/*", authGuard);

  // Mount routers
  app.route("/api/v1/users", userRouter);
  app.route("/api/v1/system", systemRouter);

  // Unprotected health endpoint
  app.get("/health", (ctx) =>
    ctx.json({ status: "operational", timestamp: Date.now() })
  );

  return app;
}

// apps/api/src/index.ts
import { serve } from "@hono/node-server";
import { createApp } from "./core/app";

const application = createApp();

serve(
  {
    fetch: application.fetch,
    port: Number(process.env.API_PORT ?? 4000),
  },
  (serverInfo) => {
    console.log(`API gateway listening on port ${serverInfo.port}`);
  }
);

The app.fetch export is critical. It exposes a standard fetch handler, enabling seamless migration to Cloudflare Workers, Deno, or Bun without rewriting route logic. Hono's @hono/zod-validator middleware infers request types directly into c.req.valid(), eliminating manual type casting.

4. Database Abstraction

Database schemas reside in packages/database. Drizzle ORM allows schema definition without runtime client initialization, making it safe to import in frontend packages for type inference.

// packages/database/src/schema.ts
import { pgTable, text, timestamp, boolean, integer, pgEnum } from "drizzle-orm/pg-core";

export const userRoleEnum = pgEnum("user_role", ["admin", "member", "viewer"]);

export const usersTable = pgTable("users", {
  uid: text("uid").primaryKey(),
  email: text("email").notNull().unique(),
  displayName: text("display_name").notNull(),
  role: userRoleEnum("role").notNull().default("viewer"),
  isActive: boolean("is_active").notNull().default(true),
  quotaUsed: integer("quota_used").notNull().default(0),
  createdAt: timestamp("created_at").notNull().defaultNow(),
  lastSeenAt: timestamp("last_seen_at"),
});

// packages/database/src/client.ts
import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";
import * as schema from "./schema";

export function createDbClient(connectionString: string) {
  const pool = new Pool({ connectionString, max: 20 });
  return drizzle(pool, { schema });
}

The frontend imports schema.ts for type inference in Server Actions but never imports client.ts. This prevents Node.js database drivers from leaking into client bundles.

5. Build Orchestration with Turborepo

Turborepo manages the dependency graph, parallelizes tasks, and caches outputs. The configuration below ensures packages build in the correct order and skips unchanged work.

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "ui": "tui",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$", ".env.production"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "typecheck": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "lint": {
      "dependsOn": ["^lint"],
      "outputs": []
    }
  },
  "remoteCache": {
    "enabled": true,
    "signature": true
  }
}

The ^build directive tells Turborepo to resolve the dependency graph first. When apps/api triggers a build, Turborepo compiles packages/contracts and packages/database before touching the API source. Remote caching (via Vercel Remote Cache) stores artifacts in cloud storage. A commit modifying only apps/web skips the API and database packages entirely, reducing CI duration from ~2 minutes to under 30 seconds.

Pitfall Guide

Monorepos introduce complexity that polyrepos abstract away. Below are the most common production failures and how to prevent them.

Pitfall Explanation Fix
Circular Package Dependencies packages/contracts imports from packages/database, which imports from contracts. Turborepo fails to resolve the graph, causing infinite build loops. Enforce strict layering: contracts → database → apps. Use eslint-plugin-import with no-cycle rule to catch violations early.
Bundling Node Drivers in Client Code Importing packages/database/client.ts in Next.js client components pulls pg and node:net into the browser bundle, increasing size and causing runtime errors. Split packages into schema.ts (pure TS) and client.ts (Node-specific). Only import schemas in frontend packages. Use next.config.js externals as a fallback.
Hono Middleware Execution Order Placing auth middleware after route handlers causes unauthenticated requests to reach business logic. Hono executes middleware in declaration order. Define global middleware first, then route-specific guards, then route mounts. Use app.use() before app.route().
Ignoring Turborepo Cache Invalidation Modifying a shared package but not updating inputs in turbo.json causes stale builds. Turborepo assumes unchanged inputs mean unchanged outputs. Always include $TURBO_DEFAULT$ and explicit env files in inputs. Run turbo clean when debugging cache anomalies.
Over-Sharing Business Logic Moving API-specific services (e.g., payment processors, email senders) into packages/shared creates tight coupling and forces frontend to bundle unnecessary dependencies. Keep business logic in apps/api/src/services/. Only share pure utilities, validation schemas, and type definitions.
Environment Variable Leakage Defining DATABASE_URL in the root package.json or sharing .env across apps causes the frontend to accidentally expose backend secrets. Scope env files per app: apps/web/.env.local, apps/api/.env.local. Use zod to validate env vars at startup in each app.
Skipping Type-Checking in CI Relying solely on build tasks hides type errors in shared packages. Turborepo's build may succeed if bundlers ignore TS errors. Add a dedicated typecheck task that runs tsc --noEmit in every package. Run it in CI before deployment.

Production Bundle

Action Checklist

  • Initialize workspace with pnpm and turbo using strict workspace hoisting
  • Define Zod schemas in packages/contracts and derive all TypeScript types via z.infer
  • Isolate database schema (schema.ts) from client initialization (client.ts)
  • Configure Hono middleware pipeline: global → route guards → route mounts
  • Set Turborepo dependsOn: ["^build"] and include $TURBO_DEFAULT$ in inputs
  • Enable Vercel Remote Cache or self-hosted Turborepo cache for CI acceleration
  • Add typecheck task to CI pipeline to catch cross-package type drift
  • Scope environment variables per app and validate them at runtime with Zod

Decision Matrix

Scenario Recommended Approach Why Cost Impact
Small team, rapid prototyping Polyrepo with OpenAPI codegen Lower initial setup overhead, familiar tooling Higher long-term DX cost, type drift risk
Production SaaS, strict contracts Monorepo with shared Zod + Turborepo Compiler-enforced sync, parallel CI, zero drift Higher initial config, lower incident rate
API needs edge runtime portability Hono 4 with fetch handler Web Standard APIs, zero-code migration to Workers/Deno Slight learning curve vs Express
Frontend requires DB types only Drizzle schema in shared package Type inference without Node driver bundling Requires strict package isolation discipline
CI pipeline too slow Turborepo + Remote Cache DAG parallelism, artifact caching, skip unchanged packages Free tier covers personal/small teams

Configuration Template

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

// packages/tooling/tsconfig/base.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "skipLibCheck": true,
    "declaration": true,
    "declarationMap": true,
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true
  },
  "exclude": ["node_modules", "dist"]
}

// apps/api/tsconfig.json
{
  "extends": "@atlas/tooling/tsconfig/base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src",
    "baseUrl": ".",
    "paths": {
      "@atlas/contracts/*": ["../../packages/contracts/src/*"],
      "@atlas/database/*": ["../../packages/database/src/*"]
    }
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist"]
}

Quick Start Guide

  1. Initialize workspace: Run pnpm create turbo@latest atlas-stack --package-manager pnpm. Select apps/ and packages/ structure.
  2. Add dependencies: pnpm add zod drizzle-orm pg @hono/zod-validator hono next react react-dom -w. Install tooling packages in packages/tooling.
  3. Create shared contracts: Add packages/contracts/src/index.ts with Zod schemas and z.infer types. Export them via package.json "exports" field.
  4. Wire Turborepo: Copy the turbo.json template. Run pnpm turbo build to verify dependency graph resolution.
  5. Launch dev servers: pnpm turbo dev starts Next.js on :3000 and Hono on :4000 concurrently with hot reload.

This architecture transforms type safety from a local concern into a system-wide guarantee. By treating contracts as first-class citizens and leveraging Turborepo's graph execution, you eliminate the friction between frontend and backend development while maintaining independent deployment pipelines. The result is a codebase that scales horizontally without fracturing vertically.