Biome plugins distribution

[ematipico]

Since v2, Biome now supports plugins via GritQL, however users can't distribute/share these plugins at the moment.

The initial idea behind this plugin system was to provide users the ability to create custom rules for their own projects. These rules would make sense only within an organisation or project, and shouldn't be shared or distributed to people outside the organisation or project.

If users need to share a plugin inside an org, nowadays, git submodules are a valid alternative. However, what if a user wants to use npm to distribute their plugins? Is it a valid case for Biome? What about rules inside monorepos?

---

Before jumping into discussions and saying "yes, plugins everywhere", I advise you forget for a moment the ESLint plugin model and take a step back.

One of the reasons users love Biome is that, unlike the ESLint plugin model, they don't need to install plugins to get their project up and running. What does this mean? Here are a few wins:

• Documentation in one single place
• Developers need to maintain a single dependency
• Developers need to interact with a single project/team if they require a fix, and they can contribute to a single project if they want to ship a fix
• High-level of DX and documentation

IMHO, language isn't a factor. While JavaScript (for future plugins) might be easier to learn and would get us easier contributions, I think language is just a medium, and eventually developers may/need to learn different languages.

Biome has recently started shipping rules that are framework-specific. While there's the argument that rules that belong a specific library/framework should belong to a plugin, we believe that native rules are faster, and offer a better DX overall.

[arendjr]

#6246 made me realise that if we fix it, users do have a workaround for distributing plugins, albeit a contrived one. If users distribute plugins inside "extends packages", the consumer of the package cannot really determine which files the plugins should operate on anymore. That might be acceptable for some use cases, especially within organisations, but I wouldn't recommend it as a means for general distribution.

[silouanwright]

I strongly agree with keeping custom rules internal and avoiding broad plugin distribution. ESLint’s history shows that plugin sprawl leads to fragmentation, config conflicts, and maintenance headaches. We should be cautious of any advocacy for pushing for plugins at all costs—often, this comes from a place of not having to have dealt with the real complexity this creates.

Biome’s simplicity and cohesion are worth protecting; teams should keep their own rules private and not repeat past mistakes.

[silouanwright]

What’s difficult, I think, is that there’s definitely an advantage to having software-specific linting rules—like for Storybook, Next, Turborepo, or React Testing Library, which helps you lint their own custom software. We just don’t want the custom distributions people would inevitably try to make. That's where all the complexity comes from.

Maybe there’s a way to allow the former, but disallow the latter?

[dyc3]

We have rule domains now, which I believe addresses this concern. For example, we have a react and a next domain for organizing rules that only apply to react and next.js respectively.

[silouanwright]

Hmm... just to rephrase my question:

These are all very popular packages which are publishing their own ESLint rules: Storybook, Next, Turborepo, React Testing Library, Effect TS, etc.

It seems like there are a couple of approaches you could take, in regards to supporting this on the Biome side of things:

