Structuring a Monorepo

Hướng dẫn cấu trúc monorepo với Turborepo — workspace setup, package types, internal packages, exports, và common pitfalls.

Turborepo xây dựng trên Workspaces — tính năng của package manager (pnpm, npm, yarn) cho phép nhóm nhiều packages trong một repo.

1. Minimum Requirements

Một monorepo hợp lệ cần:

1. Package manager lockfile — pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lock

2. Root package.json — private: true, scripts gọi turbo

3. Root turbo.json — cấu hình tasks

4. Workspace declaration — pnpm-workspace.yaml hoặc workspaces trong root package.json

5. package.json trong mỗi package

Cấu trúc thư mục chuẩn:

my-monorepo/
├── apps/
│   ├── web/            # Next.js app
│   ├── docs/           # Documentation site
│   └── api/            # Express/Fastify API
├── packages/
│   ├── ui/             # Shared UI components
│   ├── utils/          # Shared utilities
│   ├── types/          # Shared TypeScript types
│   ├── config-eslint/  # Shared ESLint config
│   └── config-ts/      # Shared tsconfig
├── turbo.json
├── package.json
├── pnpm-workspace.yaml
└── .gitignore

2. Workspace Setup

pnpm

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

npm / yarn / bun

{
  "workspaces": ["apps/*", "packages/*"]
}

Lưu ý: Không dùng apps/** hoặc packages/** (nested). Chỉ 1 cấp depth. Nếu cần nhóm sâu hơn: packages/*, packages/group/* và không tạo packages/group/package.json.

Root package.json

{
  "private": true,
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "lint": "turbo run lint",
    "test": "turbo run test"
  },
  "devDependencies": {
    "turbo": "latest"
  },
  "devEngines": {
    "packageManager": {
      "name": "pnpm",
      "version": "9.0.0"
    }
  }
}

3. Anatomy of a Package

Mỗi package gần như một "dự án nhỏ" — có package.json, tooling config, source code riêng.

package.json

{
  "name": "@repo/ui",
  "exports": {
    ".": "./src/index.ts",
    "./button": "./src/button.tsx",
    "./utils": "./src/utils.ts"
  },
  "scripts": {
    "build": "tsc",
    "lint": "eslint .",
    "test": "vitest run"
  }
}

exports — thay thế main, hỗ trợ Conditional Exports, tránh barrel files, IDE autocompletion.

Source code

Thường dùng src/ → compile ra dist/ (nếu là Compiled Package).

4. Package Types

Application Packages

• Deployable (Next.js, Vite, Express...)

• Có .env riêng

• Chạy bằng turbo run dev / turbo run build

Library Packages

• Chia sẻ code giữa các apps

• Có thể là Just-in-Time (export TypeScript trực tiếp, zero build) hoặc Compiled (build ra JS)

Tooling Packages

• ESLint config, tsconfig, GitHub Actions

5. Just-in-Time vs Compiled Packages

Just-in-Time (JIT)

{
  "name": "@repo/utils",
  "exports": {
    ".": "./src/index.ts"
  }
}

Export TypeScript trực tiếp. App sử dụng sẽ build cùng. Zero config, không cần dependsOn: ["^build"].

Compiled

{
  "name": "@repo/ui",
  "exports": {
    ".": "./dist/index.js"
  },
  "scripts": {
    "build": "tsc"
  }
}

Cần build trước khi app dùng → cần dependsOn: ["^build"].

6. Internal Package Dependencies

Khai báo dependency giữa các internal packages như package thường:

{
  "name": "@repo/web",
  "dependencies": {
    "@repo/ui": "workspace:*",
    "@repo/utils": "workspace:*"
  }
}

pnpm workspace protocol (workspace:*) tự động link local packages.

7. Dùng exports thay vì barrel files

Không dùng barrel files (index.ts re-export tất cả). Dùng exports:

{
  "exports": {
    ".": "./src/index.ts",
    "./button": "./src/button.tsx",
    "./form": "./src/form.tsx"
  }
}

Import:

import { Button } from "@repo/ui/button";
// không phải import { Button } from "@repo/ui"

Lợi ích: tree-shaking tốt hơn, compiler không bị overload, IDE autocomplete.

8. Common Pitfalls

• Không dùng ../ để import package khác — luôn install và import bằng package name

• Không cần tsconfig.json root — mỗi package tự có tsconfig, shared config ở package riêng

• Không dùng apps/** trong workspace glob — chỉ 1 level depth

• Không viết turbo commands trong package scripts — chỉ ở root

• Lockfile là bắt buộc — nếu thiếu, Turborepo behavior unpredictable

• Root .env không khuyến nghị — đặt .env trong từng Application Package

9. Tạo monorepo mới nhanh

pnpm dlx create-turbo@latest
cd my-turborepo
pnpm install
pnpm dev

Starter bao gồm: 2 apps (web + docs) + các shared packages (ui, utils, config-eslint, config-ts).

Tài liệu tham khảo

• Structuring a Repository (official)

• Internal Packages

• Package Types