Support alternative linters such as Biome

[shirakaba]

Goals

1. Extract the doctoring logic from next lint and move it to its own independent command (e.g. next doctor)
2. Allow users to lint using their own linters, such as Biome, without wrapping it in a CLI tool like next lint

Non-Goals

1. Providing boilerplate for all possible linters in Next.js itself (instead, it should provide a way for the community and users to provide their own linting boilerplate)

Background

The case against eslint and prettier

Eslint is deprecating formatting rules and community momentum for formatting looks set to move from prettier to Biome. Thus, the current "format with prettier, lint with eslint" setup (which has always pain-points due to mutually exclusive rules and setting up two different tools) is looking less attractive in the long term than simply "format and lint with Biome"..

Users can't bring their own linter

Another discussion has raised the case for documenting how to integrate Biome, but this isn't merely a matter of documentation, as I'll explain below.

As of today, starter templates (at least for Turbo) typically configure projects to lint using next lint. This prevents users from bringing their own linting setups as linting is dependent on the Next.js CLI.

Unfortunately, we can't simply ditch next lint, as it does more than just linting. It does some significant (and valuable) doctoring, too.

next lint, as of v14.0.4, does the following:

• it configures some default values for the CLI flags to pass to eslint. Actually, in most cases, it simply defaults to the same default as the eslint CLI, but it does provides React-appropriate default values for the args --ext and a Next-appropriate --cache-location.
• it sanity-checks the repo for you. Namely, it:
  • checks whether you've installed typescript, @types/react, and @types/node
  • reconfigures (or creates) your tsconfig.json:
    • ensures you have the desired compiler options
    • ensures you have ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"] in your includes array
    • ensures that you have the Next.js plugin { "name": "next" } in your plugins array
    • ensures that you have strict type-checking
    • excludes node_modules
  • checks whether next-env.d.ts has been generated
  • can optionally run a type-check before any linting
• it may finally run eslint. We can avoid running eslint by deliberately omitting an eslint config and either:
  1. setting opts.lintDuringBuild: true (impossible because the value is hard-coded).
  2. setting opts.lintDuringBuild: false (which is the default) and selecting null when prompted which config to start with next time next lint is run. However, this is interactive, so unless we can find a way to pipe the necessary input into it via the shell, I am not sure how we can automate this.

Proposal

1. Deprecate next lint and allow users to use their preferred linter command directly.
2. Move all the doctoring logic into a next doctor command that users could optionally run as part of their linting step.

[JoeSlain]

Legit request, had to implement biome in my turborepo but still had to let next lint run during linting to keep doctoring functions. Would be nice to be able to chose

[wottpal]

This should get more attention. Biome is really becoming a way more performant replacement for the legacy prettier/eslint toolchain.

[l4b4r4b4b4]

Is this a WIP or already supported?

[shirakaba]

No new issues or PRs containing the word "Biome" have been opened on the Next.js repo since I opened this discussion, so there's no indication yet that this proposal is even under official consideration.

[davidlbowman]

Easy +1.

[admmasters]

This really needs to happen.

Nextjs used to feel like it was the future, now it seems to be in a bit of a mire:

• Turbopack is taking far too long and other stacks are thriving on Vite (see Remix and almost every other framework)
• Months without members of the core team even responding to valid issues and suggestions like this

Genuinely starting to ask the question is Nextjs really a good choice now?

[damien-schneider]

+1

[eliasdanielr]

+1

[John-Dennehy]

Would love to see more progress on this. Frustrating to see eslint issues during deployment, when it isn't part of my tool chain.

[Willem-Jaap]

You can add the ignoreDuringBuilds flag to next.config.js

module.exports = {
  eslint: {
    // Warning: This allows production builds to successfully complete even if
    // your project has ESLint errors.
    ignoreDuringBuilds: true,
  },
}

https://nextjs.org/docs/app/api-reference/next-config-js/eslint

[avaltat]

+1

[hgrafa]

+1

[eliasdanielr]

+1

[peterdinis]

