---
title: "Configuration Basics"
description: "Write the microfrontends.json configuration file and wrap each Next.js config with withMicrofrontends."
canonical_url: "https://vercel.com/academy/microfrontends-on-vercel/configuration-basics"
md_url: "https://vercel.com/academy/microfrontends-on-vercel/configuration-basics.md"
docset_id: "vercel-academy"
doc_version: "1.0"
last_updated: "2026-11-04T22:26:55.203Z"
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>

# Configuration Basics

# Configuration Basics

Add the routing configuration that tells Vercel which paths go to which apps.

## Outcome

Configure `microfrontends.json` for routing and wrap each Next.js config with `withMicrofrontends` to prevent asset conflicts.

## Two Configuration Files

Microfrontends require two types of configuration:

1. **`microfrontends.json`** - Defines routing (which paths go to which apps)
2. **`next.config.ts` wrapper** - Configures asset prefixes to prevent collisions

## Fast Track

1. Install `@vercel/microfrontends` in each app
2. Create `microfrontends.json` in the marketing (default) app
3. Wrap each `next.config.ts` with `withMicrofrontends`

## Hands-on Exercise 2.1

Configure the Acme Platform for microfrontends.

### Part 1: Install the Package

Add `@vercel/microfrontends` to each application using pnpm's workspace filter:

```bash
pnpm add @vercel/microfrontends --filter acme-marketing
pnpm add @vercel/microfrontends --filter acme-docs
pnpm add @vercel/microfrontends --filter acme-dashboard
```

This installs the package in all three apps.

### Part 2: Create microfrontends.json

Create `apps/marketing/microfrontends.json`:

```json title="apps/marketing/microfrontends.json"
{
  "$schema": "https://openapi.vercel.sh/microfrontends.json",
  "applications": {
    "acme-marketing": {
      "development": {
        "fallback": "acme-marketing.vercel.app",
        "local": 3000
      }
    },
    "acme-docs": {
      "routing": [
        {
          "paths": ["/docs", "/docs/:path*"]
        }
      ],
      "development": {
        "local": 3001
      }
    },
    "acme-dashboard": {
      "routing": [
        {
          "paths": ["/app", "/app/:path*", "/settings", "/settings/:path*"]
        }
      ],
      "development": {
        "local": 3002
      }
    }
  }
}
```

Each key under `applications` is a Vercel project name. We named the packages `acme-marketing`, `acme-docs`, and `acme-dashboard` back in Lesson 1.4, so every key matches both its `package.json` name and the project we'll create in Lesson 2.5.

If a package name ever drifts from its project name, keep the key as the project name and add `packageName` with the name from `package.json`:

```json
"acme-docs": {
  "packageName": "docs",
  "routing": [{ "paths": ["/docs", "/docs/:path*"] }]
}
```

The default app has no `routing`. It catches every path the other apps don't claim. Its `development.fallback` tells the local proxy where to send requests for apps you aren't running locally, so it points at the marketing app's production domain. That project doesn't exist until Lesson 2.5, so use `acme-marketing.vercel.app` for now and swap in your real domain then. Child apps without their own fallback borrow this one.

### Part 3: Wrap Next.js Configs

Update each application's `next.config.ts` to use the wrapper.

**Marketing** (`apps/marketing/next.config.ts`):

```typescript title="apps/marketing/next.config.ts"
import type { NextConfig } from "next";
import { withMicrofrontends } from "@vercel/microfrontends/next/config";

const nextConfig: NextConfig = {
  // Your existing config
};

export default withMicrofrontends(nextConfig);
```

**Docs** (`apps/docs/next.config.ts`):

```typescript title="apps/docs/next.config.ts"
import type { NextConfig } from "next";
import { withMicrofrontends } from "@vercel/microfrontends/next/config";

const nextConfig: NextConfig = {
  // Routes live under app/docs/, so no basePath
};

export default withMicrofrontends(nextConfig);
```

**Dashboard** (`apps/dashboard/next.config.ts`):

