Skip to content

docs: clarify plugin path resolution for extended configs #4012

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
soconnor-seeq wants to merge 1 commit into
base: next
Choose a base branch
from
+23 −2
Open

docs: clarify plugin path resolution for extended configs #4012

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions src/content/docs/guides/big-projects.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,6 +179,9 @@ which the `biome.json`/`biome.jsonc` file resides. When using the `extends`
field, this means that paths in a shared configuration are interpreted from the
location of the configuration that is extending it, and not from the folder
of the file being extended.
There is one exception: `plugins` entries that start with `./` or `../` are
resolved relative to the configuration file where they are declared, even if
that file is pulled in via `extends`.

For example, let's assume a project that contains two directories `backend/` and
`frontend/`, each having their own `biome.json` that both extend a `common.json`
Expand Down
7 changes: 5 additions & 2 deletions src/content/docs/guides/configure-biome.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -161,8 +161,11 @@ You can explicitly list the files to be processed using
`src/**/*.js`. Negated patterns starting with `!` can be used to exclude files.

Paths and globs inside Biome's configuration file are resolved relative to the
folder the configuration file is in. An exception to this is when a
configuration file is [extended](/reference/configuration/#extends) by another.
folder the configuration file is in. When a configuration file is
[extended](/reference/configuration/#extends), paths inside the extended file
resolve relative to the extending config, except `plugins` entries that start
with `./` or `../`, which resolve relative to the config where they are
declared.

`files.includes` applies to all of Biome's tools, meaning the files specified
here are processed by the linter, the formatter and the assist, unless specified
Expand Down
11 changes: 11 additions & 0 deletions src/content/docs/linter/plugins.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,17 @@ the following configuration:
}
```

## Plugin paths

Plugin entries support a few path styles:

- Paths starting with `./` or `../` are treated as relative paths and are
resolved from the configuration file where they are declared (even if that
configuration file is referenced via `extends`).
- Scoped package specifiers (starting with `@`) are resolved via
`package.json` resolution (for example, from `node_modules` or workspaces).
- Other strings are treated as paths relative to the entry configuration file.
Comment on lines +39 to +41
Copy link
Contributor

@coderabbitai coderabbitai bot Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Clarify "entry configuration file" in the third bullet.

"Entry configuration file" is not a defined term in the Biome docs, and in the context of extends it's genuinely ambiguous — a reader could interpret it as either the declaring file (same as bullet 1) or the top-level extending config. Since the whole point of this section is to explain the extends behaviour, it's worth being explicit.

✏️ Suggested rewording 
-- Other strings are treated as paths relative to the entry configuration file.
+- Other strings (e.g. bare package names) are resolved relative to the
+  top-level configuration file that Biome loaded — i.e. the extending config,
+  not the file where the entry is declared.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- Scoped package specifiers (starting with `@`) are resolved via
`package.json` resolution (for example, from `node_modules` or workspaces).
- Other strings are treated as paths relative to the entry configuration file.
- Scoped package specifiers (starting with `@`) are resolved via
`package.json` resolution (for example, from `node_modules` or workspaces).
- Other strings (e.g. bare package names) are resolved relative to the
top-level configuration file that Biome loaded — i.e. the extending config,
not the file where the entry is declared.
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@src/content/docs/linter/plugins.mdx` around lines 39 - 41, The phrase "entry
configuration file" is ambiguous in the third bullet describing extends
resolution; update that bullet to explicitly say it means "the configuration
file that contains the extends property (i.e., the file doing the
extending/declaring)", not the top-level extended config. Concretely, change the
bullet text that currently reads "Other strings are treated as paths relative to
the entry configuration file" to something like "Other strings are treated as
paths relative to the configuration file that declares the extends value (the
file doing the extending)", and ensure this clarification sits alongside the
existing mention of `extends`/scoped package specifiers to remove ambiguity.

Copy link
Author

@soconnor-seeq soconnor-seeq Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I kinda agree with coderabbitai here but I don't really like how it's suggestion is phrased. I could use some help figuring out how to phrase this new behaviour of plugins using the same language that is used in the Biome docs.

Copy link
Author

@soconnor-seeq soconnor-seeq Feb 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After thinking about this for a while I think this wording is better:

Suggested change
- Scoped package specifiers (starting with `@`) are resolved via
`package.json` resolution (for example, from `node_modules` or workspaces).
- Other strings are treated as paths relative to the entry configuration file.
- Scoped package specifiers (starting with `@`) are resolved via
`package.json` resolution (for example, from `node_modules` or workspaces).
- Other strings (e.g. bare package names) are are unchanged and will continue to be resolved relative to the
top-level configuration file that Biome loaded — i.e. the same directory of the config used to power `biome lint`.


The plugin will now be enabled on all supported files the linter runs on. You
can see its results when running `biome lint` or `biome check`. For example:

Expand Down
4 changes: 4 additions & 0 deletions src/content/docs/reference/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,10 @@ The order of paths to extend goes from least relevant to most relevant.
Since v2, this option accepts a string that must match the value `"//"`, which can be used
when setting up [monorepos](/guides/big-projects#monorepo)

Most relative paths inside a configuration file are resolved relative to the extending config. There is one exception:
`plugins`. Plugin path entries starting with `./` or `../` are resolved relative to the configuration file where they
are declared, even if that file is pulled in via `extends`. See [Linter Plugins](/linter/plugins) for details.

## `root`

Whether this configuration should be treated as a root. By default, any configuration file is considered a root by default.
Expand Down