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

[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

[PaulRBerg]

Silly question but how do you patch eslint-config-next like you did? Is there a fork?

[felipedeboni]

@PaulRBerg there are a couple options depending on your package manager.

With pnpm or yarn just execute one of the following and follow the instructions.

pnpm patch eslint-config-next
yarn patch eslint-config-next

With yarn 1 or npm you need to install patch-package, if that's the case just follow patch-package guide.

[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?

[suiramdev]

This seems to be the case, as they have just deprecated the vercel/style-guide repo.
I read somewhere on X, from Lee Robinson, that he recommended using Biome instead.

Oh and they are also sponsors of Biome

[destroyer22719]

I think that we might be getting nextjs with biome? Because first the biome 2.0 allows custom plugins, which is a huge step in the right direction, but the biggest one of all is domains for nextjs: https://next.biomejs.dev/linter/domains/#next

They're still missing some features from the original eslint plugin: https://nextjs.org/docs/app/api-reference/config/eslint

But given that Vercel is sponsoring Biome and that they're using it in a monorepo, could this be a sign that biome will soon be an option for nextjs when biome v2.0 is out of beta?

[TeoChi-CF]

Another option, similar to #59347 (comment) is to revert to base eslint config file

{
  "extends": "next"
}

and if after applying the required Biome linter changes there are some differences/conflicts that come up during next build, just disable those specific eslint rules:

{
  "extends": "next",
  "rules": {
    "react-hooks/exhaustive-deps": "off"
  }
}

No patching or any other hackish solution required. You'll have to keep the eslint config file till a better solution is implemented though.

[chriscoomber]

Going further, your .eslintrc.json can just be:

{
  "ignorePatterns": ["/*"]
}

if you want it to truly do nothing.

[destroyer22719]

Hey guys, so Biome v2 is finally stable and that means you can now make custom plugins, does Vercel now have plans to give users the option to use biome for next lint and next build?

https://biomejs.dev/blog/biome-v2/

[dmythro]

Hey guys, so Biome v2 is finally stable and that means you can now make custom plugins, does Vercel now have plans to give users the option to use biome for next lint and next build?

https://biomejs.dev/blog/biome-v2/

As far as I've seen, Vercel is a prestige sponsor of Biome now, so 🤞

[abed-daloopa]

I think there's no need for them to create a plugin.

Next is a first-class "domain" in Biome v2

https://biomejs.dev/linter/domains/#next

[Yohannfra]

Hi, I know this discussion is mainly about biome but last week there is also Oxlint that came out in 1.0.0 and it works really well for my turborepo and nextjs codebase.
There is even an official nextjs plugin (https://oxc.rs/docs/guide/usage/linter/plugins.html).

[dmythro]

I've heard about oxlint but didn't try yet — and no, I think this thread is about any tool people like, and to be able to use it seamlessly with Next :)

The more you mention the tool you like — the more chances for a better integration.

[Yohannfra]

You should give it a try with npx oxlint@latest then, it's really fast.

Btw this is my .oxlintrc.json if you want to try with more rules

{
  "plugins": ["typescript", "unicorn", "oxc", "import", "node", "promise", "react", "react-perf", "nextjs"],
  "rules": {
    "no-duplicate-imports": "error",
    "typescript/no-explicit-any": "error",
    "eqeqeq": "error",
    "curly": "error",
    "typescript/no-unused-vars": "warn",
    "typescript/explicit-function-return-type": "error",
    "typescript/no-empty-interface": "off",
    "typescript/consistent-type-imports": "error",
    "typescript/require-await": "warn",
    "react/self-closing-comp": "error",
    "react/exhaustive-deps": "error",
    "react/jsx-no-useless-fragment": "error",
    "nextjs/no-img-element": "off",
    "no-console": "off",
    "no-alert": "warn",
    "no-else-return": "error"
  }
}

A simple benchmark of the two commands on my nextjs codebase:

# oxlint
pnpm run oxlint  0.92s user 0.60s system 249% cpu 0.612 total

# eslint
pnpm run lint  30.97s user 2.79s system 164% cpu 20.583 total

Less than a second for oxlint and 30+ seconds for eslint

[n2k3]

It happened: https://nextjs.org/blog/next-15-5#next-lint-deprecation