Next.js Multi-Zones Starter

Vercel Microfrontends - Next.js Multi-Zones example

This example showcases how to build and deploy a Next.js Multi-Zones microfrontends application using Vercel Microfrontends with Next.js App Router. Learn how to architect independent, deployable frontend applications that work together seamlessly while maintaining team autonomy and deployment independence.

Demo URL: https://microfrontends-marketing-three.vercel.app/

🚀 Deploy to Vercel

This example consists of two separate microfrontends that can be deployed independently:

---

Getting Started

Set up with an agent

The fastest way to run this example, or apply the same architecture to your own apps, is to give your coding agent the Vercel microfrontends skill.

Install the Vercel plugin (includes the microfrontends skill):

1
npx plugins add vercel/vercel-plugin

In Cursor you can also run /add-plugin vercel. To install only the skill:

1
npx skills add vercel/microfrontends

Then ask your agent:

1
Use the microfrontends skill to set up this Next.js multi-zones example. Install dependencies and start local development.

To wire the same pattern into your own projects:

1
Use the microfrontends skill to create a microfrontends group, add these projects, and configure the default app and /docs routing.

See the Microfrontends skill and Vercel Microfrontends docs.

Prerequisites

Ensure you have the following installed:

• Node.js 20.x or later
• pnpm 9.4.0 (recommended package manager)
• Git for version control

Local Development Setup

1. Clone the repository:

   1
   git clone https://github.com/vercel/examples
   2
   cd microfrontends/nextjs-multi-zones

2. Install dependencies:

   1
   pnpm install

3. Start the development environment:

   1
   pnpm dev

This command starts both applications simultaneously:

• Marketing app: http://localhost:3000
• Documentation app: http://localhost:3001 (automatically proxied through marketing app)

1. Access the application: Open http://localhost:3024 in your browser and navigate between different sections to see the microfrontend routing in action.

---

Why Multi-Zones?

Multi-Zones, or splitting a single domain into multiple applications, allows you to build and iterate on different parts of an application independently. The benefits include:

• Independent Deployments: Deploy each microfrontend without affecting others
• Team Autonomy: Enable teams to work independently while maintaining consistency
• Technology Flexibility: Each microfrontend can use different technologies or versions
• Fault Isolation: Issues in one microfrontend don't affect others
• Incremental Upgrades: Modernize parts of your application gradually

---

Architecture Overview

This example implements a multi-zones architecture where:

Loading diagram...

Key Components

1. Marketing Application (apps/marketing/)

   • Primary application handling the main website
   • Contains homepage, pricing, and general marketing content
   • Acts as the shell application orchestrating other microfrontends

2. Documentation Application (apps/docs/)

   • Dedicated documentation microfrontend
   • Handles all /docs routes
   • Can be developed and deployed independently

3. Shared Packages (packages/)

   • Common TypeScript configurations
   • Shared ESLint rules and formatting standards
   • Ensures consistency across all applications

---

Project Structure Deep Dive

1
microfrontends/nextjs-multi-zones/
2
├── apps/
3
│   ├── marketing/              # Main application (shell)
4
│   │   ├── app/               # Next.js App Router pages
5
│   │   ├── components/        # UI components
6
│   │   ├── lib/              # Utilities and helpers
7
│   │   ├── microfrontends.json # Routing configuration
8
│   │   └── next.config.ts    # Next.js configuration with MFE setup
9
│   │
10
│   └── docs/                  # Documentation microfrontend
11
│       ├── app/              # Documentation pages
12
│       ├── components/       # Doc-specific components
13
│       ├── lib/             # Documentation utilities
14
│       └── next.config.ts   # Standalone Next.js configuration
15
│
16
├── packages/
17
│   ├── eslint-config-custom/  # Shared linting configuration
18
│   └── ts-config/            # Shared TypeScript configuration
19
│
20
├── package.json              # Root package.json with workspaces
21
├── pnpm-workspace.yaml       # PNPM workspace configuration
22
└── turbo.json               # Turborepo build pipeline

