Next.js

Purpose and Scope

This page explains how the Turborepo documentation presents Next.js as a framework integration inside a JavaScript and TypeScript monorepo. The source guide treats Next.js as the React framework for the web and focuses on the practical steps for adding applications, connecting internal packages, and adjusting framework-specific settings when a repository grows beyond a single app. The important reader problem is not how to learn every Next.js feature, but how to make a Next.js application behave as one package in a Turborepo workspace where shared packages, root task definitions, and deployment patterns all need to line up.

Sources: apps/docs/content/docs/guides/frameworks/nextjs.mdx, apps/docs/content/docs/guides/frameworks/index.mdx

Turborepo’s framework section explicitly says that Turborepo works with any framework, then offers focused guides for popular frontend frameworks. That positioning matters because the Next.js page is not a special execution engine; it is an integration recipe layered on top of the same package and task model used by the rest of the project. The framework navigation metadata lists Next.js alongside SvelteKit, Vite, Rsbuild, Nuxt, and framework bindings, so treat this page as one framework-specific branch of a broader pattern for adding web apps to a shared workspace.

Sources: apps/docs/content/docs/guides/frameworks/index.mdx, apps/docs/content/docs/guides/frameworks/meta.json

Relevant Source Files

• apps/docs/content/docs/guides/frameworks/nextjs.mdx - Defines the Next.js guide, including quickstart commands, create-next-app setup, internal package installation examples, package configuration guidance, and the microfrontend basePath note.
• apps/docs/content/docs/guides/frameworks/framework-bindings.mdx - Explains how shared library packages can expose Next.js-specific bindings through peer dependencies and export paths.
• apps/docs/content/docs/guides/frameworks/index.mdx - Establishes the framework guide section and states that Turborepo works with any framework while linking to Next.js and related framework guides.
• apps/docs/content/docs/guides/frameworks/meta.json - Shows the ordering of framework pages, including Next.js and framework bindings.
• apps/docs/content/docs/guides/frameworks/nuxt.mdx - Provides a comparable framework guide with the same integration structure and a microfrontend asset-prefix setting for Nuxt.
• apps/docs/content/docs/guides/frameworks/rsbuild.mdx - Provides a comparable framework guide with the same integration structure plus Rsbuild-specific microfrontend and module federation notes.

Core Workflow

The fastest path is to create a new Turborepo repository from the official starter. The Next.js guide says the quickstart creates a repository with two Next.js applications, which is useful for learning the shape of a multi-app workspace before adding custom packages or changing task definitions. Choose the command for the package manager your repository will use, then inspect the generated apps and packages to see how root configuration and package scripts cooperate. This path is best for new teams because the starting point already demonstrates the monorepo relationship between applications and shared code.

Sources: apps/docs/content/docs/guides/frameworks/nextjs.mdx

pnpm dlx create-turbo@latest

yarn dlx create-turbo@latest

npx create-turbo@latest

bunx create-turbo@latest

For an existing repository, the guide uses the Next.js project generator rather than a Turborepo-specific application generator. Run the command from the workspace root and place the application under an application directory such as apps/my-app. After that, the new package becomes part of the repository’s workspace once the package manager install step has been run and the workspace configuration recognizes the directory. This sequence keeps framework scaffolding in the framework’s tool while leaving orchestration, task ordering, and caching to Turborepo.

Sources: apps/docs/content/docs/guides/frameworks/nextjs.mdx

pnpm dlx create-next-app@latest apps/my-app

yarn dlx create-next-app@latest apps/my-app

npx create-next-app@latest apps/my-app

bunx create-next-app@latest apps/my-app

Integrating Internal Packages

After a Next.js app exists, the next integration step is usually consuming shared workspace packages. The guide demonstrates adding an internal package such as a shared user interface library to the app’s dependencies. The version specifier depends on the package manager: pnpm and Bun examples use a workspace protocol, while Yarn and npm examples use a wildcard. The functional goal is the same in all cases. The application declares that it depends on the internal package, the package manager installs or links it, and Turborepo can then understand the dependency relationship when tasks are scheduled.

Sources: apps/docs/content/docs/guides/frameworks/nextjs.mdx

{
  "name": "my-app",
  "dependencies": {
+   "@repo/ui": "workspace:*"
  }
}