• No support for these (which does give ESLint an advantage, and also would eliminate some positive DX that comes with software solutions who help you fall into the right patterns with these linting rules)
• They can give you snippets of linting rules for Biome, which you can copy and paste (which has it's own issues)
• You will support these solutions coming into the Biome repo and making PR's for adding rule specific domains for their own use cases?

I think it would be helpful spelling out explicitly what the plan is here for third party libraries who have legitimate use cases for linting rules, and all the ramifications that go with that.

[arendjr]

You will support these solutions coming into the Biome repo and making PR's for adding rule specific domains for their own use cases?

The main idea is that we will indeed support third-parties who want to upstream their rules into Biome. Hopefully this wouldn’t lead to domains with just a single rule (if it would, what is the point of a domain, as it is just as easy to enable an individual rule as it is to enable a domain?), but I don’t see a problem with domains that only have a few rules.

[silouanwright]

I think this is a good compromise. Though it definitely comes with tradeoffs.

• It’s undeniably easier for third-party teams to manage their own linting rules within their own codebases.
• Because Biome requires new rules to be reviewed and merged upstream, it can be slower to adopt the latest or experimental linting rules, especially for fast-moving or beta software. In contrast, ESLint’s plugin model lets teams quickly release and share new rules, which can make it more attractive for those who need cutting-edge linting support. And things like this will lead to some level of resistance towards utilizing Biome.
• Biome contributors now have the extra burden of reviewing and merging these rules, and will have to mediate disagreements about what belongs in each domain. Should the teams that own the relevant technologies get more say? Maybe I'm getting ahead of myself.
• Because Biome controls the domains, upgrading Biome could force teams to address changes across multiple domains at once. With ESLint, it’s simpler to update one plugin at a time.

Still, I’m convinced this approach is the right one. It supports the need for custom rules, avoids forcing teams onto a different tool for this purpose, and helps prevent the inevitable slinging of fragmented custom rule distributions. The benefits to maintainability and developer experience are worth the extra coordination required.

Dropping a link to the domain rules for anyone following along: https://biomejs.dev/linter/domains/

[eMerzh]

Indeed it would be more interesting to have things builtin than just look how eslint does and try to plugin-ize the whole world with 2400 extra packages.

That beeing said, as the existence of plugins says, there allways will be niche use cases, or internal policies that will not be covered by those.

Maybe a good place to start is just having a place (discussion, repo, .. you name it) where users can share their patterns.
Grit is currently not widely used and the syntax might be a bit tricky to handle at first (especially with differences between plain old grit and biome grit).
That could inspire users or let others learn from the previous

[Hazer]

We have a design-system repo with UI components, and we have some rules for the usage of those components, for now, we can use extends as a workaround, so the downstream projects will receive the plugins, but doesn't feel scalable. The plugins belong to the design system, the user is the downstream project, but the design-system shouldn't have any knowledge of the other biome settings the project uses. It also don't make sense to make our default config extends the ds settings, because not all projects use the design system, it's kinda messy right now to reuse enough, but not too much, it's a really thin line.

If the design-system could provide it as an extra export on the components package, and just reference it as the package name, that would be perfect for our use case.

[Hazer]

Having that said, I too feel that allowing plugin exports, may lead to fragmentation, having the option for a whole custom domain, with plugins inside, would probably be better, but I'm afraid the fragmentation will still exist, just be pushed a few layers up, but we would really make use of it.

[victordidenko]

I think, inability to distribute linting rules via npm will lead to distribution of just plugin files. With message like "As long as Biome doesn't support npm plugins, copy-paste those files in your codebase and include them in your biome.json file". This may lead to even bigger "fragmentation, config conflicts, and maintenance headaches".

Earlier was already mentioned that software-specific linting rules exists — like for Storybook, Next, Turborepo, or React Testing Library. But those are all well known and quite popular libraries. There are less known libraries, which provides their linting rules, for example Effector — I bet maybe just few of Biome maintaners even knows about this state manager. Are you going to embrace all possible libraries' custom linting rules? Will every change in rules for some library, I don't even know and don't use, be a bump new Biome version (because all rules a baked-in)? Who will decide what library's rules are worth including into Biome binary? Will you establish some "barrier measures" for libraries, let's say, stars count?

[Netail]

Although I agree with including framework rules into Biome, but there will probably be a line. Let's say there's this framework with only 1 user, does it get it's own domain? If yes, we could end up with a lot of rules specific to small software or frameworks in the binary.

Also, within our company we use a package to distribute config presets (react, tailwind, etc) and up to the consumer app to extend from any of the presets. However, we would also like to create some gritql plugins that are related to the company, for internal use only. These somehow needs to be distributed over several repositories, which we do not want to copy & paste, but shared through this package. So, importing from a package would be nice to have;

{
    "plugins": [
        "@netail/biome-plugins/noTestPlugin.grit"
    ]
}

(Which currently does not resolve from node_modules, unlike extends)

[arendjr]

I don't see a problem with a domain for a single user, but maybe such a user wouldn't mind maintaining their own fork 😆

More seriously though, I think you can indeed distribute plugins through NPM packages so long as you provide a relative path to the Grit plugin file. It's maybe a little hassle, but there are ways to make it work.

[Th3S4mur41]

I think it’s important to look beyond the idea that Biome’s appeal is only about “simple configuration” or “no dependency chains.” Those are great benefits, but what really differentiates Biome is the combination of speed, a unified execution model, and the absence of conflicts between separate tools like formatters and linters. That’s a much deeper value proposition than just avoiding extra packages.

At the same time, there’s a whole category of rules that teams rely on which Biome currently can’t express. In the CSS world, I previously used Stylelint plugins like defensive CSS and logical CSS. These don’t flag invalid CSS — they flag valid CSS that can cause accessibility issues, layout instability, or usability problems and enforce modern and more sustainable solutions. These rules are extremely valuable, but also opinionated and not universally applicable.

This raises the question of where such rules should live in the Biome ecosystem?

One option would be to include them in Biome core, potentially grouped into a dedicated rule domain that is disabled by default and enabled with a single switch. That would keep Biome simple for users who don’t need these constraints, while still making them first‑class for teams who do.

If Biome were to go in that direction, the open question becomes: what would the process and criteria be for creating these opt‑in rule groups? How do we decide which opinionated or higher‑level rules belong in an official domain?

On the other hand, a plugin mechanism would allow these rules to evolve independently of Biome’s release cycle and might be a better fit for constraints that are highly opinionated or dependent on project context (like browser support targets).

So I’m curious how the Biome team and its users envision this long‑term:
Should advanced rule sets like defensive CSS or logical property enforcement be part of Biome core as opt‑in domains, or is a plugin system the more appropriate model for these kinds of rules? And if domains are the preferred approach, what would the workflow look like for defining and maintaining them?

[arendjr]

So far we've indeed held onto the notion that such rules would be well served with a domain within Biome, since it sounds like they would be applicable/beneficial to larger groups of users. We've kinda held off the boat on plugin distribution based on the premise that plugins should be reserved for company/organisation-specific rules.

[Th3S4mur41]

@arendjr That'd be great in my opinion and is the answer I was kinda hoping for since it means there is no need for additional dependencies.
So the next questions would be:

• What domain (name) would you have in mind for this. Would it be a generic CSS domain with a split between recommended and all and maybe a third option like extended or something?
  Or rather a dedicated domain like defensiveCSS as a reference to the original rules?
• What would be the process to create those? Gather the rules in a new issue and create a PR with an initial set of rules or do you imagine something different?

[arendjr]

Yeah, I think starting with an issue would be good, since it will allow you to gauge interest and prioritise. I'm not opinionated on the names of the rules, seeing how not much of a CSS expert myself 😅

[Th3S4mur41]

I just created an issue to track this: #9034

[atrofimov-sc]

Enterprise perspective

From what I have seen in enterprise settings, Biome has been painful to adopt, and this decision is another serious blocker for us.

Why “one ruleset per framework” is not enough

A lot of linting is not tied to a product or framework (Next, React, Storybook, etc.); it is team- or org-specific. You cannot ship a fixed set of rules per stack and assume you have covered real-world codebases. Most code is private. There is no public “companyFoo/productX” domain for you to model, so a one-size-fits-all story does not match how large organizations work. Inside one company, many teams often cannot align on one policy, let alone the whole ecosystem.

The post does not really engage with the need for Biome to be extensible in the ways teams actually need.

Where ESLint still wins (for us)

###The gap with ESLint feels large:

• Team-owned plugins — teams can ship and share their own rules.
• TSDoc — linting and formatting around documentation comments.
• no-restricted-syntax — custom checks on the AST without a separate plugin ecosystem for every idea.
• Comments in the AST — rules can reason about comment blocks, not only code.
• Debuggability — you can step through and understand failures.
• Familiar authoring — plugin authors use JavaScript/TypeScript, not a new AST DSL.

Plugins and Grit

I was hopeful when you added some plugin story and thought AI could narrow the gap even if I did not want to learn another AST DSL. This update undercuts that.

We have hundreds of no-restricted-syntax rules. AI could help port many of them, but Grit’s AST story (e.g. no comment support and other limits) gets in the way. Worse: custom .grit plugins cannot be distributed the way we need across hundreds of repositories. A thread comment suggesting it is fine to copy rules misses the point — copying hundreds of files into hundreds of repos is exactly the maintenance burden that blocks adoption. That is why I am skeptical about real uptake until this is solved.

Ask

Please reconsider this direction and how extensibility and shared, distributable custom rules fit into Biome’s story for large, private codebases.

[ematipico]

Please reconsider this direction and how extensibility and shared,

It's possible you misunderstood the intention of the discussion. We haven't decided anything. This discussion is meant to collect ideas and consensus. I like your case!

[tyteen4a03]

It's kinda wild that after a year, there's still no decision on this, something that should have been decided before v2 GA.

I am considering switching to oxlint because this omission means in effect, Biome plugins do not exist.