[RFC] Boundaries

[anthonyshew]

We’d like to introduce a Boundaries feature in Turborepo.

The JavaScript ecosystem has grown into having great support for monorepos, letting developers scale JavaScript and TypeScript repositories like never before. However, as a repository progresses to greater scales, it becomes important to enforce boundaries within the repository to maintain order and predictability in the codebase.

Problems we want to solve

Without clear boundaries in a monorepo, it’s too easy to use code from internal packages in undesirable ways:

• Because code is all on the same file system, you can easily ../../ out of the root of a package. This breaks out of the model of JavaScript monorepos, since code now depends on other code without respecting the package graph. This can result in unexpected caching behavior, since Turborepo can’t account for code outside of the package graph in hashing.
• You can use any package in any other package. This can create entanglement in the dependency graph, creating disorder and confusion that harms developer experience.
• You can easily install an application into another application. This is likely to create a litany of issues when it comes to building and deploying your applications.
• Packages can be used in contexts they aren’t meant for. For example, backend code can be authored much differently than frontend code, without concern for bundle sizes. This can cause the backend-minded package to bloat frontend bundles. At scale, this can be disastrous for web application performance.
• Domain concerns mean that you could have a set of packages that are only meant for certain domain contexts. For example, you may have an @repo/shared-marketing package that can accidentally be used in an application that is outside of the marketing domain.

Proposed Solution

The turbo boundaries command will:

• Exit with a 0 exit code to indicate a successful run when no Boundaries have been breached
• Exit with a 1 exit code to indicate failure when a Boundary has been breached, printing output to stderr to indicate where there are issues.

turbo boundaries

2 Boundary issues found:
- `@repo/be-utils` is used in `@repo/ui`, but is not
  listed in `dependencies` in `@repo/ui`'s package.json.
  Location: ./packages/ui/src/button.tsx - Line 2, Column 9

- The path `../../.eslint-config.js` leads outside of the package's directory.
  This can lead to caching issues.
  Location: ./packages/ui/.eslint-config.js - Line 1, Column 4

- `@repo/ui` denies packages with the tag `util` to be used. `@repo/utils` has this tag.
  Location: ./packages/ui/package.json - Line 32, Column 8

Additionally, any non-CI invocation of turbo run or turbo watch will include a synthetic "Boundaries checking" task once the Boundaries feature has been enabled. This ensures that we can notify you as soon as possible after writing code that breaches a Boundary.

Getting started with zero-configuration

Add boundaries: true to your root turbo.json to start using the recommended checks provided by Turborepo. (This is not required to use Boundary Tags.)

// ./turbo.json
{
  "boundaries": true
}

This will enforce our recommended set of Boundaries for your Workspace:

• You will no longer be able to path outside of a package’s directory. Assuming apps/web is a package’s directory, the code below would result in an error.

// apps/web/foo.ts
import {} from "../../../"

• Importing code from an internal package that is not installed in the package. Assuming that @repo/utils is not listed in apps/web/package.json#dependencies, the code below would result in an error. This helps with some package managers that allow dependencies to be available where they aren't installed.

import {} from "@repo/utils"

Once added, you may find existing issues that you’re not ready to address quite yet. See the Allowlisting existing code section for more on how to incrementally adopt Boundaries.

Incrementally adopting Boundary Tags

Additionally, you can create Tags to mark domains, concerns, contexts, and other useful sets that you want to make custom Boundaries for.

In a Package Configuration, add a boundaries key.

// ./packages/ui/turbo.json
{
  "extends": ["//"],
  "boundaries": {
    "tags": ["library", "ui", "frontend", "stable"]
    // Mutually exclusive. You may only use one of these.
    "allowDependencyOn": ["library", "frontend"],
    "denyDependencyOn": ["backend", "marketing", "alpha", "beta"],
    // Mutually exclusive. You may only use one of these.
    "allowDependencyFrom": ["library", "frontend"],
    "denyDependencyFrom": ["backend"]
  }
}

The schema for boundaries above represents:

• tags : The tags for the package. These will be used for comparisons against the Boundaries of other packages.
• allowDependencyOn: List of tags that internal dependencies of the package must include at least one of in its own tag list, including indirect dependencies. Any package that does not have any of these tags will be considered an error. Cannot be used with denyDependencyOn.
• denyDependencyOn: List of tags that internal dependencies of the package cannot include any of in its own tag list, including indirect dependencies. Any package with any of these tags will be considered an error. Cannot be used with allowDependencyOn.
• allowDependencyFrom: List of tags that internal dependents must include at least one of in their own tag list, including indirect dependencies. Any package that tries to use this package but is not tagged with any members of the allowDependencyFrom array will be considered an error. Cannot be used with denyDependencyOn.
• denyDependencyFrom: List of tags that internal dependents most not include any of in their own tag list, including indirect dependencies. Any package that tries to use this package that is tagged with any of the members of denyDependencyFrom will be considered an error. Connot be used with allowDependencyFrom.

Creating exceptions for existing code

Introducing Boundaries to a large codebase can be difficult when you want to enforce a new Boundary where there wasn’t one before, so we want to make sure that Boundaries are incrementally adoptable.

