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.