Microfrontends

Purpose and Scope

Microfrontends split one web experience into smaller applications that can be owned, developed, and deployed independently. Turborepo’s guide focuses on vertical microfrontends, also called zones, where different URL regions are served by different frontend applications. The practical problem is local development: teams need several apps running at once, but they do not want every developer to memorize ports, manually open separate URLs, or break hot reloading when requests cross an app boundary. Turborepo addresses that workflow with a built-in local proxy that coordinates applications while the normal package tasks continue to run through the monorepo task system.

Sources: apps/docs/content/docs/guides/microfrontends.mdx

In the documented model, production and development have different composition concerns. Production may use separate deployments and compose the final site with reverse proxy rules or edge routing. Local development instead needs a unified entrypoint, path-based routing, WebSocket support, and predictable ports. Turborepo’s microfrontend support is therefore not a replacement for a production edge platform; it is a development-time routing layer that lets application teams work in a monorepo without recreating production infrastructure on every laptop. That distinction is important when deciding what belongs in framework configuration, what belongs in deployment configuration, and what belongs in the local proxy file.

Sources: apps/docs/content/docs/guides/microfrontends.mdx, apps/docs/content/docs/guides/ci-vendors/vercel.mdx

Relevant Source Files

• apps/docs/content/docs/guides/microfrontends.mdx — Defines the reader-facing microfrontends guide, the local proxy concept, the parent application convention, the sample microfrontends.json shape, port injection, and framework base-path examples.
• apps/docs/content/blog/free-vercel-remote-cache.mdx — Explains Vercel Remote Cache and the environment variables used to authenticate non-Vercel CI providers, which matters once microfrontend repositories run shared build and test tasks in CI.
• apps/docs/content/blog/joining-vercel.mdx — Provides project context for Turborepo’s Vercel-backed remote caching and open-source CLI direction.
• apps/docs/content/docs/guides/ci-vendors/github-actions.mdx — Shows a concrete CI shape for root package scripts, turbo.json tasks, package-manager setup, and optional Remote Caching credentials.
• apps/docs/content/docs/guides/ci-vendors/vercel.mdx — Documents Vercel’s zero-config Turborepo integration and automatic use of Vercel Remote Cache for deployments.
• apps/docs/content/blog/2-10.mdx — Notes development-environment reliability improvements such as graceful task shutdown, which is relevant when a microfrontend workspace runs several long-lived dev servers.

Core Workflow

Start by choosing a parent application. The parent is the application that owns the local microfrontend configuration and receives requests that do not match another application’s routing rule. In the guide’s example, a repository contains multiple frontend packages under an apps directory, such as a main web app, a docs app, and a marketing app. The parent application contains a microfrontends configuration file that names each participating application, assigns development ports, and declares route patterns for child applications. Running the normal development task through Turborepo then starts the proxy so a developer can use one local URL instead of juggling multiple app URLs.

Sources: apps/docs/content/docs/guides/microfrontends.mdx

A minimal setup has three pieces. First, create the microfrontend configuration in the parent application. Second, make each application’s development script read the port assigned by Turborepo instead of hard-coding a local port. Third, set any framework-level base path required by the app being mounted under a path segment. For Next.js, the guide uses a base path setting. For Vite, the guide uses the base option. These are framework concerns: the proxy can route traffic, but each framework still needs to generate links, assets, and client navigation that agree with the path where the application is mounted.

Sources: apps/docs/content/docs/guides/microfrontends.mdx

{
  "$schema": "https://turborepo.dev/microfrontends/schema.json",
  "applications": {
    "web": {
      "development": {
        "local": {
          "port": 3000
        }
      }
    },
    "docs": {
      "development": {
        "local": {
          "port": 3001
        }
      },
      "routing": [
        {
          "paths": ["/docs", "/docs/:path*"]
        }
      ]
    }
  }
}

Configuration and Command Surface

The public configuration surface shown in the guide is intentionally small. The root object identifies the schema and then declares applications by name. Each application can include a development local port, and routed applications can include path patterns. Requests that match those patterns are forwarded to the corresponding application; requests without a match fall through to the parent. This means route specificity and framework base paths should be reviewed together. If a child app is mounted under a path but its framework still assumes it lives at the site root, links and assets can appear to work in isolation while failing behind the proxy.

Sources: apps/docs/content/docs/guides/microfrontends.mdx

