RFC: Biome plugins

[arendjr]

Update 2: Plugins are coming to Biome 2.0: #4428
Update: A follow-up RFC, based on the results and discussions here, has been presented: #1762

As many of you are aware, Biome's roadmap for 2024 includes the goal to develop a plugin system. But as the post mentioned, we don't yet know what those plugins will look like, what use cases they will cover and/or what technology we will use to implement them. What we do know, is there are plenty of ideas out there :)

So rather than proposing a specific solution, this RFC is intended to gather your input: What functionality do you miss in Biome, and do you think a plugin might help to cover it? What are you looking forward to in plugins the most? What will make or break our plugin system in your mind? This is the place to speak up!

I have attached a poll to take people's votes on preferred technology choices, and I will also create a few threads to help guide the discussion around various use cases. If you think anything is missing, feel free to create your own! You can also upvote use cases you think should be prioritized.

[arendjr]

Use case: Formatter

Do you think Biome's formatter should support plugins? If so, what kind of things you want to use it for?

Please keep in mind we cannot format anything we cannot parse. Does that mean our parser should support plugins too? Speak your mind!

[ssalbdivad]

If an alternate ternary formatting for types is not considered, a formatter plugin would offer an escape hatch for what I otherwise find a big issue for readability (see #2388).

[jeremyjacob]

Formatting the HTML and template bits Svelte files would be great.

Tailwind's prettier plugin that sorts classes also hooks into the TailwindCSS config to sort non-tailwind classes to the front. That wouldn't be something I'd expect to have built into Biome.

[Liam-Tait]

Biome’s formatter should not support plugins that can modify the code style.
Introducing plugins that can modify the style is analogous to introducing new options, undermining the consistent style.

A quote from the option philosophy

No matter the project, no matter the setup, code formatted by Biome will always look the same.

Does this quote still apply when the code style can be modified with a plugin?

[seahindeniz]

@Liam-Tait, plugins are based on the idea of giving the ability to customize the I/O in almost every library/app that has a plugin system.

I believe that statement will be updated to satisfy the plugin system that has the ability to format the code. Like a disclaimer text 🤔

[arendjr]

Use case: Linter

Do you think Biome's linter should support plugins? If so, do you have specific rules in mind?

What kind of API do you think we could use to report diagnostics? How would we support fixers? Let us know!

[Hebilicious]

@morgante If I'm not mistaken, grit currently doesn't work with embedded script tags (vue/svelte/astro files).
I assume that it should not be an issue since Biome would just use the gritQL DSL, not grit itself. Am I correct ?

[morgante]

Parsing embedded scripts is fine - Biome just needs to choose which code regions to analyze.

[nikeee]

React 19 will support React-Compiler. React-Compiler has new linter rules that go beyond the normal react-eslint Plugin.

The eslint plugin for the React Compiler just invokes the compiler and collects its output. However, the React Compiler is written in TS/JS, so adding it natively to Biome won't happen (see #3 (comment)).

So I think the easiest way for this to happen is JS/TS plugins, which can in turn invoke the React Compiler, just like the ESLint plugin does. This is why I vote for JS/TS interfacing with biome.

[bitttttten]

We have a few custom rules that we use in a project, we want to enforce certain variable names when you import from our api, so that there is consistency. We also don't want people to call hooks from our api and also grab a property or value on the same line.

i.e. we disallow useApi().data but allow const api = useApi(); console.log(api.data). we find it makes it easier to scan since we are so used to reading this piece of code, and also creates less git diffs. If you are used to seeing const api = useApi(), then const data = useApi().data is not as immediately clear and decreases scan-ability.

We also have a rule that disallows empty objects being passed to our api, instead we enforce undefined. This is because we cast the variables to a string for caching, and if you pass in undefined over here, and an empty object over there, you get different results back.

i.e. we disallow useApi({}) and useApi({}, { someOption: true }). Instead, you must do useApi() and useApi(undefined, { someOption: true }). The signature of this function is like useApi<V, O>(variables: V, options O).

We'd love to move to biome although we'd need to move these custom eslint rules over too.

[arendjr]

Use case: Transformer

Do you think Biome's upcoming transformer functionality (see roadmap) should support plugins? Or maybe it should even be built around plugins from the ground up? Your ideas are appreciated!

[conartist6]

The second problem with a non-pure AST is that you don't really know if it's printable. Whenever you make up a program out of an AST to be safe you really need to print it and then parse what you printed, because many printers if not most printers will gladly emit illegal syntax when confronted with subtly incorrect object trees. After all, if they handled all those edge cases, they would just be parsers!

[conartist6]

Also how would you know what to disallow? Some code may need to be formatted using unicode escapes in identifiers due to limitations in textual encoding scheme, for example. You can't rely on being able to make a hard and fast rule against unicode escapes, which will occur in more normal places like strings too.

[HerringtonDarkholme]

transformation will be very helpful for custom usage (say transforming i18n, custom jsx syntax, or special decorators)
AST based manipulation should be enough for transformation if transformation is not driven by trivias.
e.g. changing a variable name can be as easy as an assignment. there is no need to interact with actual spaces here.

if (node.name === 'longlongname') node.name = 'short'

Exposing CST details may make the transformation conflict with the formatter. CST can be stored somewhere in the data structure since biome needs it for later formatting, but exposing it to plugin users seems to be more complicated and slower than not.

[conartist6]

@HerringtonDarkholme How are you suggesting that would be implemented? Would node be a plain JS object, or a facade wrapping a Rust CST node? In other words, does node.name = actually update Biome's tree directly, or will we have to rebuild Biome's tree by some diffing process later?

[HerringtonDarkholme]

Would node be a plain JS object, or a facade wrapping a Rust CST node

I would argue it should be a facade (probably a JS proxy) wrapping Rust data structure. Serializing/deserializing a whole tree will be very expensive. A facade can avoid the cost and only deserialize sub-tree. Also see similar issue in oxc-project/oxc#1680

will we have to rebuild Biome's tree by some diffing process later?

Yes

[conartist6]

Use case: Query engine

Linter and Formatter are too task-specific. What underlies each of them is querying, and querying is a desirable ability even in the absence of the need to change formatting or detect known mistakes. If Biome is the thing tasked with understanding conceptual overlays on your code, I would definitely hope that I respond to queries without requiring me to define a lint rule or a formatter plugin.

[DaniGuardiola]

even if the plugin is wasm?

[arendjr]

@DaniGuardiola Yeah, unfortunately I don't think WASM will have that much of an advantage over JS/TS here, since we would still need to serialize a codebase-wide traversal from Rust to the plugin.

[conartist6]

@arendjr You say you'd need to serialize the traversal from Rust to the plugin, but remember that you might only be doing that work once for the entire set of plugins running in the scripting environment

[conartist6]

My point is that whether that cost is too high to pay (or even has much impact on perf at all) depends greatly on what benefit you derive from it.

[webpro]

@arendjr @DaniGuardiola Feel free to hit me up and talk about Knip, happy to chat about it.

[nstepien]

Use case: Codemod

https://github.com/facebookarchive/codemod
https://nextjs.org/docs/app/building-your-application/upgrading/codemods

Codemods can be used to help migrate codebases or adopt new patterns.
I'm not sure this is 100% plugin territory though.

[arendjr]

I like it. I suspect if we have transformer plugins, it should be relatively straightforward to offer codemod functionality too, no? It’s maybe a tough question to answer since we don’t have transforms yet, or do you see something particular that stands out?

[nstepien]

Codemods are definitely dependent on transforms, but they're one-off operations so I'm not sure you would configure them as part of something like biome's plugins: [] setting.

[DaniGuardiola]

npx @biomejs/biome codemod GitHubUsername/repo

or npm package

[mizdra]

If Biome provides codemod functionality, I think its advantages are unclear. There may be people who want the performance benefits that come with Biome. However, since codemods are typically used only once, I don't think performance is a important factor.

[HerringtonDarkholme]

whether codemod should be a separate topic from transformation mainly depends on the transformation API.
if the API allows one to write one-off transformation without touching config, there is few need for shipping codemod.
However, transformation API should also be integrated enough to the CLI so that transformation API users don't need to traverse code files themselves.
Otherwise, a dedicated codemod API is still valuable.

[dikaio]

Use Case: Tailwind Class Sorting

Prettier just had an update that handles tailwind class sorting, which would be a nice addition to biomejs.

https://tailwindcss.com/blog/automatic-class-sorting-with-prettier
https://github.com/tailwindlabs/prettier-plugin-tailwindcss

[ematipico]

We are already working on this:

• https://biomejs.dev/linter/rules/use-sorted-classes/
• ☂️ Tailwind class sorting lint rule #1274

[vlechemin]

Similarly Vue attribute sorting would be nice

[RafaelKr]

It would also be great to have this supported in "supersets" of HTML, e.g. template engines.
To me (and probably the whole Symfony Ecosystem) it would be especially helpful if Twig templates will be supported.

Also see #1274 (comment)
There I also linked an example twig-html file: https://github.com/symfony/demo/blob/7169fb500af3be8fdcfb7badb38ac6ed88020882/templates/base.html.twig

[morgante]

In parallel to the work @arendjr is doing on enabling GritQL in Biome, I've also started working on a TypeScript interface for the Grit engine. I think this will likely end up being very useful to Biome plugins because it allows logic to be written/compose in TypeScript while the actual processing happens mostly in Rust.

I'd love feedback from the Biome community on the API before I go too far into implementation: getgrit/gritql#403

[rluvaton]

I think Rust plugins should be consider as well, to avoid getting to the same position we are currently in with slow eslint plugins

[arendjr]

We may still support WASM plugins at some point, which could then be written in Rust. But it’s not a focus right now.

Btw, the GritQL plugins we are currently working towards should be very high-performance because it essentially relies on a pattern matching engine that is fully written in Rust. They’ll be less powerful than JS/TS plugins, but when we introduce those the goal is to leverage the same GritQL engine so the plugins themselves only need to implement the logic that cannot be expressed in patterns. The expectation is that this will be plenty fast for the vast majority of use cases.

[wojtekmaj]

I'm not entirely convinced on the idea of Biome plugins. I realize that might be a controvesial take, but hear me out. :D

Many "ESLint refugees" found Biome appealing because of its simplicity, performance, and ease of use largely thanks to "batteries included" approach.

ESLint is not a pleasant tool to use. The maintainers were met with a rather mixed community response regarding the introduction of Flat config, which although may have had good intentions, resulted in even more burden on developers' backs.

With all due respect to the ESLint maintainers; the switch to Flat config was communicated literally years before it happened, it was widely discussed, and it was a much needed change. But it was "much needed" because of what ESLint has become over the years - a highly configurable, extensible, but also an incredibly complex linting tool.

The community just never stops wanting more, and ESLint maintainers, were not in a position to say no: ESLint without its plugins is completely useless nowadays.

I would not like it for Biome to repeat the same story. With the introduction of plugins:

• We decentralize development of important Biome features, leading often to multiple, often competing, half-baked, low-performance, low-quality solutions; negatively affecting hard earned Biome developer experience.
• We remove the incentive for the development of Biome itself, "batteries" are not "included" anymore.
• We make funding more complicated; users are unsure which project(s) to support, and where that support is actually needed - something Biome maintainers may know best.

[arendjr]

I don't think your take is that controversial at all, I'm quite aligned with it! :)

