User-configurable package colors in turbo.json

[pastarita]

User-configurable package colors in turbo.json

Problem

Monorepos with 15+ packages get no visual signal from task prefix colors. The current 5-color palette (cyan, magenta, green, yellow, blue) cycles ~3 times across 18 packages, making colors noise rather than signal.

Teams that maintain domain-specific color conventions (design systems, microservice topologies, pillar architectures) can't leverage their existing visual vocabulary in turbo output.

Prior work

This builds on the chain of improvements to color handling:

• Discussion Give each package a separate color in the terminal #1877 identified the need for better package color differentiation
• Issue [turborepo] Logging colors are non-deterministic #2564 tracked non-deterministic color assignment
• PR feat: color no longer tied to task execution order #9023 (by @Shaharking, merged in v2.1) made colors deterministic by sorted task name

PR #9023 solved which package gets which color. The natural next step is letting users choose which color.

Proposal

A top-level packageColors map in turbo.json that feeds into the existing ColorSelector:

{
  "packageColors": {
    "@myorg/api": "#3B82F6",
    "@myorg/web": "#22C55E",
    "@myorg/shared": "#FFD700"
  }
}

• Packages not listed fall back to the existing 5-color round-robin (no behavioral change)
• Invalid values produce a warning and fall back to auto-assignment
• Colors rendered as nearest ANSI-256 for broad terminal compatibility, with 24-bit RGB where supported

Why packageColors and not per-task config

I'm aware that per-task UI configuration was discussed in #9167 and #9091, and that the concern is "there can only be one UI but many tasks." This proposal is deliberately scoped differently:

• It's a global map (package name to color), not a per-task UI setting
• It configures the ColorSelector's lookup table, not the UI mode
• Every task from a package inherits the same color, exactly like today's behavior

Scope

The implementation touches three files:

• crates/turborepo-ui/src/color_selector.rs — accept custom colors from config alongside the existing palette
• crates/turborepo-lib/src/turbo_json/ — parse the optional packageColors field
• crates/turborepo-lib/src/task_graph/visitor.rs — pre-populate custom colors before the graph walk

Questions for the team

1. Is the team open to a packageColors configuration surface in turbo.json?
2. Should this live at the top level of turbo.json or somewhere else in the schema?
3. Any preference on color format? (hex #RRGGBB, named ANSI colors, or both?)

Happy to submit a PR if there's interest. Would keep it tightly scoped to this one feature.

[pastarita]

Additionally, perhaps an extension worth flagging: packageColors could be the first field in a broader packageMeta surface.

In monorepos with nested scopes or hierarchical package structures (@myorg/api, @myorg/api-auth, @myorg/api-gateway), you'd want child packages to inherit a parent color and shift along a gradient — e.g., the @myorg/api family all lives in the blue range but each sub-package gets a distinct shade(perhaps configurably governed by depth and/or peer-hierarchiality).

A parametric color driver could handle this:

{
  "packageMeta": {
    "@myorg/api": {
      "color": "#3B82F6",
      "colorMode": "gradient"
    },
    "@myorg/web": {
      "color": "#22C55E"
    }
  }
}

Where colorMode: "gradient" tells the ColorSelector to derive sub-colors for any package matching the @myorg/api* prefix — shifting hue, lightness, or saturation parametrically so the family is visually cohesive but individually distinguishable.

This is/may be out of scope for an initial PR, but it suggests that packageColors might be better designed from the start as packageMeta with color as the first registered field — so the schema doesn't need a breaking change when label, icon, or colorMode are added later. Just a thought on future-proofing the surface.