OpenWikivercel/turborepo

Single-package Workspaces

Purpose and Scope

A single-package workspace is a repository that contains one application package rather than a package-manager workspace full of apps and libraries. Turborepo is often introduced as a monorepo build system, but the guide makes clear that the same task runner can also improve standalone applications created by tools such as Next.js or Vite starters. The important distinction is not whether the repository has many folders; it is whether Turborepo can discover multiple packages and build package relationships. In single-package mode, the useful benefits are task caching, remote cache sharing, parallel execution, and repeatable command orchestration, not package-to-package graph traversal.

Sources: apps/docs/content/docs/guides/single-package-workspaces.mdx

Use this page when you have one deployable application and want a disciplined workflow without converting the project into a monorepo. The official guide frames this as an incremental adoption path: install the Turbo CLI, keep the existing package scripts, and introduce a small task configuration only where it provides value. A first run may simply execute the existing build script, while a later configuration can sequence setup work, run checks in parallel, or make CI reuse local and remote cache artifacts. The result is a faster standalone project that still feels like the package you already maintain.

Sources: apps/docs/content/docs/guides/single-package-workspaces.mdx, apps/docs/content/docs/core-concepts/package-and-task-graph.mdx

Relevant Source Files

  • apps/docs/content/docs/guides/single-package-workspaces.mdx — Main user guide for installing Turbo in a standalone application, running package scripts, sequencing setup tasks, and parallelizing checks.
  • apps/docs/content/docs/messages/package-task-in-single-package-workspace.mdx — Troubleshooting page explaining why package-scoped task names are invalid when there is only one package.
  • apps/docs/content/docs/core-concepts/package-and-task-graph.mdx — Concept page defining package graphs and task graphs, which explains why single-package workspaces still benefit from task relationships.
  • apps/docs/content/docs/core-concepts/package-types.mdx — Concept page distinguishing application packages from library packages, useful for deciding whether the repository should stay single-package or become multi-package.
  • apps/docs/content/docs/crafting-your-repository/creating-an-internal-package.mdx — Guide showing what changes when shared code becomes an internal package and Turborepo starts using package relationships.
  • apps/docs/content/docs/messages/unnecessary-package-task-syntax.mdx — Troubleshooting page for package-level configuration where package prefixes are unnecessary, reinforcing when plain task names are expected.

Core Primitives

The core primitive in a single-package workspace is the task, which usually corresponds to a package script such as build, dev, lint, type checking, formatting, database setup, or test execution. Turborepo reads task relationships from the task configuration and turns them into a task graph. A task graph is a directed ordering of work: one task can depend on another task, so the prerequisite finishes before the dependent task begins. In a monorepo, that graph may combine package relationships and task relationships. In a single package, the graph is simpler, but it is still valuable because it can encode setup order and safe parallelism.

Sources: apps/docs/content/docs/guides/single-package-workspaces.mdx, apps/docs/content/docs/core-concepts/package-and-task-graph.mdx

Caching is the second primitive to understand. The single-package guide explicitly says local caching and Remote Caching still work, which means repeated work can be restored instead of executed when the inputs have not changed. The page also cautions that a lone build command may not show much value if every rebuild follows a code change, because the cache will miss when relevant inputs change. The adoption pattern is therefore to identify repeatable checks, setup steps, or CI tasks where stable inputs are common enough for cache reuse to matter. Parallelization complements caching by running independent scripts together when task dependencies allow it.

Sources: apps/docs/content/docs/guides/single-package-workspaces.mdx

Installation and First Run

Install Turbo as a development dependency in the application so the repository has a reproducible CLI version. The guide provides package-manager commands for pnpm, Yarn, npm, and Bun. A global installation is optional for developer convenience, but the local dependency is the safer project contract because it travels with the repository. After installation, running the CLI with a task name can execute the matching package script. For example, if the application already has a build script, a Turbo build command runs that script and subsequent identical runs can be served from cache.

Sources: apps/docs/content/docs/guides/single-package-workspaces.mdx

pnpm add turbo --save-dev
yarn add turbo --dev
npm install turbo --save-dev
bun install turbo --dev

The fastest useful first configuration is usually not a large rewrite. Keep the existing package scripts and add only the task relationships that describe real workflow constraints. The guide’s setup example uses a development command that must wait for database setup, schema push, and seed work. Those scripts are ordinary package scripts, but the task configuration makes their ordering explicit. When a developer starts the development task through Turbo, the setup sequence runs first, then the persistent development server starts. This is a better fit than asking each developer to remember a series of commands or encoding everything in one fragile shell script.

Sources: apps/docs/content/docs/guides/single-package-workspaces.mdx

{
  "tasks": {
    "dev": {
      "dependsOn": ["db:seed"],
      "cache": false,
      "persistent": true
    },
    "db:seed": {
      "dependsOn": ["db:push"],
      "cache": false
    },
    "db:push": {
      "dependsOn": ["db:up"],
      "cache": false
    },
    "db:up": {
      "cache": false
    }
  }
}