Configuration Files Explained

microfrontends.json

This file defines how microfrontends are discovered and routed:

• Applications mapping: Defines each microfrontend and its ports
• Routing rules: Specifies which URLs should be handled by which microfrontend
• Development settings: Local ports and fallback URLs for development

next.config.ts

Each application has its own Next.js configuration enhanced with:

• withMicrofrontends(): Enables microfrontend capabilities
• withVercelToolbar(): Adds development debugging tools
• Standard Next.js optimizations and settings

---

How Microfrontend Routing Works

The magic happens through the @vercel/microfrontends package:

1. Route Discovery

The marketing application (shell) reads the microfrontends.json configuration to understand which routes should be handled by which microfrontend.

2. Dynamic Proxying

When a user navigates to /docs, Vercel Microfrontends:

• Recognizes this route belongs to the documentation microfrontend
• Proxies the request to the documentation application
• Returns the response seamlessly to the user

All routing between microfrontends is handled dynamically by Vercel Microfrontends, allowing for a smooth user experience without page reloads.

3. Development Magic

During development, both applications run simultaneously, and the routing happens transparently, providing a seamless development experience.

4. Production Deployment

In production, each microfrontend is deployed independently to Vercel, and the routing configuration ensures requests are directed to the correct deployment.

Learn more in the routing documentation.

---

Development Workflow

Working with Individual Microfrontends

You can develop microfrontends in isolation using the microfrontends local development proxy:

1
# Work on the marketing application only
2
cd apps/marketing
3
pnpm dev
4

5
# Work on the documentation application only
6
cd apps/docs
7
pnpm dev

Building and Testing

1
# Build all applications
2
pnpm build
3

4
# Run linting across all apps
5
pnpm lint
6

7
# Type check all applications
8
pnpm typecheck
9

10
# Run all quality checks
11
pnpm checks

Adding New Microfrontends

1. Create a new application in the apps/ directory
2. Update microfrontends.json to include routing rules
3. Add the new app to the workspace configuration
4. Configure deployment settings for the new microfrontend

Learn more in the Managing Microfrontends documentation.

---

Configuration and Components

Next.js Configuration in This Project

Both applications use withMicrofrontends to enable cross-zone routing:

1
// apps/marketing/next.config.ts & apps/docs/next.config.ts
2
import { withMicrofrontends } from '@vercel/microfrontends/next/config';
3
import { withVercelToolbar } from '@vercel/toolbar/plugins/next';
4

5
export default withVercelToolbar()(
6
  withMicrofrontends(nextConfig, { debug: true }),
7
);

Routing Configuration

The marketing app defines how to route to the docs microfrontend:

1
// apps/marketing/microfrontends.json
2
{
3
  "applications": {
4
    "microfrontends-marketing": {
5
      "development": {
6
        "local": 3000,
7
        "fallback": "microfrontends-marketing.vercel.app",
8
      },
9
    },
10
    "microfrontends-docs": {
11
      "development": { "local": 3001 },
12
      "routing": [{ "group": "docs", "paths": ["/docs", "/docs/:path*"] }],
13
    },
14
  },
15
}

Optimizing Cross-Microfrontend Navigation

The @vercel/microfrontends package can be used to prefetch and prerender links to other microfrontends.

First, embed the PrefetchCrossZoneLinksProvider element in the root layout.tsx of your application.

Then, use the enhanced Link component for seamless optimized navigation between zones:

1
// In marketing app - navigating to docs
2
import { Link } from '@vercel/microfrontends/next/client';
3

4
<Link href="/docs">View Documentation</Link>
5
<Link href="/docs/getting-started">Getting Started Guide</Link>

This setup enables the marketing app to seamlessly route /docs requests to the documentation microfrontend while maintaining a unified user experience.

Learn more in the Optimizing Hard Navigations documentation.