Feature request: nested configuration files (grandparents)

[PaulRBerg]

Introduction

I’m proposing support for recursive extends in biome.json. Right now, Biome only resolves one level, which forces us to duplicate configs and makes it harder to stay modular.

Use Case

We want a base Biome config and then layer more specific configs on top of it, like a UI config.

~/sablier/devkit/biome/base.jsonc

{
  "$schema": "https://biomejs.dev/schemas/latest/schema.json",
  "formatter": { "enabled": true, "lineWidth": 100 },
  "linter": { "enabled": true, "rules": { "recommended": true } }
}

~/sablier/devkit/biome/ui.jsonc

{
  "$schema": "https://biomejs.dev/schemas/latest/schema.json",
  "extends": ["./base.jsonc"],
  "linter": { "rules": { "a11y": { "recommended": true } } }
}

Consuming project (project/biome.json)

{
  "extends": ["@sablier/devkit/biome/ui"],
  "files": { "includes": ["src/**/*.ts"] }
}

The Problem

I'd expect project/biome.json to inherit both ui.jsonc and base.jsonc. But Biome stops after one level, so anything in base.jsonc gets ignored unless I manually copy it into ui.jsonc.

This leads to duplication and extra maintenance.

Proposed Solution

Make extends work recursively. When a config extends another, Biome should follow the chain all the way up and merge everything. The most specific config should always win.

Existing Issues

Related requests exist (#1867, #3950, #2257), but they’re marked “not planned.” Given how common recursive config hierarchies are in other tools, it feels worth revisiting.

[ematipico]

Given how common recursive config hierarchies are in other tools, it feels worth revisiting.

ESlint v10 was a big change because it removed the possibility of recursive configurations; instead, they went for a flattening strategy.

We don't want to make the same mistakes. Recursive configurations are difficult to debug.

[PaulRBerg]

I see .. maybe at least allow one level (grandparent)?

It would enable basic uses cases like the one mentioned in the OP.

I currently have to write tests to ensure that the base.jsonc and ui.jsonc files match.

[ematipico]

What's stopping users from asking for more?

Again, this is a rabbit hole and could impact negatively how quickly we can debug things.

Users can already fix this. Plus, it allows users to see all configs they are extending

[PaulRBerg]

Nothing. But a better question to ask would be "how many users will ask for grand-grandparent configs?"

Grandparent configs would address 80% of use cases. So only 20% of users would need more.

Users can already fix this

At the cost of bad UX and writing equivalence tests.

Allow users to see all configs they are extending

Not a problem in modern IDEs. CMD+click in VSCode makes it trivial to jump between files.

also, IIRC, biome rage provides the resolved config.

[PaulRBerg]

Another use case that is not possible because of this limitation:

Extending a third-party Biome preset like ultracite in a company-wide preset, which is then extended in the company's projects.

Because grandparents are not supported, we have to:

1. Extend from both ultracite and our company-wide presets (which are already messy, because again, grandparents are not supported).
2. Maintain multiple dependencies in package.json

[ematipico]

Yeah, I can see your point.

I'll need to think about it, because I don't want to ship this feature without a way for us and the users to know where a configuration is coming from.

For example, with the use case you provided, you wouldn't know which configuration enabled something (a rule, a formatted field, etc.). Clicks, editors, etc. don't count.

Without it, I don't think it's a feature we can ship to the users.

[PaulRBerg]

thank you, and yeah I can also understand it can be tricky to get the design right.

to begin with, maybe biome rage can be made to explain the source of each enabled rule - this would be useful even now when only a parent config file is allowed.

[christymcgrory]

I think the documentation here makes it more confusing because the Exporting a configuration from an NPM package is directly below the Monorepo section. It wasn't until the 5th or 6th time looking at that page that I noticed:

Files that you extend from cannot extend other files in turn.

Personally I would make this distinction more visible, as well as the limitation of only using one or the other.

We've also run into the same problems that @PaulRBerg is describing, and I think it's quite a common pattern for monorepo projects to essentially have a hybrid of the two options described in the Big Projects guide, where you have a common published package that is extended by a monorepo root, then each package extends that root level config in turn.

The only alternatives I know of are:

1. Extend the package directly from each workspace package and manage biome versions per package (since biome at the root does not seem to play ball with configs in subdirectories without the monorepo setup, unless I've missed something).

• One caveat of this is that vcs.useIgnoreFiles doesn't work as expected since the .gitignore is at the root level, and also does not seem to respect vcs.root as far as I can tell.
• I also noticed some inconsistency with the Github Action + the biome cli with this method, but I am not confident that it was configured correctly.

2. Do away with the NPM package and simply manage one big biome config at the root level (less keen on this one since we lose versioning, but the vcs settings above would mitigate it in theory).

While I agree that nested configs can become messy in general, maybe a good halfway point, at least where monorepos are concerned, would be:

• if a package biome.json specifies { extends: "//" }
• and that root level biome.json specifies { extends: "./some/package" }
• then the package inherits both the monorepo root + the package it extends.

Either that or some explicit opt in config:

{
  "extends": {
     "files": ["//"],
     "inheritNested": true,
     "inheritLevel": 2,
  }
}

Happy to spin up a draft PR if there's anything here you think would be beneficial!

[ematipico]

Personally I would make this distinction more visible, as well as the limitation of only using one or the other.

You're more than welcome to send a PR and make it more evident. That part has been there for a long time, and the features that Biome had aren't the ones it has now, so the perception of certain missing features changes with time.

---

Again, what concerns me isn't the feature per se, but finding a way to debug it. Even now, without this feature, you can have a list of 10 extended packages, and you don't know which one changed the default value of a certain setting (rule, action, formatting, etc.).

So before moving forward, we should do some internal work to make it debuggable, which requires some internal refactoring.

[ematipico]

Closing #11432