The way I see it is that plugins are very much an additional feature for Biome rather than a replacement for the batteries-included approach that we have today. As you point out, native, built-in rules are a core strength of Biome and I think we should keep that approach even when we have plugins. But we also have to remain realistic and know that we cannot fulfill all user requests with a batteries-included approach, so that’s the gap which plugins are supposed to fix IMO.

[kariudo]

While I agree with the sentiment here, and the "batteries-included" approach is nice. To keep in the analogy, many users with power powerful uses for a tool will throw away the batteries that were included to use the "better batteries" they need in that same tool.

I don't think the existance of support for customizing Biome will defeat the purpose of idiology of it supporting an opinionated set of included rules/etc. I think the importance of having support for plugins is emphasized by looking around out all the issues and discussions where "x rule" is missing and the number of commentors saying "this is sadly a deal breaker" or a "road block" and forcing them back to their existing eslint tooling, despite the massive performance improvements provided by biome.

In my personal two cents experience, I moved all of our tooling for a major product to Biome to save a ton of time being spent on CI/CD, git hooks, and IDE delay; however, the missing rules/plugins are causing some headaches in enforcing assorted style guidelines. So I am strongly in support of plugin support, nothing says you need to use them, so long as the tooling remains "batteries-included" without them.

[antfu]

I would not like it for Biome to repeat the same story

