turbo 2.11.4 → 2.11.5-canary.2

package/docs/README.md

@@ -0,0 +1,39 @@
+# Turborepo documentation
+
+These docs match the installed `turbo` package version. Start here, choose the smallest relevant page, and read it before changing Turborepo configuration or commands.
+
+The files are the same MDX sources used by turborepo.dev. Site-absolute links such as `/docs/reference/run` map to paths in this directory, such as `reference/run.mdx`.
+
+## Find the page for your task
+
+| To do this                                        | Read this                                                                                                               |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Add Turborepo to a repository                     | [Add to an existing repository](./getting-started/add-to-existing-repository.mdx)                                       |
+| Understand packages and task relationships        | [Package and task graph](./core-concepts/package-and-task-graph.mdx)                                                    |
+| Configure tasks, dependencies, inputs, or outputs | [Configuring tasks](./crafting-your-repository/configuring-tasks.mdx)                                                   |
+| Look up `turbo.json` fields                       | [Configuration reference](./reference/configuration.mdx)                                                                |
+| Run or filter tasks                               | [Running tasks](./crafting-your-repository/running-tasks.mdx) and [`turbo run` reference](./reference/run.mdx)          |
+| Configure caching or debug cache misses           | [Caching](./crafting-your-repository/caching.mdx)                                                                       |
+| Set up Remote Cache                               | [Remote Caching](./core-concepts/remote-caching.mdx)                                                                    |
+| Configure environment variables                   | [Using environment variables](./crafting-your-repository/using-environment-variables.mdx)                               |
+| Structure a repository                            | [Structuring a repository](./crafting-your-repository/structuring-a-repository.mdx)                                     |
+| Create an internal package                        | [Creating an internal package](./crafting-your-repository/creating-an-internal-package.mdx)                             |
+| Manage workspace dependencies                     | [Managing dependencies](./crafting-your-repository/managing-dependencies.mdx)                                           |
+| Configure package-specific tasks                  | [Package Configurations](./reference/package-configurations.mdx)                                                        |
+| Set up CI                                         | [Constructing CI](./crafting-your-repository/constructing-ci.mdx) and [CI vendor guides](./guides/ci-vendors/index.mdx) |
+| Configure watch mode                              | [`turbo watch` reference](./reference/watch.mdx)                                                                        |
+| Enforce package boundaries                        | [Boundaries](./reference/boundaries.mdx)                                                                                |
+| Look up a command or option                       | [Reference](./reference/index.mdx) and [options overview](./reference/options-overview.mdx)                             |
+| Upgrade Turborepo                                 | [Upgrading](./crafting-your-repository/upgrading.mdx)                                                                   |
+
+## Broader reading order
+
+For a broader introduction, read:
+
+1. [Introduction](./index.mdx)
+2. [Core concepts](./core-concepts/index.mdx)
+3. [Crafting your repository](./crafting-your-repository/index.mdx)
+4. [Guides](./guides/index.mdx)
+5. [Reference](./reference/index.mdx)
+
+Prefer these installed docs over the live website when behavior may vary by version.

package/docs/acknowledgments.mdx

