skip to content

In a Dart pub workspace, what can a member's `pubspec_overrides.yaml` change, and how do you use it to resolve that member on its own?

level: seniorimportance: nice to knowfreq 12%

answer

  1. a file beside pubspec.yaml
  2. three keys, no more
  3. usually kept out of git
  4. an empty resolution: detaches
  5. check constraints as a consumer would

basics

~20 s

pubspec_overrides.yaml sits next to a pubspec.yaml and overrides only its dependency_overrides, workspace and resolution keys, usually without being committed. An empty resolution: in it detaches the member, so dart pub get there creates an independent resolution.

solid answer

~40 s

When a `pubspec_overrides.yaml` sits next to a `pubspec.yaml`, pub lets its attributes win over the pubspec's, but only for three keys: `dependency_overrides`, `workspace` and `resolution`. It exists so that temporary or script-generated overrides don't get committed; dart.dev says you usually keep it out of source control. In a workspace, every member may have one. The workspace trick is an empty `resolution:` entry: running `dart pub get` inside that member then creates an independent resolution with its own lockfile. Sibling members are then fetched from their hosted versions, not the local copies, which is how you check that a publishable package such as `api_client` really works with the constraints it declares. Delete the file and run `dart pub get` again; pub then removes the member's stray lockfile and the shared one takes over.

code

yaml · 3 lines
yaml
# packages/api_client/pubspec_overrides.yaml (not committed)
# An empty value resets `resolution: workspace` from pubspec.yaml.
resolution:

go deeper

for a junior

Recall that pubspec_overrides.yaml sits beside a pubspec.yaml, overrides a few keys locally, and usually isn't committed.

for a middle

Name the three overridable keys and explain how an empty resolution: entry makes dart pub get resolve one member independently.

for a senior

Use a detached resolution, optionally with dart pub downgrade, to validate publishable members as consumers see them, and keep overrides out of shared history.

for a principal

Make stand-alone constraint checks for published members part of the release process, since the workspace's local stand-ins hide exactly the failures consumers hit.

## What the file is `pubspec_overrides.yaml` is an optional file that sits **next to a `pubspec.yaml`**. When pub finds one, attributes in it **override** the same attributes in the pubspec. It was added in Dart 2.16 to make local overrides easier to keep out of version control, and it matters more in a pub workspace, where every member package may have its own. Only three keys can be overridden: | Key | Typical use in a workspace | |---|---| | `dependency_overrides` | point a dependency at a local fork or force a version while testing | | `workspace` | change the member list of a (possibly nested) workspace locally | | `resolution` | detach a member from the shared resolution | Everything else - `name`, `version`, `environment`, `dependencies`, `dev_dependencies` - still comes from `pubspec.yaml`. ## Why it usually stays out of git dart.dev's package-layout guide says you usually don't want to check this file in. The reasons: - it holds **temporary** changes - a fork path on one laptop, an experiment - that would break or confuse everyone else; - a script can generate it and delete it again without touching tracked files; - committing an override to `resolution` or `workspace` would silently change the repository's structure for every developer. A common practice is to add `pubspec_overrides.yaml` to `.gitignore`. ## Detaching a member Take a monorepo with an app, `apps/field_app`, and four local packages: `core`, `api_client`, `ui_kit` and `storage`. `api_client` is published to pub.dev and depends on `core: ^2.0.0`. Inside the workspace, `core` always resolves to the local copy, so tests there never see what a consumer sees. To resolve `api_client` alone: 1. Create `packages/api_client/pubspec_overrides.yaml` containing only `resolution:` with no value, which resets the setting. 2. Run `dart pub get` inside `packages/api_client`. pub now creates an **independent resolution** for it, with its own `pubspec.lock`, and fetches `core` from pub.dev like any hosted dependency. 3. Run the package's tests. Optionally run `dart pub downgrade` first, which picks the lowest versions the constraints allow, to check that the lower bounds are honest. 4. Delete the overrides file and run `dart pub get` from the workspace. Because pub removes stray `pubspec.lock` and `.dart_tool/package_config.json` files between the root and each member, the temporary lockfile disappears and the shared resolution takes over again. ## Why validate outside the workspace - Inside the workspace, **local members stand in for hosted ones**, whatever source is declared - a change in `core` that isn't published yet can make `api_client` pass locally and fail for users. - The shared resolution uses whatever third-party versions the **whole repository** agreed on; a consumer's app may pick different ones inside `api_client`'s ranges. - Lax lower bounds hide easily: nothing in a workspace ever resolves `api_client` with the oldest versions its pubspec claims to support. ## Overrides and the once-only rule Overrides in a member's `pubspec_overrides.yaml` still feed the single shared resolution while the member is attached. The workspace rule that **a package can be overridden only once** still applies, so the same package overridden in two members, whether in `pubspec.yaml` or in an overrides file, is a conflict. dart.dev recommends keeping committed overrides in the root `pubspec.yaml`. ## Overrides file versus overrides in pubspec.yaml Both places can hold `dependency_overrides`, but they serve different purposes: | | `dependency_overrides` in `pubspec.yaml` | `pubspec_overrides.yaml` | |---|---|---| | Usually committed | yes, so the whole team gets it | no, dart.dev advises keeping it out | | Keys it can change | `dependency_overrides` only | `dependency_overrides`, `workspace`, `resolution` | | Typical lifetime | until a migration lands | one experiment or one script run | | Visible in review | yes | no, which is the point for local experiments | A useful rule of thumb: if the whole team needs the override to build, it belongs in the root `pubspec.yaml` with a comment explaining why; if only you need it for an hour, it belongs in an overrides file that never leaves your machine. ## Summary - Same directory as the pubspec; overrides only `dependency_overrides`, `workspace` and `resolution`. - Usually not committed. - An empty `resolution:` detaches a member for a stand-alone `dart pub get`, the way to test a published member the way consumers resolve it.

  • Why not just delete `resolution: workspace` from `pubspec.yaml` for the experiment?
    It works, but it edits a tracked file that is easy to commit by accident, which would drop the member from the workspace for everyone. The overrides file keeps the change local and is the documented way to reset `resolution`.
  • What does `dart pub downgrade` add to the stand-alone check?
    It resolves each dependency to the lowest version its constraints allow. Running the tests after it shows whether the lower bounds a published package declares are real; if they fail, the bounds are too loose and should be raised before the next release.

saying these in an interview costs you the question

  • pubspec_overrides.yaml can override any pubspec key, including version and dependencies
  • pubspec_overrides.yaml is only allowed next to the workspace root pubspec
  • It should always be committed so that the whole team shares the overrides
  • Tests passing inside the workspace prove a member's constraints work for its consumers
  • Only editing pubspec.yaml can take a member out of the shared resolution