The command surface centers on normal development scripts. The guide shows Next.js using the turbo get-mfe-port command in the script so the framework receives the assigned port at startup. It also shows Vite reading the TURBO_MFE_PORT environment variable. Both patterns avoid manually synchronizing package scripts with the configuration file. The application can still use its usual framework dev server, but the port source comes from Turborepo when the workspace is launched through turbo dev. That separation keeps framework tools familiar while letting the proxy coordinate the full set of applications.

Sources: apps/docs/content/docs/guides/microfrontends.mdx

{
  "scripts": {
    "dev": "next dev --port $(turbo get-mfe-port)"
  }
}

{
  "scripts": {
    "dev": "vite dev --port $TURBO_MFE_PORT"
  }
}

Framework and Module-Federation Patterns

The microfrontends guide deliberately sits beside the framework guides for Next.js, Vite, and Rsbuild. Treat the proxy as the shared local-development layer and the framework guide as the place to resolve framework-specific behavior. Next.js applications commonly need basePath alignment when mounted under a route segment. Vite applications use a base setting for similar reasons. Rsbuild and module-federation-oriented examples should be approached the same way: keep Turborepo responsible for task orchestration and local routing, then let the framework or bundler own module loading, asset paths, and any federation-specific runtime configuration.

Sources: apps/docs/content/docs/guides/microfrontends.mdx

This division also helps teams decide how to structure ownership. A docs team can own the docs app, a marketing team can own the marketing app, and the parent application can own the fallback shell and cross-zone routing contract. Turborepo does not require those applications to share one framework. The example mixes Next.js-style and Vite-style configuration, which reinforces that the proxy is path-oriented rather than framework-specific. Shared packages, such as design systems or TypeScript configuration, still behave like normal internal packages in the monorepo and should be wired through package manager workspace dependencies and task dependencies rather than through the proxy.

Sources: apps/docs/content/docs/guides/microfrontends.mdx

CI, Deployment, and Caching Considerations

A microfrontend monorepo usually has more packages and more repeated work than a single application repository, so CI should run Turborepo tasks from the root rather than invoking every app manually. The GitHub Actions guide shows root scripts for build and test that delegate to turbo run commands, plus a turbo.json where build outputs and dependency relationships are declared. That pattern applies directly to microfrontends: each app can define its own scripts, while the root task graph decides ordering, caching, and reuse. When Remote Caching is enabled, unchanged work can be restored across developers and CI jobs instead of being recomputed.

Sources: apps/docs/content/docs/guides/ci-vendors/github-actions.mdx, apps/docs/content/blog/free-vercel-remote-cache.mdx

Vercel deployment has a simpler integration path because Turborepo repositories imported into Vercel are pre-configured to use Vercel Remote Cache, and commands running on Vercel automatically benefit from that cache. On other CI providers, the remote cache blog and GitHub Actions guide point to TURBO_TOKEN and TURBO_TEAM as the authentication values to provide. This does not change the local proxy setup, but it changes the economics of a multi-app repository: builds, tests, and checks for shared packages or frontend zones can be reused across branches, pull requests, and machines when their task inputs have not changed.

Sources: apps/docs/content/docs/guides/ci-vendors/vercel.mdx, apps/docs/content/blog/free-vercel-remote-cache.mdx, apps/docs/content/docs/guides/ci-vendors/github-actions.mdx

Operational Notes and Next Steps

Because the microfrontend workflow runs several long-lived development servers, shutdown and signal behavior matter. Turborepo 2.10 release notes describe graceful task shutdown: when the development environment receives an interrupt or termination signal, Turborepo forwards it to tasks and waits for them to finish cleanup. That reliability improvement is especially useful for microfrontend workspaces where multiple framework dev servers, background services, or loggers may be active. Developers should still make their app scripts handle termination cleanly, but the task runner is designed to give those processes an opportunity to close rather than being abruptly killed.

Sources: apps/docs/content/blog/2-10.mdx

To adopt this workflow, begin with a small parent-and-child setup before adding more zones. Confirm that the parent fallback works, then add one routed application, assign ports through the Turborepo mechanism, and verify framework base paths under the unified local URL. After local routing works, review CI task definitions and enable Remote Caching so multi-app builds remain fast. For deeper setup, read the framework guide for the frontend stack you use, then pair this page with the task configuration, remote caching, and CI vendor pages so local development, pull requests, and deployments all follow the same task graph.

Sources: apps/docs/content/docs/guides/microfrontends.mdx, apps/docs/content/docs/guides/ci-vendors/github-actions.mdx, apps/docs/content/docs/guides/ci-vendors/vercel.mdx