---
title: "Monorepo Setup"
description: "Initialize a Turborepo monorepo ready for multiple applications and shared packages."
canonical_url: "https://vercel.com/academy/microfrontends-on-vercel/monorepo-setup"
md_url: "https://vercel.com/academy/microfrontends-on-vercel/monorepo-setup.md"
docset_id: "vercel-academy"
doc_version: "1.0"
last_updated: "2026-04-11T07:44:02.722Z"
content_type: "lesson"
course: "microfrontends-on-vercel"
course_title: "Microfrontends on Vercel"
prerequisites:  []
---

<agent-instructions>
Vercel Academy — structured learning, not reference docs.
Lessons are sequenced.
Adapt commands to the human's actual environment (OS, package manager, shell, editor) — detect from project context or ask, don't assume.
The lesson shows one path; if the human's project diverges, adapt concepts to their setup.
Preserve the learning goal over literal steps.
Quizzes are pedagogical — engage, don't spoil.
Quiz answers are included for your reference.
</agent-instructions>

# Monorepo Setup

# Monorepo Setup with Turborepo

Microfrontends don't require a monorepo, but shared code and coordinated builds are easier with one.

## Outcome

Set up a Turborepo monorepo with workspace configuration, task orchestration, and remote caching.

## Why Monorepo + Microfrontends

| Benefit            | How It Helps                                     |
| ------------------ | ------------------------------------------------ |
| Shared packages    | One Header component, used everywhere            |
| Atomic commits     | Change shared code and all consumers together    |
| Coordinated builds | Turborepo builds dependencies in the right order |
| Remote caching     | Skip builds that haven't changed                 |

Vercel uses this pattern: all 12 microfrontend projects live in one monorepo with shared packages for headers, footers, and design systems.

## Fast Track

1. Create a new directory and initialize Turborepo
2. Configure pnpm workspaces
3. Verify the setup runs

## Hands-on Exercise 1.3

Initialize the Acme Platform monorepo from scratch.

**Requirements:**

1. Create a new directory called `acme-platform`
2. Initialize with pnpm and Turborepo
3. Configure workspaces for `apps/*` and `packages/*`
4. Set up the turbo.json task configuration

**Step 1: Create the directory structure**

```bash
mkdir acme-platform
cd acme-platform
```

**Step 2: Initialize package.json**

Create `package.json`:

```json title="package.json"
{
  "name": "acme-platform",
  "private": true,
  "scripts": {
    "dev": "turbo dev",
    "build": "turbo build",
    "lint": "turbo lint"
  },
  "devDependencies": {
    "turbo": "^2.3.0"
  },
  "packageManager": "pnpm@9.15.0"
}
```

**Step 3: Configure pnpm workspaces**

Create `pnpm-workspace.yaml`:

```yaml title="pnpm-workspace.yaml"
packages:
  - "apps/*"
  - "packages/*"
```

**Step 4: Configure Turborepo**

Create `turbo.json`:

```json title="turbo.json"
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "dependsOn": ["^lint"]
    }
  }
}
```

**Step 5: Create directory structure**

```bash
mkdir -p apps packages
```

**Step 6: Install dependencies**

```bash
pnpm install
```

## Try It

After setup, your structure should look like:

```
acme-platform/
├── apps/                    # Empty for now
├── packages/                # Empty for now
├── node_modules/
├── package.json
├── pnpm-lock.yaml
├── pnpm-workspace.yaml
└── turbo.json
```

Verify Turborepo is working:

```bash
pnpm turbo --version
```

Expected output:

```
2.3.0
```

## Understanding turbo.json

The configuration tells Turborepo how tasks relate:

```json
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],  // Build dependencies first
      "outputs": [".next/**", "!.next/cache/**"]  // Cache these files
    },
    "dev": {
      "cache": false,     // Don't cache dev mode
      "persistent": true  // Keep running
    }
  }
}
```

- **`dependsOn: ["^build"]`** - The `^` means "build my dependencies before building me"
- **`outputs`** - Files Turborepo caches to skip future builds
- **`persistent: true`** - The task keeps running (like a dev server)

## Commit

```bash
git init
git add -A
git commit -m "chore: initialize turborepo monorepo"
```

## Done-When

- [ ] `acme-platform` directory created
- [ ] `package.json` with turbo scripts configured
- [ ] `pnpm-workspace.yaml` pointing to apps/\* and packages/\*
- [ ] `turbo.json` with build, dev, and lint tasks
- [ ] `pnpm install` completes without errors

## Optional: Enable Remote Caching

Remote caching shares build artifacts across machines. Enable it with Vercel:

```bash
npx turbo login
npx turbo link
```

After linking, builds on CI will reuse cached artifacts from local development (and vice versa). This becomes valuable once you have multiple applications building.

## What's Next

Skeleton's ready. Now you'll create the three Next.js apps and a shared UI package.


---

[Full course index](/academy/llms.txt) · [Sitemap](/academy/sitemap.md)