+1

[HunteRoi]

+1

[hanan-yara]

+1

[ivanjeremic]

+1

[alexmandrikdev]

+1

[lyleunderwood]

Just wanted to point out that since Biome does not currently support custom rules, there is not a clear path to feature parity using biome as an alternative to the next eslint plugin. Until biome supports custom rules or the necessary rules are implemented into core biome, switching to biome as a linter in particular would definitely necessitate sacrificing some of the current features of the eslint plugin. This is obviously not necessarily relevant for other linting tools, but particular to Biome.

That being said, disentangling "doctoring" from linting seems like an obvious step forward.

Also please stop +1 posting.

[admmasters]

That's a fair comment, to give a slightly more blunt take on the situation, nextjs tying us to eslint feels limiting. To be be honest the days where we can justify migrating config (next is already behind the current version of eslint btw) are over. The eslint 8-9 migration feels extremely self indulgent and breaks a lot of packages, all the projects I work on with biome feel so much cleaner and don't need so many dependencies (we should be optimising for getting the job done as quickly as possible - eslint in 2024 feels like a total Frankenstein of a toolchain)

[manavm1990]

Also please stop +1 posting.

Yeah. I don't get this at all. I mean why people do this stupid stuff. Add some useful input, or just use the emoji reaction, or contribute something! 😮‍💨 Stop cluttering up the 🧵 to where we have to 📜 incessantly to get to anything useful! 👎🏾

Should be grounds for being blocked.

[ematipico]

That's a fair assessment, but it's also fair to let people choose their linter.

While some rules might be different or not implemented, maybe some users don't need them.

Regardless, it's good to give the choice

[pirmax]

+1

[dmythro]

I'd really love to see some action on this as Biome is much more preferable to me now, and as far as I know to a lot of devs too.

Probably, people behind @next/eslint-plugin-next can quickly provide better requirements, and stages for integration.

As far as Biome already supports some of the rules from @next/eslint-plugin-next, it is possible to setup at least a basic / recommended configuration to extend from as a starting point, to align with ESLint configuration at least partially.

Then, update Next configuration / documentation in order to support Biome as well. Maybe, run Biome instead of ESLint on build if configured etc.

See:

• https://nextjs.org/docs/pages/building-your-application/configuring/eslint#eslint-plugin
• https://biomejs.dev/linter/rules-sources/#nexteslint-plugin-next

[jxnnyo]

Is there any update on this? After taking some benchmarks, using Biome in my project would on average save 60x of time linting. Would be nice to know if this is denied/on the roadmap etc?

[ravi-outcomes-ai]

+1

[DarioLopes]

[GabenGar]

As if biomejs won't have to deal with breaking changes in the future.

[devth]

Whether a project choses to break their users with backward incompat changes is a decision. I think eslint lost trust from the community through years of unnecessary backward incompat changes. The hope is that biome would provide better stewardship and carefully consider impact to users.

[GabenGar]

You seem to be accustomed to a commercial view of semver major being just an excuse for the blog post and/or a conference when in reality it is used exactly for the purpose of signalling breaking changes to consumers in just a single string. It's pretty bizzare to expect a tool, which existed before ESM even becoming a spec, to retain the legacy behaviour across 9 major versions.
Biome itself doesn't provide a backward compat guarantee even between patch versions, so I guess don't use linters at all.

[devth]

Good point, but I'll give Biome a chance to slowly burn me over a decade+ first.

[Willem-Jaap]

Hi all,

You can implement your own linter (biome) just fine. There is nothing in Next.js which is blocking you from using Biome.

Follow these steps:

• Remove eslint and any related dependencies (probably prettier too)
• Add the following to your next.config

  eslint: {
    // Warning: This allows production builds to successfully complete even if
    // your project has ESLint errors.
    ignoreDuringBuilds: true,
  },

https://nextjs.org/docs/app/api-reference/next-config-js/eslint

• Install biome: https://biomejs.dev/guides/getting-started/
• Add the biome script to your package.json

