Core Concepts Overview
Purpose and Scope
The Core Concepts section is the conceptual on-ramp for Turborepo. It exists before the task-configuration and repository-crafting material because new users need a shared vocabulary before they decide how to structure packages, define tasks, or reason about build performance. The source page identifies itself as an overview for the Turborepo product and summarizes the section as a place to explore the foundational concepts that power Turborepo’s monorepo tooling. In practice, that means this page should help you recognize the core ideas, understand how they relate, and choose the next detailed page to read.
Sources: apps/docs/content/docs/core-concepts/index.mdx
The overview is intentionally concise in the repository: it is a routing page made of cards, not a long tutorial. Those cards define the section’s scope by naming four concepts: Remote Caching, Package types, Internal Packages, and Package and Task Graphs. The companion metadata file uses the same four entries as the ordered page list for the section. Treat that order as the first-party learning path: first understand how repeated work can be avoided, then distinguish kinds of packages, then learn how shared code is represented, and finally connect packages and scripts through Turborepo’s graph model.
Sources: apps/docs/content/docs/core-concepts/index.mdx, apps/docs/content/docs/core-concepts/meta.json
Relevant Source Files
- apps/docs/content/docs/core-concepts/index.mdx — Defines the Core concepts overview page, including frontmatter, summary text, related links, and the four visible documentation cards.
- apps/docs/content/docs/core-concepts/meta.json — Defines the ordered child pages for the Core Concepts section: remote-caching, package-types, internal-packages, and package-and-task-graph.
Core Primitives
Remote Caching is introduced with the reader-facing promise to “save time by never doing the same work twice.” At the overview level, that is the important mental model: Turborepo is not only a command runner, it is designed around avoiding redundant work when previous task results can be reused. Before learning cache keys, artifact storage, authentication, or CI cache sharing, understand the goal: identical work should not need to be recomputed across a workspace or across environments that can share cache artifacts.
Sources: apps/docs/content/docs/core-concepts/index.mdx
Package types are presented as “Application and Library Packages.” This distinction is foundational because a monorepo usually contains deployable units and reusable units at the same time. An application package is typically the thing a user runs, serves, builds, or deploys. A library package is typically consumed by another package and exists to share implementation, configuration, or types. The overview does not prescribe a directory layout, but it does tell you that successful Turborepo usage starts by identifying what kind of package each workspace member is meant to be.
Sources: apps/docs/content/docs/core-concepts/index.mdx
Internal Packages are described as the way to “easily share code inside your repository.” This concept narrows the general package-type discussion to a common monorepo need: local reuse without publishing every shared module externally. Internal packages let teams move repeated code, configuration, or type definitions into a workspace package that other packages can depend on. The overview links this as its own concept because sharing code changes how tasks relate, how dependencies are managed, and how repository boundaries are maintained over time.
Sources: apps/docs/content/docs/core-concepts/index.mdx
Package and Task Graphs are introduced as the concept for understanding “how Turborepo relates your tasks to each other.” A package graph describes relationships among packages, while a task graph describes the work Turborepo must schedule across those packages. Even before reading the detailed graph page, this distinction helps explain why Turborepo documentation repeatedly talks about packages and tasks together: the tool needs to know both where code lives and which scripts depend on other scripts before it can run work efficiently.
Sources: apps/docs/content/docs/core-concepts/index.mdx
System-to-Code Mapping
The source-backed structure of the Core Concepts section is small but deliberate. The MDX page supplies public documentation frontmatter: title, description, product, type, summary, and related links. Those fields establish that this is not a command reference or configuration guide; it is an overview page for learning. The body then renders four cards. Each card has a title, a target href under /docs/core-concepts, and a short description. This gives the documentation site a reader-friendly landing page while keeping the detailed explanations in separate pages.
Sources: apps/docs/content/docs/core-concepts/index.mdx
The metadata file maps the same concept set into the documentation navigation. Its pages array contains remote-caching, package-types, internal-packages, and package-and-task-graph. That ordering matters for readers because it is the section’s table of contents, not just a list of files. When maintaining this documentation area, a new concept should not only be linked in the MDX content; it should also be added to the metadata so the sidebar and section structure stay aligned with the visible overview.
Sources: apps/docs/content/docs/core-concepts/meta.json
| Concept | Source label | Reader question it answers | Where it leads next |
|---|---|---|---|
| Remote caching | Remote Caching | How does Turborepo avoid repeating work? | Remote caching and caching behavior |
| Package categories | Package types | What kinds of packages exist in my workspace? | Repository structure and package design |
| Shared workspace code | Internal Packages | How do packages share code inside the repository? | Internal package strategies |
| Execution relationships | Package and Task Graphs | How are tasks related across packages? | Task graph and task configuration |
Learning Path Before Configuration
Read this overview before writing a complex turbo.json because configuration is easier when you can name the model you are configuring. If you do not yet know which packages are applications and which are libraries, task definitions will be harder to reason about. If shared code is not represented as an internal package, dependencies may be hidden in conventions rather than visible in the workspace. If package and task relationships are unclear, a task pipeline can look like a list of scripts instead of a graph of work.
Sources: apps/docs/content/docs/core-concepts/index.mdx, apps/docs/content/docs/core-concepts/meta.json
A useful first pass is to map your own repository to the four cards. Identify the work you repeat often and ask whether caching should make it faster. List each workspace package and decide whether it is an application package, a library package, or a shared internal package. Then list the tasks those packages expose, such as build, test, lint, or dev, and ask which tasks must happen before others. This exercise turns the overview from navigation into a practical model for later configuration.
Sources: apps/docs/content/docs/core-concepts/index.mdx
After that first pass, move from concepts to implementation guides. The repository-crafting section is the natural continuation because it applies these concepts to structuring a repository, managing dependencies, creating internal packages, configuring tasks, and running work. The official Core Concepts overview also links related concept pages directly, so readers who already know their repository shape can jump to the specific idea they need. Use the overview as a checkpoint: if a later guide mentions remote caching, internal packages, or task graphs, return here to reconnect the term to the broader model.
Sources: apps/docs/content/docs/core-concepts/index.mdx
Implementation Details for Documentation Maintainers
When editing the Core Concepts overview, keep its role narrow. The MDX source declares type: overview and uses cards instead of long procedural content, so the page should remain a gateway to the detailed concept pages rather than duplicating them. The body text should orient readers, and the cards should stay focused on durable concepts that belong before command references. If a proposed addition is really a task option, package field, or CLI flag, it probably belongs in a reference page instead of this overview.
Sources: apps/docs/content/docs/core-concepts/index.mdx
Keep the overview page and metadata synchronized. The visible cards include href values for the concept destinations, while meta.json controls the section’s page list. If those drift, readers may see a concept on the landing page that is missing from navigation, or a navigation item that is not introduced by the overview. The current source evidence shows a consistent set of four concepts in both places, which is the right pattern for a first-party documentation index.
Sources: apps/docs/content/docs/core-concepts/index.mdx, apps/docs/content/docs/core-concepts/meta.json
Next Steps
Start with the four concept pages in the order provided by the section metadata: Remote Caching, Package types, Internal Packages, and Package and Task Graphs. Then continue into repository-crafting material when you are ready to make structural decisions, or into task and configuration references when you are ready to encode those decisions in Turborepo configuration. The key outcome is not memorizing the overview page; it is being able to explain how your packages, shared code, task relationships, and caching strategy fit together before you optimize the workflow.
Sources: apps/docs/content/docs/core-concepts/meta.json