After creating a Boundary, you can quickly create an exception list for existing violations by adding an --exclude-errors flag.

turbo boundaries --exclude-errors
Allowlisted 38 errors.

This will create an allowlist file in packages that have violations. The exclusion list would look something like:

// packages/ui/turbo.json
{
  "extends": ["//"],
  "boundaries": {
    "exclusions": [
      {
        "type": "Path breakout",
        "file": "./packages/ui/src/button.tsx",
        "location": "@repo/ui-@repo/utils",
        "reason": "The path `../../../` terminates outside of the package."
      },
      {
        "type": "Missing dependency",
        "file": "./packages/ui/src/card.tsx",
        "location": "@repo/ui-@repo/utils",
        "reason": "`@repo/utils` is used but is cannot be found in package.json"
      },
      {
        "type": "Tag violation",
        "file": "./packages/ui/package.json",
        "location": "@repo/ui-@repo/utils",
        "reason": "`@repo/ui` denies packages with the tag `util` to be used. `@repo/utils` has this tag."
      }
    ]
  }
}

Exclusions will also be inspected whenever Boundaries checking occurs (turbo boundaries, turbo run, turbo watch) and errors will be thrown for exclusions that aren’t being used. turbo boundaries --exclude-errors will automatically fix the erroneous exclusions.

Open questions

• We anticipate that the community will want this feature most for Multi-package Workspaces. However, it’s possible this feature could make sense in single-package Workspaces at a module level, as well. We would love to hear use cases where you believe Boundaries could help your single-package Workspace.
• Automatically running the Boundaries check seems like it should not happen in CI, since you'd get the same failure many times. It seems we should teach developers to run turbo boundaries as a CI check, and allow all other turbo run invocations to proceed without checking Boundaries so that developers can get feedback from their other tasks sooner.

[kasper573]

This is really exciting! I've been using dependency-cruiser and eslint-plugin-monorepo-cop to painstakingly emulate something like this. Having something like this directly in turbo sounds awesome. Nice work!

i agree that boundary checks should be opt in for the ci.

[reconsumeralization]

I want in.

[franky47]

I could see the value of this kind of linting step, and it being integrated with the rest of package relationship configs (I had missed the fact we could have multiple turbo.json, which is nice too) makes sense.

I'd be interested to give this a try in nuqs, particularly to test the --exclude-errors flag, which seems like a convenient way on its own to see if there are any undesirable cross-links between packages. I've recently split my e2e test environments into multiple frameworks, and making sure there isn't too much wild cross-pollination between them would be nice.

I had been using a linter config in some client projects for this purpose, can't recall which one though.

[reconsumeralization]

I really like the secret auto documentation the cursors using. I hear told, the pnpm isn't having dependencies issues with it's peer anymore. 😚🥰😍😂😘😚😁😁😁

[drwpow]

Devil’s advocate: why not enforce the boundaries by default? Make the “unsafe” behavior opt-in for users that are already using this, and make them aware of the drawbacks. As someone who’s dealt with this issue, there are no downsides to forcing that all packages either import local code, or import via a valid npm specifier (to all the points stated in the RFC).

Vite has enforced this since v2.7 (and by extension, Vitest), so a lot of people are already used to build systems that require this.

This may be a “breaking” or annoying change, but on the flipside, enabling by default could just improve the perception that people have of Turbopack’s quality—it guides you into safer monorepo strategies that are easier to optimize and scale. Or people will just get annoyed; hard to say 😅

[anthonyshew]

While it does sound attractive to make the recommended Boundaries a default out of the box, this feature might be unrealistic for us to ship as the default right away. Our goal is that folks should be able to get started with Turborepo with as little friction as possible, especially in huge repos (where Turborepo can have tremendous impact).

The problem ends up being that large repos can have the scariest, darkest corners. I've seen...things. 😄 That ends up meaning a feature like this being on by default is a barrier to entry and we would have to balance that against the cache safety reasoning that you've adeptly mentioned. The tradeoff for raising the quality bar of the average Turborepo would be that difficulty of adoption increases.

Right now, that balance is an unknown. This feature is only an idea, and we think we can reasonably expect how folks are going to use the feature - but we can only make an educated guess based on our experiences. Instead of going for making this the default straight out of the box, we can incrementally ship this such that folks who want it can turn it on at their leisure.

One way to think about this is in the cost of "getting it wrong". There are two scenarios:

1. We be cautious, and incrementally ship the recommended Boundaries through an opt-in flag. Folks can incrementally adopt Boundaries (or not) when we ship the feature for the first time. It doesn't require a major release to get the feature into your hands. After some time, we may find that this really should be the default and ship a major that includes the default flipping. Note that that is one, optional major release.
2. We be aggressive and ship the recommended boundaries on Day One. That makes one major release. It's possible that we find out that our instincts weren't correct that this should be enabled by default and it requires another major version of Turborepo to undo our mistake. That means, at a minimum, one forced major, plus a possibility for a second.

Hopefully that paints a picture of why I'm expecting we would eventually, slowly release this feature (if this RFC makes it to implementing at all, of course). I do agree with your point that cache safety is vital, and I wish it were as easy as making sure every repo gets it right at all times, but, today, I do believe we'll need to be thoughtful about how we approach the release of this feature.