@@ -0,0 +1,48 @@
+---
+title: Acknowledgements
+description: Thank you to all these developers, build systems, and monorepo tools for their support and assistance.
+product: turborepo
+type: overview
+summary: Credits and thanks to the developers, build systems, and monorepo tools that inspired Turborepo.
+related:
+  - /docs/community
+---
+
+Turborepo was originally created by [Jared Palmer](https://x.com/jaredpalmer) as a closed-source enterprise software offering. In late 2021, [Vercel acquired Turborepo](https://vercel.com/blog/vercel-acquires-turborepo) and open sourced the codebase.
+
+Today, Turborepo has a dedicated full-time team working on it as well as a growing list of [open source contributors](https://github.com/vercel/turborepo/graphs/contributors).
+
+## Inspiration and Prior Art
+
+At [Vercel](https://vercel.com/), we believe deeply in the open source movement and in the power of open collaboration. To that end, it's important to provide meaningful attribution to the projects and people that inspire(d) us and our work.
+
+We'd like to make a special shoutout to other build systems, monorepo tools, and prior art:
+
+- Bazel - https://bazel.build
+- Buck - https://buck.build
+- Please - https://please.build
+- Pants - https://www.pantsbuild.org
+- Scoot - https://github.com/twitter/scoot
+- TSDX - https://tsdx.io
+- Lerna - https://lerna.js.org
+- Lage - https://microsoft.github.io/lage
+- Backfill - https://github.com/microsoft/backfill
+- Bolt - https://github.com/boltpkg/bolt
+- Rush - https://rushjs.io
+- Preconstruct - https://preconstruct.tools
+- Nx - https://nx.dev
+- Yarn - https://yarnpkg.com
+- npm - https://www.npmjs.com
+- pnpm - https://pnpm.js.org
+
+Throughout the documentation, wherever applicable, we also provide inline callouts and links to the projects and people that have inspired us.
+
+## Additional Thanks
+
+Additionally, we're grateful to:
+
+- [Rick Button](https://x.com/rickbutton) for donating the `turbo` package name on npm
+- [Iheanyi Ekechukwu](https://x.com/kwuchu) for helping Jared pick up Golang during the Pandemic!
+- [Kenneth Chau](https://x.com/kenneth_chau) for Lage's Scope and Pipeline API and docs
+- [Miguel Oller](https://x.com/ollermi) and [MakeSwift.com](https://www.makeswift.com/) for piloting Turborepo
+- [Eric Koslow](https://x.com/ekosz1), [Jack Hanford](https://x.com/jackhanford), and [Lattice.com](https://lattice.com/) for piloting Turborepo

package/docs/community.mdx

@@ -0,0 +1,63 @@
+---
+title: Community
+description: Learn about the Turborepo community.
+product: turborepo
+type: overview
+summary: Find ways to contribute, ask questions, and connect with other Turborepo developers.
+related:
+  - /docs/acknowledgments
+---
+
+Turborepo has a large and active community of developers across the world. Here's how you can get involved.
+
+## Contributing
+
+- [Documentation](https://github.com/vercel/turborepo/tree/main/docs): Suggest improvements or even write new sections to help build understanding of how to use Turborepo.
+- [Examples](https://github.com/vercel/turborepo/tree/main/examples): Help developers integrate Turborepo with other tools and services by improving an example.
+- [Code](https://github.com/vercel/turborepo/blob/main/CONTRIBUTING.md): Learn more about the underlying architecture, contribute bug fixes, and suggest new features.
+
+## Discussions
+
+If you have a question about Turborepo or want to help others, join the conversation:
+
+- [GitHub Discussions](https://github.com/vercel/turborepo/discussions)
+- [Vercel Community](https://community.vercel.com/tag/turborepo)
+
+## Acknowledgements
+
+Turborepo was originally created by [Jared Palmer](https://x.com/jaredpalmer) as a closed-source enterprise software offering. In late 2021, [Vercel acquired Turborepo](https://vercel.com/blog/vercel-acquires-turborepo) and open sourced the codebase.
+
+Today, Turborepo has dedicated full-time team working on it as well as a growing list of [open source contributors](https://github.com/vercel/turborepo/graphs/contributors).
+
+### Inspiration / Prior Art
+
+At [Vercel](https://vercel.com/), we believe deeply in the open source movement and in the power of open collaboration. To that end, it's important to provide meaningful attribution to the projects and people that inspire(d) us and our work.
+
+We'd like to make a special shoutout to other build systems, monorepo tools, and prior art:
+
+- Bazel - https://bazel.build
+- Buck - https://buck.build
+- Please - https://please.build
+- Pants - https://www.pantsbuild.org
+- Scoot - https://github.com/twitter/scoot
+- TSDX - https://tsdx.io
+- Lerna - https://lerna.js.org
+- Lage - https://microsoft.github.io/lage
+- Backfill - https://github.com/microsoft/backfill
+- Bolt - https://github.com/boltpkg/bolt
+- Rush - https://rushjs.io
+- Preconstruct - https://preconstruct.tools
+- Nx - https://nx.dev
+- Yarn - https://yarnpkg.com
+- npm - https://www.npmjs.com
+- pnpm - https://pnpm.js.org
+
+### Additional Thanks
+
+Additionally, we're grateful to:
+
+- [Rick Button](https://x.com/rickbutton) for donating the `turbo` package name on npm
+- [Iheanyi Ekechukwu](https://x.com/kwuchu) for helping Jared pick up Golang during the Pandemic!
+- [Kenneth Chau](https://x.com/kenneth_chau) for Lage's Scope and Pipeline API and docs
+- [Miguel Oller](https://mobile.x.com/ollermi) and [MakeSwift.com](https://www.makeswift.com/) for piloting Turborepo
+- [Eric Koslow](https://x.com/ekosz1), [Jack Hanford](https://x.com/jackhanford), and [Lattice.com](https://lattice.com/) for piloting Turborepo

package/docs/core-concepts/index.mdx

@@ -0,0 +1,41 @@
+---
+title: Core concepts
+description: Learn about the core concepts behind Turborepo.
+product: turborepo
+type: overview
+summary: Explore the foundational concepts that power Turborepo's monorepo tooling.
+related:
+  - /docs/core-concepts/remote-caching
+  - /docs/core-concepts/package-types
+  - /docs/core-concepts/internal-packages
+  - /docs/core-concepts/package-and-task-graph
+---
+
+Learn more about the core concepts of Turborepo:
+
+<Cards>
+<Card
+title="Remote Caching"
+href="/docs/core-concepts/remote-caching"
+description="Save time by never doing the same work twice"
+/>
+
+<Card
+  title="Package types"
+  href="/docs/core-concepts/package-types"
+  description="Application and Library Packages"
+/>
+
+<Card
+  title="Internal Packages"
+  href="/docs/core-concepts/internal-packages"
+  description="Easily share code inside your repository"
+/>
+
+<Card
+  title="Package and Task Graphs"
+  href="/docs/core-concepts/package-and-task-graph"
+  description="How Turborepo relates your tasks to each other"
+/>
+
+</Cards>

package/docs/core-concepts/internal-packages.mdx

@@ -0,0 +1,177 @@
+---
+title: Internal Packages
+description: Learn how to build Internal Packages in your monorepo.
+product: turborepo
+type: conceptual
+summary: Understand how internal packages work and their compilation strategies for sharing code across your monorepo.
+prerequisites:
+  - /docs/core-concepts/package-types
+related:
+  - /docs/crafting-your-repository/creating-an-internal-package
+  - /docs/core-concepts/package-and-task-graph
+  - /docs/guides/publishing-libraries
+---
+
+Internal Packages are libraries whose source code is inside your Workspace. You can quickly make Internal Packages to share code within your monorepo and choose to [publish them to the npm registry](/docs/guides/publishing-libraries) if you need to later.
+
+Internal Packages are used in your repository by installing them in `package.json` similar to an external package coming from the npm registry. However, instead of marking a version to install, you can reference the package using your package manager's workspace installation syntax:
+
+<PackageManagerTabs>
+
+<Tab value="pnpm">
+```json title="./apps/web/package.json"
+{
+  "dependencies": {
+    "@repo/ui": "workspace:*" // [!code highlight]
+  }
+}
+```
+</Tab>
+
+<Tab value="yarn">
+```json title="./apps/web/package.json"
+{
+  "dependencies": {
+    "@repo/ui": "*" // [!code highlight]
+  }
+}
+```
+</Tab>
+
+<Tab value="npm">
+```json title="./apps/web/package.json"
+{
+  "dependencies": {
+    "@repo/ui": "*" // [!code highlight]
+  }
+}
+```
+</Tab>
+
+<Tab value="bun">
+```json title="./apps/web/package.json"
+{
+  "dependencies": {
+    "@repo/ui": "workspace:*" // [!code highlight]
+  }
+}
+```
+</Tab>
+
+<Tab value="nub">
+```json title="./apps/web/package.json"
+{
+  "dependencies": {
+    "@repo/ui": "workspace:*" // [!code highlight]
+  }
+}
+```
+</Tab>
+
+<Tab value="aube">
+```json title="./apps/web/package.json"
+{
+  "dependencies": {
+    "@repo/ui": "workspace:*" // [!code highlight]
+  }
+}
+```
+</Tab>
+
+</PackageManagerTabs>
+
+In the [Creating an Internal Package guide](/docs/crafting-your-repository/creating-an-internal-package), you can build an Internal Package from the beginning using [the Compiled Package strategy](#compiled-packages). On this page, we'll describe other strategies for creating Internal Packages and their tradeoffs, including [publishing the package to the npm registry](#publishable-packages) to create an External Package.
+
+You can then import the package into your code like you're used to doing with an external package:
+
+```tsx title="./apps/web/app/page.tsx"
+import { Button } from "@repo/ui"; // [!code highlight]
+
+export default function Page() {
+  return <Button>Submit</Button>;
+}
+```
+
+## Compilation Strategies
+
+Depending on what you need from your library, you can choose one of three compilation strategies:
+
+- [**Just-in-Time Packages**](#just-in-time-packages): Create minimal configuration for your package by allowing application bundlers to compile the package as it uses it.
+- [**Compiled Packages**](#compiled-packages): With a moderate amount of configuration, compile your package using a build tool like `tsc` or a bundler.
+- [**Publishable Packages**](#publishable-packages): Compile and prepare a package to publish to the npm registry. This approach requires the most configuration.
+
+### Just-in-Time Packages
+
+A Just-in-Time package is compiled by the application that uses it. This means you can use your TypeScript (or uncompiled JavaScript) files directly, requiring much less configuration than the other strategies on this page.
+
+This strategy is most useful when:
+
+- Your applications are built using a modern bundler like Turbopack, webpack, or Vite.
+- You want to avoid configuration and setup steps.
+- You're satisfied with your applications' build times, even when you can't hit cache for the package.
+
+A `package.json` for a Just-in-Time package may look like this one:
+
+```json title="./packages/ui/package.json"
+{
+  "name": "@repo/ui",
+  "exports": {
+    "./button": "./src/button.tsx", // [!code highlight]
+    "./card": "./src/card.tsx" // [!code highlight]
+  },
+  "scripts": {
+    "lint": "eslint . --max-warnings 0", // [!code highlight]
+    "check-types": "tsc --noEmit" // [!code highlight]
+  }
+}
+```
+
+There are a few important things to notice in this `package.json`:
+
+- **Directly exporting TypeScript**: The `exports` field marks the entrypoints for the package and, in this case, you're **referencing TypeScript files directly**. This is possible because the bundler for the application will compile the code as it uses it in its build process.
+- **No `build` script**: Because this package is exporting TypeScript, it doesn't need a build step for transpiling the package. This means you don't have to configure a build tool in this package to make it work in your Workspace.
+
+#### Limitations and tradeoffs
+
+- **Only applicable when consumers do transpiling**: This strategy can only be used when the package is going to be used in tooling that uses a bundler or natively understands TypeScript. The consumer's bundler is responsible for transpiling the TypeScript packages to JavaScript. If your builds or other usages of the package are not able to consume TypeScript, you will need to move to the [Compiled Packages](#compiled-packages) strategy.
+- **No TypeScript `paths`**: A library that is being transpiled by its consumer cannot use the `compilerOptions.paths` configuration because TypeScript assumes that source code is being transpiled in the package where it is written. If you're using TypeScript 5.4 or later, we recommend [using Node.js subpath imports](https://devblogs.microsoft.com/typescript/announcing-typescript-5-4/#auto-import-support-for-subpath-imports). To learn how, visit [our TypeScript page](/docs/guides/tools/typescript#use-nodejs-subpath-imports-instead-of-typescript-compiler-paths).
+- **Turborepo cannot cache a build for a Just-in-Time Package**: Because the package doesn't have its own `build` step, it can't be cached by Turborepo. This tradeoff may make sense for you if you want to keep configuration to a minimum and are okay with the build times for your applications.
+- **Errors in internal dependencies will be reported**: When directly exporting TypeScript, type-checking in a dependent package will fail if code in an internal dependency has TypeScript errors. You may find this confusing or problematic in some situations.
+
+### Compiled Packages
+
+A Compiled Package is a package that handles its own compilation using a build tool, like [`tsc` (the TypeScript compiler)](https://www.typescriptlang.org/docs/handbook/compiler-options.html#handbook-content).
+
+```json title="./packages/ui/package.json"
+{
+  "name": "@repo/ui",
+  "exports": {
+    "./button": {
+      "types": "./src/button.tsx", // [!code highlight]
+      "default": "./dist/button.js" // [!code highlight]
+    },
+    "./card": {
+      "types": "./src/card.tsx", // [!code highlight]
+      "default": "./dist/card.js" // [!code highlight]
+    }
+  },
+  "scripts": {
+    "build": "tsc" // [!code highlight]
+  }
+}
+```
+
+Compiling your library produces compiled JavaScript outputs into a directory (`dist`, `build`, etc.) that you will use for the entrypoints for your package. The build outputs will be cached by Turborepo once they're added to the [`outputs` key of the task](/docs/reference/configuration#outputs), allowing you to have faster build times.
+
+#### Limitations and tradeoffs
+
+- **Using the TypeScript compiler**: The majority of Compiled Packages should use `tsc`. Since the package is highly likely to be consumed by an application that is using a bundler, the application's bundler will prepare the library package for distribution in the application's final bundles, handling polyfilling, downleveling, and other concerns. A bundler should only be used if you have a specific use case that requires it, like bundling static assets into your package's outputs.
+- **More configuration**: Compiled Packages require deeper knowledge and configuration to create build outputs. There are [many configurations for the TypeScript compiler](https://www.typescriptlang.org/docs/handbook/compiler-options.html#compiler-options) that can be difficult to manage and understand, and further configuration to optimize for bundlers, like [the `sideEffects` key in `package.json`](https://webpack.js.org/guides/tree-shaking/#mark-the-file-as-side-effect-free). You can find some of our recommendations in [our dedicated TypeScript guide](/docs/guides/tools/typescript).
+
+### Publishable packages
+
+Publishing a package to the npm registry comes with the most strict requirements of the packaging strategies on this page. Because you don't know anything about how your package will be used by consumers who download the package from the registry, you may find it difficult due to the numerous configurations required for a robust package.
+
+Additionally, the process of publishing a package to the npm registry requires specialized knowledge and tooling. We recommend [`changesets`](https://github.com/changesets/changesets) for managing versioning, changelogs, and the publishing process.
+
+For a detailed guide, visit [our Publishing packages guide](/docs/guides/publishing-libraries).

package/docs/core-concepts/meta.json

@@ -0,0 +1,8 @@
+{
+  "pages": [
+    "remote-caching",
+    "package-types",
+    "internal-packages",
+    "package-and-task-graph"
+  ]
+}

package/docs/core-concepts/package-and-task-graph.mdx

@@ -0,0 +1,127 @@
+---
+title: Package and Task Graphs
+description: Turborepo builds a Task Graph based on your configuration and repository structure.
+product: turborepo
+type: conceptual
+summary: Learn how Turborepo uses directed acyclic graphs to model package dependencies and task relationships.
+prerequisites:
+  - /docs/core-concepts/internal-packages
+related:
+  - /docs/crafting-your-repository/configuring-tasks
+  - /docs/crafting-your-repository/running-tasks
+---
+
+## Package Graph
+
+The Package Graph is the structure of your monorepo created by your package manager. When you install [Internal Packages](/docs/core-concepts/internal-packages) into each other, Turborepo will automatically identify those dependency relationships to build a foundational understanding of your Workspace.
+
+For a deeper explanation of how to set up your Workspace, [visit our Structuring a repository page](/docs/crafting-your-repository/structuring-a-repository#anatomy-of-a-workspace). This sets the groundwork for the Task Graph, where you'll define how **tasks** relate to each other.
+
+## Task Graph
+
+In `turbo.json`, you express how tasks relate to each other. You can think of these relationships as
+dependencies between tasks, but we have a more formal name for them: the Task Graph.
+
+<Callout type="info">
+  You can generate a visualization of the task graph for your tasks using [the
+  `--graph` flag](/docs/reference/run#--graph-file-type).
+</Callout>
+
+Turborepo uses a data structure called a [directed acyclic graph (DAG)](https://en.wikipedia.org/wiki/Directed_acyclic_graph) to
+understand your repository and its tasks. A graph is made up of "nodes" and
+"edges". In the Task Graph, the nodes are tasks and the edges are the
+dependencies between tasks. A _directed_ graph indicates that the edges
+connecting each node have a direction, so if Task A points to Task B, we can say
+that Task A depends on Task B. The direction of the edge depends on which task
+depends on which.
+
+For example, let's say you have a monorepo with an application in `./apps/web` that
+depends on two packages: `@repo/ui` and `@repo/utils`:
+
+<Files>
+  <Folder name="apps" defaultOpen>
+    <Folder name="web" />
+  </Folder>
+  <Folder name="packages" defaultOpen>
+    <Folder name="ui" />
+    <Folder name="utils" />
+  </Folder>
+</Files>
+
+You also have a `build` task that depends on `^build`:
+
+```json title="./turbo.json"
+{
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"]
+    }
+  }
+}
+```
+
+Turborepo will build a task graph like this:
+
+![Task graph visualization. The diagram has one node at the top named "apps/web" with two lines that connect to other nodes, "packages/ui" and "packages/utils" respectively.](/images/docs/simple-task-graph.png)
+
+### Transit Nodes
+
+A challenge when building a Task Graph is handling nested dependencies. For
+example, let's say your monorepo has a `docs` app that depends on the `ui`
+package, which depends on the `core` package:
+
+<Files>
+  <Folder name="apps" defaultOpen>
+    <Folder name="docs" />
+  </Folder>
+  <Folder name="packages" defaultOpen>
+    <Folder name="ui" />
+    <Folder name="core" />
+  </Folder>
+</Files>
+
+Let's assume the `docs` app and the `core` package each have a `build` task, but
+the `ui` package does not. You also have a `turbo.json` that configures the
+`build` task the same way as above with `"dependsOn": ["^build"]`. When you run
+`turbo run build`, what would you expect to happen?
+
+Turborepo will build this Task Graph:
+
+![A Task Graph visualization with a Transit Node. The diagram has one node at the top named "apps/doc" with a line that connects to a "packages/ui" node. This node does not have a "build" task. The "packages/ui" node has another line to a "packages/core" node that does have a "build" task.](/images/docs/transitive-nodes.png)
+
+You can think of this graph in a series of steps:
+
+- The `docs` app only depends on `ui`.
+- The `ui` package does **not** have a build script.
+- The `ui` package's _dependencies_ have a `build` script, so the task graph knows to include those.
+
+Turborepo calls the `ui` package a Transit Node in this scenario, because it
+doesn't have its own `build` script. Since it doesn't have a `build` script,
+Turborepo won't execute anything for it, but it's still part of the graph for
+the purpose of including its own dependencies.
+
+#### Transit Nodes as entry points
+
+What if the `docs/` package didn't implement the `build` task? What would
+you expect to happen in this case? Should the `ui` and `core` packages still
+execute their build tasks? Should _anything_ happen here?
+
+Turborepo's mental model is that all nodes in the Task Graph are the same. In other words,
+Transit Nodes are included in the graph regardless of where they appear in the graph.
+This model can have unexpected consequences. For example, let's say you've configured
+your `build` task to depend on `^test`:
+
+```json title="./turbo.json"
+{
+  "tasks": {
+    "build": {
+      "dependsOn": ["^test"]
+    }
+  }
+}
+```
+
+Let's say your monorepo has many apps and many packages. All packages have
+`test` tasks, but only one app has a `build` task. Turborepo's mental model
+says that when you run `turbo run build`, even if an app doesn't implement `build`
+the `test` task of all packages that are dependencies will show up in the graph.

package/docs/core-concepts/package-types.mdx

@@ -0,0 +1,32 @@
+---
+title: Package types
+description: Learn about the different types of packages in a workspace.
+product: turborepo
+type: conceptual
+summary: Understand the difference between Application Packages and Library Packages in a workspace.
+related:
+  - /docs/core-concepts/internal-packages
+  - /docs/core-concepts/package-and-task-graph
+  - /docs/crafting-your-repository/structuring-a-repository
+---
+
+In Turborepo, we talk about two types of packages:
+
+- [Application Packages](#application-packages)
+- [Library Packages](#library-packages)
+
+## Application Packages
+
+An Application Package is a package in your workspace that will be deployed from your workspace. Examples of Application Packages are Next.js, Svelte, Vite, or CLI applications that are commonly found in the `./apps` directory.
+
+It's best practice that your Application Packages are the "end" of your [Package Graph](/docs/core-concepts/package-and-task-graph#package-graph), not being installed into other packages of your repository. Your CI/CD pipelines will most often finalize at these nodes of your Package and Task Graphs.
+
+### Installing an application package into another package
+
+In rare cases, you may need to install an Application Package into another package. This should be the exception. If you find you are doing this often, you may want to rethink your package structure.
+
+An example of an exception for this rule is installing your Application Package into a package that handles end-to-end testing. Once installed, you can depend on the Application Package in your end-to-end testing package so it is aware of re-deploys of the application.
+
+## Library Packages
+
+Library Packages contain code that you intend to share around your workspace. They aren't independently deployable. Instead, they support the Application Packages to create the final deployables from your repository. You might also refer to these packages as [Internal Packages](/docs/core-concepts/internal-packages), which have their own sub-types.