{
  "scripts": {
    "lint": "biome check ."
  }
}

• Configure biome to your liking.
• Run the biome script as your linting step and before build
• 🎉 Done

I have seen a lot of people talking about a mismatch of linting in builds in other issues. This is not related to eslint, rather the typescript compiler which runs during next build. If you're setting up a linting step in a CI/CD pipeline you probably want to add a 'type-check' step before build which runs the typescript compiler to check for typing issues:

{
  "scripts": {
     "type-check": "tsc --noEmit"
  }
}

Warning

When implementing this yourself you are missing out on the doctoring logic of next lint (see issue description) but in my experience this is fine in most cases

I still really would love first party biome support!

[lyleunderwood]

As somebody who is already using biome with next and currently doesn't have doctoring, I'm subscribed to this discussion because this discussion is about separating out doctoring from linting.

[wlechowicz]

Nice write-up, but completely missed the point.

There is nothing in Next.js which is blocking you from using Biome.

but

When implementing this yourself you are missing out on the doctoring logic of next lint

meanwhile this is the whole point of this entire discussion.

Nobody said "you can't use Biome".

[lyleunderwood]

Nobody said "you can't use Biome".

Maybe it's the title on the discussion:

Support alternative linters such as Biome

Depending on your definition of "support," next does indeed support alternative linters such as Biome. The very first thing said in the description, however, is:

Extract the doctoring logic from next lint and move it to its own independent command (e.g. next doctor)

A more appropriate title might be,

Improve DX when using alternative linters such as Biome

There are really two parts to this, as I see it:

1. Separating out doctoring, and
2. Some minimal documentation about bringing your own linter.

[bitttttten]

what's the difference between next lint and what biome can do? what are we missing from next lint that is not in biome already?

[lyleunderwood]

See the list of doctoring operations listed in the OP.

[felipedeboni]

Looking forward to this too as I am sick of ESLint breaking changes and wasting a lot of time on something that should be stable enough.

Apart from that Biome is way faster then Eslint and Prettier.

[EfstathiadisD]

I am not sure what is stopping you. Are you using next lint? Cause that's being terrible from the start.

I have my own fmt command that uses biome. You can do it. I guess y want an option on next lint to not do the work hourselves. Right?

[manavm1990]

Well, we're using Next for everything else, so it makes sense to have this option taken care of also.

And, yeah, configuration 🔧 details like that aren't the best use of time.

[alicercedigital]

+1

Biome is like a car, while ESLint is a horse. Cars are a recent invention and may not yet be the perfect replacement for horses, but the shift is inevitable. Eventually, we'll have to bid farewell to the old horse.

[Zerebokep]

Agree, I've switched completely to biome after eslint's v9 f*ckup, I'll never touch eslint again. Biome's DX is awesome.

[Willem-Jaap]

Same here, migrated some pretty large monorepo's (500+ files) to Biome. Changes in almost every file. Tried to keep the formatting config as close to prettier as possible. Errors that were reported were generally quite useful, even catched some bugs.

Changes that are required are mostly not too difficult, added some biome ignores to look at later

Am missing some eslint features but it was definitely worth it, I'd estimate we save 1000 minutes on CI time a month by switching to Biome

[devth]

The most insane part about biome is defaulting to tabs (LOL) but otherwise it's incredible.

[Zerebokep]

I did 5 migrations so far, biome's learning curve is very flat, everything works out of the box, prettier is also not needed anymore. At your first migration there might be some rules missing, but biome had a replacement for anything I use. The majority of work is to replace eslint comments, plus code optimizations here and there which eslint didn't catch (e.g. foreach vs for..in).

Performance is also WAY better than eslint, I guarantee you that you will not walk back to eslint after you tried it.

[devth]

Did you need to manually enable a bunch of rules to make it work well with React, like useEffect dependency arrays, or anything else? I'm slightly worried that when I switch I'll have less rules being checked but won't really know they're missing until I discover a bug down the road.

[Zerebokep]

