Framework Guides

Purpose and Scope

The framework guides section is the entry point for applying Turborepo to application stacks rather than to a generic workspace in the abstract. Its overview page states the key positioning directly: Turborepo works with any framework, while the documentation provides focused guides for common frontend frameworks. That makes this page useful when a team already knows the framework it wants to use, but needs to understand how Turborepo should coordinate that framework's build, development, and package-sharing behavior inside a monorepo. Sources: apps/docs/content/docs/guides/frameworks/index.mdx

This section should be read as a bridge between core Turborepo concepts and practical framework integration work. Core concepts explain packages, tasks, dependency graphs, caching, and environment inputs; framework guides show how those concepts appear in real projects such as Next.js, SvelteKit, Vite, Nuxt, and Rsbuild. The source-backed navigation metadata lists those framework pages alongside a separate framework-bindings guide, which signals that framework integration is not only about application configuration. It also includes library packages that expose framework-specific entrypoints. Sources: apps/docs/content/docs/guides/frameworks/meta.json

Relevant Source Files

apps/docs/content/docs/guides/frameworks/index.mdx — Defines the reader-facing framework overview, including the claim that Turborepo works with any framework and the card links for common framework guides.
apps/docs/content/docs/guides/frameworks/meta.json — Defines the ordered framework section navigation: Next.js, SvelteKit, Vite, Rsbuild, Nuxt, and framework bindings.
apps/docs/content/docs/guides/frameworks/framework-bindings.mdx — Documents how shared library packages can create framework-specific integrations through peer dependencies and export paths.

The framework overview is intentionally compact, but its metadata gives the structure of the section. The visible cards in the overview point readers to Next.js, SvelteKit, Vite, and Nuxt, while the navigation file also includes Rsbuild and framework bindings. In practice, a reader should choose the framework page when configuring an application package, then use the framework-bindings material when a shared package needs to import framework APIs directly. The separation keeps application setup distinct from reusable library design, even though both belong to the same integration area. Sources: apps/docs/content/docs/guides/frameworks/index.mdx, apps/docs/content/docs/guides/frameworks/meta.json

A useful way to navigate this section is to start with the framework that owns the runtime of the application. For example, an app package using Next.js should be aligned with the Next.js guide before the team decides how shared UI components interact with Next.js APIs. A Vite or Nuxt application follows the same pattern: first establish the application-level Turborepo tasks and package relationships, then decide whether any internal package should publish a framework-aware surface. This keeps the monorepo graph understandable and avoids hiding runtime assumptions inside general-purpose packages.

Framework Bindings Concept

A framework binding is a library-package interface that intentionally uses APIs from a framework. The framework-bindings guide defines this as integrating library code more deeply with a framework by leveraging the framework's APIs directly in the library. That is different from a plain shared package that only exports framework-neutral utilities or components. The binding package gains access to the framework through a peer dependency, so the consuming application provides the framework version while the library can still type-check and author code against that framework's public API. Sources: apps/docs/content/docs/guides/frameworks/framework-bindings.mdx

The documented example uses Next.js, but the guide explicitly frames the pattern as applicable to any framework or other dependency. The library package adds a peer dependency for the dependency it wants to bind to, such as Next.js. That peer dependency makes the framework API available without forcing the library package to install and own the framework version independently. As a result, if applications in the workspace use a particular Next.js version, the library resolves the corresponding Next.js APIs and types from those consumers. Sources: apps/docs/content/docs/guides/frameworks/framework-bindings.mdx

{
  "name": "@repo/ui",
  "peerDependencies": {
    "next": "*"
  }
}

The peer dependency version range is an important design choice. The docs example accepts any version, but the same source notes that a real package may want a more specific range, such as requiring a minimum framework version. The guide also calls out older package-manager behavior: some setups may need configuration that installs peer dependencies, or a development dependency workaround so the library can be developed locally. Those details matter because a framework binding is coupled to framework APIs, and unresolved or mismatched peers can become install-time or type-checking problems. Sources: apps/docs/content/docs/guides/frameworks/framework-bindings.mdx

Entrypoints and Package Design

The framework-bindings guide recommends export paths when a library supports multiple framework-specific variants. Splitting a package into entrypoints gives bundlers a clearer signal about which framework target the consumer selected, and the guide says this reduces the chance of strange bundling errors. The example separates a generic link component from a Next.js-specific link component, allowing a design-system package to expose a default HTML anchor implementation and a framework-aware wrapper without making every consumer load or resolve every framework integration. Sources: apps/docs/content/docs/guides/frameworks/framework-bindings.mdx

{
  "exports": {
    "./link": "./dist/link.js",
    "./next-js/link": "./dist/next-js/link.js"
  },
  "peerDependencies": {
    "next": "*"
  }
}

This entrypoint design is especially useful in Turborepo workspaces because internal packages are commonly shared by several applications. A single UI package might be consumed by a Next.js app, a SvelteKit app, and a framework-neutral package. If the UI package exposes separate framework entrypoints, each application imports the binding that matches its runtime, while general consumers can continue to use neutral exports. The resulting package boundary is explicit: application packages opt into framework coupling, and the shared package documents those choices through its exports map and peer dependency fields.

Applying the Guidance

When adding a new framework to a Turborepo workspace, begin with the framework guide that matches the application package and use the core Turborepo task model to decide which scripts should be cacheable, persistent, or environment-sensitive. Then review framework bindings only if an internal package needs to call framework APIs directly. If the shared package only exposes plain components, utilities, or generated assets, a framework-neutral package may remain simpler. If it wraps router components, image components, server APIs, or other framework-specific primitives, model that relationship explicitly as a binding.

The next decision is whether the binding belongs in the same package as neutral exports or in a separate package. The source guide favors export paths for splitting framework-specific entrypoints within a package, but the same reasoning can inform package boundaries: keep the import path clear, keep peer dependencies visible, and avoid surprising downstream consumers. In most design-system cases, an exports map with neutral and framework-specific paths is a good first step. In more complex cases, separate packages may make ownership, versioning, or release constraints easier to reason about.

Next Steps

Use this page as the orientation layer for the framework section. Choose the specific framework guide for application setup, then return to framework bindings when shared packages need deeper integration with framework APIs. For repository design background, read the internal-packages and structuring-repository pages before turning a binding pattern into a long-lived package convention. For runtime correctness, pair framework setup with the environment-variables and configuration references, because framework builds often depend on environment inputs that must be included in Turborepo hashing and task execution decisions.

Ask a question...