ESLint's story isn't that bad. It's indeed some pain about the config system, the fragmentation of the plugin ecosystem, etc. But I won't say it's because of the "introduce of plugins", but rather, the historical reason of JavaScript, the language and best practices have evolved so much in the past years since ESLint was created. And actually, the whole point of ESLint to exist is to have an extensible linter interface. IMO, the fact that ESLint supports plugins makes the community able to try so many different approaches/integrations, that have the JS ecosystem we have today, and also the foundation of Biome's builtin rules, as many of those best practices has been battle-tested with ESLint's community rules.

Let's take another example that better shows my point - Vite. From my perspective, without plugins, Vite won't be anything as it today. Vite is rather battery-included, it handles HTML, CSS, TS, Workers, HMR, etc. Out-of-box. While having the plugins allows so many meta-frameworks to build amazing things on top of the great foundations. In that case "I wish Biome to have a similar story" - by having a great plugin ecosystem with a strong community around it that innovates and moves forward together.

[ekwoka]

I think Linting is the primary place, where some extra rules can be easier to add.

But beyond that, the most important would actually be full language support. Or at least these Framework things, like Svelte and Vue or Astro. Being able to inform Biome how to treat these kinds of "multi language" files.

I think favoring WASM as the starting point would be smart, with JS/TS simple as a second. Like using a direct Rust JS Engine that may lack many features, but can process the AST.