Local Development

The local proxy stitches your apps together so you can test microfrontends routing without deploying.

Outcome

Run all three applications through the microfrontends proxy at localhost:3024 with working cross-app navigation.

The Local Proxy

The @vercel/microfrontends package includes a development proxy that mimics Edgenivo's production routing locally:

localhost:3024 (proxy)
├── /              → localhost:3000 (marketing)
├── /pricing       → localhost:3000 (marketing)
├── /docs/*        → localhost:3001 (docs)
├── /app/*         → localhost:3002 (dashboard)
└── /settings/*    → localhost:3002 (dashboard)

When you visit localhost:3024/docs, the proxy routes to the docs app at localhost:3001.

Fast Track

1. Add localProxyPort to microfrontends.json
2. Run pnpm dev from the root
3. Visit localhost:3024 to see the stitched application

Hands-on Exercise 2.3

Enable and test the local development proxy.

Part 1: Configure the Proxy Port

Update apps/marketing/microfrontends.json:

{
  "$schema": "https://openapi.vercel.sh/microfrontends.json",
  "applications": {
    "@acme/marketing": {
      "development": {
        "fallback": "http://localhost:3000",
        "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
      }
    }
  },
  "options": {
    "localProxyPort": 3024
  }
}

development.local is the port each app runs on. development.fallback points to production when you're not running an app locally.

Part 2: Start All Apps

From the monorepo root:

pnpm dev

You should see output like:

• Packages in scope: @acme/ui, dashboard, docs, marketing
• Running dev in 3 packages

marketing:dev: ready - started server on 0.0.0.0:3000
docs:dev: ready - started server on 0.0.0.0:3001
dashboard:dev: ready - started server on 0.0.0.0:3002

The proxy starts automatically when Turborepo detects microfrontends configuration.

Part 3: Test Cross-App Navigation

Open http://localhost:3024 in your browser.

1. Marketing homepage loads - You're at / served by marketing app
2. Click "Docs" in the header - Navigates to /docs served by docs app
3. Click "Dashboard" in the header - Navigates to /app served by dashboard app
4. Click "Home" in the header - Back to / served by marketing app

All navigation happens through the same domain (localhost:3024), just like production.

Try It

Verify routing with the browser's network tab:

1. Open DevTools → Network
2. Visit localhost:3024/docs
3. Look at the request - it's to localhost:3024/docs
4. The proxy forwards it to localhost:3001/docs

You can also test that paths reach the correct app:

Debugging Proxy Issues

If something isn't routing correctly, enable debug logging. Set the MFE_DEBUG=1 environment variable, or pass debug: true to withMicrofrontends.

Check Proxy Status

The proxy logs which app it routes to:

[proxy] GET /docs → docs (localhost:3001)
[proxy] GET /app → dashboard (localhost:3002)

Common Issues

Proxy not starting: Check that every app lists @vercel/microfrontends as a dependency and that you start the apps through turbo. localProxyPort is optional and only changes the port.

Wrong app serves route: Your path pattern probably doesn't match what you think. Double-check the routing array.

Port 3024 already in use: Something else grabbed that port. Change localProxyPort or kill the other process.

Hybrid Local/Production Development

You can run some apps locally while pointing others to production:

{
  "applications": {
    "@acme/marketing": {
      "development": {
        "fallback": "http://localhost:3000",
        "local": 3000
      }
    },
    "@acme/docs": {
      "routing": [
        {
          "paths": ["/docs", "/docs/:path*"]
        }
      ],
      "development": {
        "fallback": "https://docs.acme-platform.vercel.app"
      }
    }
  }
}

With this config, /docs/* routes to the production docs deployment while you develop marketing locally. Useful when you only need to work on one app.

With Turborepo 2.3.6, or 2.4.2 or newer, the proxy starts automatically on turbo dev. Run a single app with turbo run dev --filter=marketing.

Commit

git add -A
git commit -m "feat: configure local development proxy"

Done-When

• All three apps running through proxy at localhost:3024
• Navigation between apps works (/, /docs, /app)
• Each path serves content from the correct app
• You understand hybrid local/production development

What's Next

Notice the hard page reloads when navigating between apps. No shared client-side router. Next, you'll build shared packages for components that need to appear across all apps.