I only have 7 rules added in our react project where 3 of them disable some of the "too strict" default rules of biome, useEffect dependencies are checked by default.

You might check the biome docs, all (default) rules are listed there. I've also seen some best practices biome configs in the wild.

[felipedeboni]

I am almost finishing the migration to Biome while keeping next lint. It's a bit hacky, but it's what it's.

All that needs to be done is to patch eslint-config-next and remove everything you don't care about.

This is how my patch looks like:

diff --git a/index.js b/index.js
index 4c95a88ad4fba7c4257ab5071dbc581d63ee55b4..d5cf85a4aa52dc46d28adbf38ca7b5e44ca6d1d0 100644
--- a/index.js
+++ b/index.js
@@ -31,9 +31,7 @@ sortedPaths.push(...keptPaths)
 const hookPropertyMap = new Map(
   [
     '@typescript-eslint/eslint-plugin',
-    'eslint-plugin-import',
-    'eslint-plugin-react',
-    'eslint-plugin-jsx-a11y',
+    'eslint-plugin-import'
   ].map((request) => [
     request,
     require.resolve(request, { paths: sortedPaths }),
@@ -54,30 +52,9 @@ require('@rushstack/eslint-patch/modern-module-resolution')
 
 module.exports = {
   extends: [
-    'plugin:react/recommended',
-    'plugin:react-hooks/recommended',
     'plugin:@next/next/recommended',
   ],
-  plugins: ['import', 'react', 'jsx-a11y'],
-  rules: {
-    'import/no-anonymous-default-export': 'warn',
-    'react/no-unknown-property': 'off',
-    'react/react-in-jsx-scope': 'off',
-    'react/prop-types': 'off',
-    'jsx-a11y/alt-text': [
-      'warn',
-      {
-        elements: ['img'],
-        img: ['Image'],
-      },
-    ],
-    'jsx-a11y/aria-props': 'warn',
-    'jsx-a11y/aria-proptypes': 'warn',
-    'jsx-a11y/aria-unsupported-elements': 'warn',
-    'jsx-a11y/role-has-required-aria-props': 'warn',
-    'jsx-a11y/role-supports-aria-props': 'warn',
-    'react/jsx-no-target-blank': 'off',
-  },
+  plugins: ['import'],
   parser: './parser.js',
   parserOptions: {
     requireConfigFile: false,

Also you lint script should be updated to:

"lint": "biome lint . && next lint"

Output becomes:

➜ pnpm lint

> lint /path/to/project
> biome lint . && next lint

Checked 134 files in 8ms. No fixes applied.

./path-to-file.tsx
24:5  Warning: Using `<img>` could result in slower LCP and higher bandwidth. Consider using `<Image />` from `next/image` or a custom image loader to automatically optimize images. This may incur additional usage or cost from your provider. See: https://nextjs.org/docs/messages/no-img-element  @next/next/no-img-element

info  - Need to disable some ESLint rules? Learn more here: https://nextjs.org/docs/app/api-reference/config/eslint#disabling-rules

Only downside to that is the editor don't show up any ESLint violations, only through command line.

---

Additionally, you can make your team life easier with the following additions to the project (if using vscode).

project settings.json:

{
  "biome.enabled": true,
  "eslint.enable": true,
  "sort-imports.on-save": false,
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnPaste": false,
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "quickfix.biome": "always",
    "source.organizeImports.biome": "always"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[typescript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[json]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[css]": {
    "editor.defaultFormatter": "biomejs.biome"
  }
}

project: extensions.json

{
  "recommendations": [
    "biomejs.biome"
  ]
}

If you have many projects using ESLint and Prettier and will migrate one at time and is annoyed by the error message that shows up when biome isn't detected, take a look here

[lveillard]

Following so I can throw a big party once we get rid of ESLint. ESLint 8 was painful enough, but 9.x has exceeded all my worst expectations.

[devth]

+1000. Delete eslint.

[Netail]

Biome is working hard on version 2.0, with plugin support. Which the NextJS team is perhaps waiting on?