System-to-Code Mapping

The single-package guide maps directly to a practical subset of Turborepo behavior. Its installation section establishes the CLI dependency. Its global command note explains that a task name can resolve to an existing package script. Its multi-script example demonstrates task dependencies, disabled cache for side-effectful setup, and persistent development processes. The package-and-task graph concept page supplies the model behind that behavior: tasks are nodes, dependency declarations are directed edges, and the runner can determine an execution order. In a one-package repository, there may be no meaningful package graph, but the task graph remains the source of orchestration.

Sources: apps/docs/content/docs/guides/single-package-workspaces.mdx, apps/docs/content/docs/core-concepts/package-and-task-graph.mdx

The package-type concept page helps decide whether the single-package model is still appropriate. It describes application packages as deployable units, often framework applications or command-line applications, and library packages as shared code that supports applications rather than being deployed independently. A standalone Next.js or Vite project is naturally an application package. If the repository begins accumulating reusable code that several deployables need to import, the creating-an-internal-package guide shows the multi-package direction: create a discoverable package with its own package metadata, exports, scripts, and dependencies. That change gives Turborepo package relationships to understand, which is beyond single-package mode.

Sources: apps/docs/content/docs/core-concepts/package-types.mdx, apps/docs/content/docs/crafting-your-repository/creating-an-internal-package.mdx

Task Configuration Patterns

Use plain task names in single-package workspaces. The troubleshooting page for package tasks states that package-scoped declarations are not permitted in single-package mode because there cannot be multiple packages to disambiguate. A configuration key shaped like a package name plus task name should be rewritten as the task name alone. This rule is easy to miss when copying examples from monorepo documentation, where package-specific targeting may appear. In a standalone app, the package is already implied, so the configuration should describe the task, its dependencies, cache behavior, outputs, and whether it is persistent.

Sources: apps/docs/content/docs/messages/package-task-in-single-package-workspace.mdx, apps/docs/content/docs/messages/unnecessary-package-task-syntax.mdx

A useful pattern is to separate deterministic checks from side-effectful runtime setup. Linting, type checking, formatting checks, tests, and production builds are often cacheable when their inputs are well defined. Database startup, schema mutation, seeding a local database, and long-running development servers are usually not cacheable because their value is the live side effect. The guide’s example disables caching for database setup and marks the development task as persistent. That combination tells the reader that Turbo is not only for build outputs; it is also a declarative scheduler for everyday workflows where some tasks should be ordered but not cached.

Sources: apps/docs/content/docs/guides/single-package-workspaces.mdx

Execution Flow and Edge Cases

A typical adoption flow starts by installing Turbo locally, then running one existing script through Turbo to verify the CLI works. Next, choose a workflow that currently requires several manual commands and represent each command as a package script. Add task dependencies so Turbo can run prerequisites in order. Finally, identify independent checks and let Turbo parallelize them. This approach avoids changing the application architecture before the team has measured value. It also leaves the door open for remote caching in CI, where the same task definitions can reduce repeated work across machines.

Sources: apps/docs/content/docs/guides/single-package-workspaces.mdx

The primary edge case is accidental monorepo syntax. If a single-package configuration declares a package-scoped task, the fix is to remove the package prefix. A related troubleshooting page says the same principle applies inside a package-level configuration file: when a configuration already applies to a specific package, the package name is unnecessary. The broader lesson is that task keys should match the scope of the configuration file. In a root single-package configuration, the scope is the only package. In a package-level configuration within a larger workspace, the scope is also already narrowed to that package.

Sources: apps/docs/content/docs/messages/package-task-in-single-package-workspace.mdx, apps/docs/content/docs/messages/unnecessary-package-task-syntax.mdx

When to Stay Single-package Versus Split Packages

Stay single-package when the repository has one deployable application, shared code does not need independent package boundaries, and the team primarily wants faster scripts, repeatable setup, and CI acceleration. This keeps the mental model small: package scripts remain the public surface, and Turbo adds scheduling and caching around them. Split into multiple packages when shared code becomes a product of the repository itself, when multiple deployables should depend on common libraries, or when package boundaries clarify ownership and release behavior. The internal package guide shows that this transition requires package metadata and workspace discovery, not just moving files into a folder.

Sources: apps/docs/content/docs/core-concepts/package-types.mdx, apps/docs/content/docs/crafting-your-repository/creating-an-internal-package.mdx

Next Steps

After configuring a standalone application, read the caching and remote caching material to understand why tasks hit or miss cache and how artifacts are shared across machines. If your team needs to skip work in deployment pipelines, the single-package guide points readers toward skipping-task workflows. If the repository grows into multiple packages, move next to package and task graphs, package types, internal packages, and repository structuring. Those pages explain the additional model Turborepo uses when there are several applications and libraries instead of one package with a focused task graph.

Sources: apps/docs/content/docs/guides/single-package-workspaces.mdx, apps/docs/content/docs/core-concepts/package-and-task-graph.mdx

Ask a question...