eslint-plugin-nextjs

Overview

This is a unofficial fork of @next/eslint-plugin-next with TypeScript and ESLint v9 support. I have no association with Vercel or the Next.js team. I just needed an updated version of the plugin for my style guide, js-style-kit.

If you're using eslint-config-next, you do not need this plugin. You only need this plugin if you're rolling your own ESLint config.

Beginning with v1, this plugin is ESM only and requires ESLint v9. If you need legacy support, use v0.1.2.

Requirements

• ESLint v9
• Node.js v20.11.0 or higher

Installation

npm i eslint eslint-plugin-nextjs -D
# or
yarn add eslint eslint-plugin-nextjs -D
# or
pnpm add eslint eslint-plugin-nextjs -D
# or
bun add eslint eslint-plugin-nextjs -d

Usage

I've cleaned up the API, so it's not 1:1 with the original plugin, but all of the rules remain the same.

The original plugin ships two configs, recommended and core-web-vitals. They're the same but the latter has two rules upgraded to errors. I've consolidated this to a single "recommended" config with all rules warnings by default.

My belief is that all ESLint rules should be warnings to allow you to distinguish between ESLint issues and TypeScript issues easily in your IDE (orange squiggly vs red squiggly).

If you're migrating from either config, all rules will still be enabled. I didn't changed any core functionality.

Note: If you run this plugin with next lint, it will give you a warning that the next eslint plugin is not installed. You can either ignore this, or run your lint with eslint . instead.

Flat Config

// eslint.config.js/mjs
import nextjs from "eslint-plugin-nextjs";

export default [
  // ... other configs
  nextjs.configs.recommended,
];

If your project has "type": "module" in package.json, you can use eslint.config.js, otherwise use eslint.config.mjs which will allow you to use ESM syntax in that file.

Custom Config

import nextjs from "eslint-plugin-nextjs";

export default [
  // ... other configs
  {
    plugins: {
      nextjs,
    },
    rules: {
      // note that the prefix is different, the original plugin uses "@next/next/"
      "nextjs/google-font-display": "warn",
      "nextjs/no-img-element": "warn",
    },
  },
];

Rules

See Vercel's documentation for rule details. I'll add a proper rule table here in the future.