```typescript title="apps/dashboard/next.config.ts"
import type { NextConfig } from "next";
import { withMicrofrontends } from "@vercel/microfrontends/next/config";

const nextConfig: NextConfig = {
  // Routes live under app/app/ and app/settings/
};

export default withMicrofrontends(nextConfig);
```

All three configs look the same. `withMicrofrontends` handles the asset prefixes, and each app's folders handle the routes.

### Part 4: Keep Routes at Their Full Paths

If you've built Next.js multi-zones before, your hand is probably reaching for `basePath` right about now:

```typescript title="apps/docs/next.config.ts"
// Don't do this
const nextConfig: NextConfig = {
  basePath: "/docs",
};
```

Vercel microfrontends don't support Next.js apps that use [`basePath`](https://vercel.com/docs/microfrontends/quickstart#set-up-microfrontends-with-your-framework). The docs app receives `/docs/getting-started` with the full path intact, so it needs a route at that full path. That's why Lesson 1.4 put the docs pages under `app/docs/` instead of at the root.

There's nothing new to create here. Confirm both child apps match these trees:

```
apps/docs/app/
├── layout.tsx
└── docs/
    └── page.tsx          # handles /docs

apps/dashboard/app/
├── layout.tsx
├── app/
│   └── page.tsx          # handles /app
└── settings/
    └── page.tsx          # handles /settings
```

The folder names repeat the URL. `app/app/page.tsx` looks like a typo, and it's the correct path for `/app`.

## Why Asset Prefixes Matter

Without `withMicrofrontends`, every app serves static assets at `/_next/`:

```
marketing: /_next/static/chunks/main.js
docs:      /_next/static/chunks/main.js  ← CONFLICT!
dashboard: /_next/static/chunks/main.js  ← CONFLICT!
```

The wrapper adds unique prefixes (an obfuscated hash like `vc-ap-b3331f`):

```
marketing: /_next/static/chunks/main.js
docs:      /vc-ap-a1b2c3/_next/static/chunks/main.js
dashboard: /vc-ap-d4e5f6/_next/static/chunks/main.js
```

This prevents JavaScript and CSS from one app overwriting another's.

## Try It

At this point, the apps still run independently. The configuration prepares them for the microfrontends proxy, which we'll enable in Lesson 2.3.

Run the apps:

```bash
pnpm dev
```

Visit each and verify the Header still renders correctly:

- **<http://localhost:3000>** - Marketing
- **<http://localhost:3001/docs>** - Docs
- **<http://localhost:3002/app>** - Dashboard

## Commit

```bash
git add -A
git commit -m "feat: add microfrontends configuration"
```

## Done-When

- [ ] `@vercel/microfrontends` installed in all three apps
- [ ] `microfrontends.json` created in marketing app with correct schema (using `paths` array)
- [ ] Application keys in `microfrontends.json` match the Vercel project names (`acme-marketing`, `acme-docs`, `acme-dashboard`), which also match the `package.json` names
- [ ] All `next.config.ts` files wrapped with `withMicrofrontends`
- [ ] No app uses `basePath`, and the docs pages live under `apps/docs/app/docs/`
- [ ] Apps run without console errors

## Troubleshooting

**Asset 404s on `/_next/` paths**: You forgot `withMicrofrontends` in next.config.ts. Easy to miss.

**`does_not_match_schema` error**: You used `path` (string) instead of `paths` (array). The schema validator is picky about this.

**Build fails with `Could not find a microfrontends.json file in the repository that contains the "acme-docs" application`**: The key in `microfrontends.json` doesn't match the Vercel project name. Rename the key to the project name. If the `package.json` name is different, add `packageName` with that name. See the [troubleshooting docs](https://vercel.com/docs/microfrontends/troubleshooting).

**`/docs` returns a 404 from the docs app**: Check for a leftover `basePath` in `apps/docs/next.config.ts`, and confirm the page lives at `apps/docs/app/docs/page.tsx`.

## What's Next

Configuration done. Next lesson covers path routing in detail, including the execution order that trips up most developers.


---

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