The guide also calls out two follow-up checks that are easy to miss. First, run the package manager’s install command after editing dependencies, because the workspace graph is only useful when the package manager has updated its installation state. Second, review the app’s package scripts, because a generated Next.js app may not use exactly the task names your root Turborepo configuration expects. A common team convention is to align scripts like build, dev, lint, and typecheck across applications so root commands can target consistent task names without per-app surprises.

Sources: apps/docs/content/docs/guides/frameworks/nextjs.mdx

Task Configuration and Framework Behavior

A newly added Next.js application uses tasks from the root Turborepo configuration by default. That means a repository-level task definition can cover the new app immediately, provided the app exposes matching scripts. When the app needs different inputs, outputs, dependencies, or behavior than other packages, the guide points readers to package configurations. This is the supported escape hatch for package-specific task behavior. In practice, use the root configuration for shared conventions and reach for package-level configuration only when a Next.js app has a legitimate difference from the rest of the workspace.

Sources: apps/docs/content/docs/guides/frameworks/nextjs.mdx

Turborepo does not replace Next.js build semantics. Instead, it coordinates when package scripts run, how dependencies between packages affect ordering, and whether previous task results can be reused through the normal task and cache model. The framework guide’s task note is intentionally small because the core behavior lives in Turborepo concepts and reference pages, not in a Next.js-only API. For maintainability, keep framework commands inside the app’s package scripts, keep shared orchestration in root task definitions, and document any package-specific override near the app that needs it.

Sources: apps/docs/content/docs/guides/frameworks/nextjs.mdx

Microfrontends and Asset Paths

When using Next.js with Turborepo microfrontends, the guide highlights one framework-specific requirement: child applications need the Next.js base path configured so assets such as images and CSS route to the correct application. This is an example of the boundary between Turborepo and the framework. Turborepo can coordinate multiple applications in the same repository, but the framework still owns how its runtime serves assets under a nested route. For a child app mounted under a path such as docs, configure the application itself so generated URLs and static assets resolve from that path.

Sources: apps/docs/content/docs/guides/frameworks/nextjs.mdx

import type { NextConfig } from "next";
 
const nextConfig: NextConfig = {
  basePath: "/docs",
};
 
export default nextConfig;

The sibling Nuxt and Rsbuild guides show the same Turborepo pattern with different framework settings. Nuxt uses a base setting in Vite configuration for child applications, while Rsbuild uses server base and notes that this value becomes the default asset prefix for development and production assets. Those comparisons reinforce the rule for Next.js teams: do not copy another framework’s option name, but do carry over the intent. In every case, child applications in a microfrontend setup need a framework-owned asset path setting that matches where the app is mounted.

Sources: apps/docs/content/docs/guides/frameworks/nuxt.mdx, apps/docs/content/docs/guides/frameworks/rsbuild.mdx, apps/docs/content/docs/guides/frameworks/nextjs.mdx

Framework Bindings in Shared Libraries

The framework bindings guide explains how a shared library can integrate more deeply with Next.js without directly owning the framework installation. A library package can declare Next.js as a peer dependency, allowing consumers to provide the actual installed version. That pattern is useful for packages such as a shared user interface library that exports a customized link component built on top of the Next.js Link component. The consumer application’s Next.js version determines the types and APIs resolved by the library, so teams should choose peer dependency ranges deliberately rather than treating them as incidental metadata.

Sources: apps/docs/content/docs/guides/frameworks/framework-bindings.mdx

The same guide recommends splitting framework-specific bindings with export paths when a package supports multiple frameworks. For example, a design system can expose a generic link entrypoint and a Next.js-specific link entrypoint. This separation helps bundlers understand which framework the consuming application intends to target and reduces the chance of confusing framework code being pulled into the wrong app. For a Next.js monorepo, this approach is cleaner than making every consumer import from one broad package surface that mixes generic components with framework-only components.

Sources: apps/docs/content/docs/guides/frameworks/framework-bindings.mdx

Next Steps

Use this guide as the Next.js-specific layer on top of the broader Turborepo workflow. Start with create-turbo when you want a working multi-application example, use create-next-app when adding to an existing workspace, then wire internal packages through normal package manager dependencies. After the application builds and runs, review root task definitions, decide whether package-level task configuration is necessary, and add the Next.js base path if the app participates in a microfrontend deployment. For deeper follow-up, read the pages on internal packages, package configurations, microfrontends, framework bindings, and the turbo run command.

Sources: apps/docs/content/docs/guides/frameworks/nextjs.mdx, apps/docs/content/docs/guides/frameworks/framework-bindings.mdx