---
title: ESLint Module
---

All-in-one ESLint integration for Nuxt. It generates a project-aware [ESLint flat config](https://eslint.org/docs/latest/use/configure/configuration-files-new) and provides the ability to optionally run ESLint check along side the dev server.

:::callout{icon="i-ph-lightbulb-duotone"}
This module is designed for the [new ESLint flat config format](https://eslint.org/docs/latest/use/configure/configuration-files-new) which is the [default format since ESLint v9](https://eslint.org/blog/2024/04/eslint-v9.0.0-released/). Flat config is supported since ESLint v8.45.0 so you can use any version of ESLint later than that. We recommend you to use the latest version of ESLint to get the best experience.
<br><br>
The legacy `.eslintrc` config is **not supported** by this module. We highly recommend you to migrate over the flat config to be future-proof.
:::

::read-more
---
to: https://github.com/nuxt/eslint/tree/main/packages/module
color: gray
icon: i-simple-icons-github
---
Source code on GitHub
::

## Features

- [ESLint flat config](https://eslint.org/docs/latest/use/configure/configuration-files-new), composable, customizable and future-proof.
- Project-aware Nuxt-specific settings, also supports [layers](https://nuxt.com/docs/getting-started/layers).
- [Nuxt DevTools](https://github.com/nuxt/devtools) integration powered by [`@eslint/config-inspector`](https://github.com/eslint/config-inspector).
- Extensible with other modules.
- Optional [dev server checker](#dev-server-checker) integration.

## Quick Setup

Run the following command to add the `@nuxt/eslint` module to your project:

```bash [Terminal]
npx nuxi module add eslint
```

Once you start your Nuxt app, a `eslint.config.mjs` file will be generated under your project root. You can customize it as needed.

:::callout{icon="i-catppuccin-typescript"}

If you are using TypeScript, you need to install the `typescript` in your project:

::code-group
```bash [yarn]
yarn add --dev typescript
```
```bash [npm]
npm install -D typescript
```
```bash [pnpm]
pnpm add -D typescript
```
```bash [bun]
bun add -D typescript
```
::

:::

### Manual Setup

::code-group
```bash [yarn]
yarn add --dev @nuxt/eslint eslint typescript
```
```bash [npm]
npm install -D @nuxt/eslint eslint typescript
```
```bash [pnpm]
pnpm add -D @nuxt/eslint eslint typescript
```
```bash [bun]
bun add -D @nuxt/eslint eslint typescript
```
::

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: [
    '@nuxt/eslint'
  ],
  eslint: {
    // options here
  }
})
```

And create an `eslint.config.mjs` file under your project root, with the following content:

```js [eslint.config.mjs]
import withNuxt from './.nuxt/eslint.config.mjs'

export default withNuxt(
  // your custom flat configs go here, for example:
  // {
  //   files: ['**/*.ts', '**/*.tsx'],
  //   rules: {
  //     'no-console': 'off' // allow console.log in TypeScript files
  //   }
  // },
  // {
  //   ...
  // }
)
```

`withNuxt` will take the rest arguments of flat configs and append them after Nuxt flat config items. You can either use the [Nuxt DevTools](https://github.com/nuxt/devtools) panel to inspect the resolved ESLint flat config, or manually run [`npx @eslint/config-inspector`](https://github.com/eslint/config-inspector).

## Recipes

### VS Code

ESLint v9.x support was added in the [ESLint VS Code extension (`vscode-eslint`)](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) v3.0.10.
In versions of `vscode-eslint` prior to v3.0.10, the new configuration system is not enabled by default. To enable support for the new configuration files, edit your `.vscode/settings.json` file and add the following:

```json [.vscode/settings.json]
{
  // Required in vscode-eslint < v3.0.10 only
  "eslint.useFlatConfig": true
}
```

### NPM Scripts

Add the below to lint commands to your `package.json` script section:

```json
{
  "scripts": {
    ...
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    ...
  },
}
```

Run the `npm run lint` command to check if the code style is correct or run `npm run lint:fix` to automatically fix issues.

### Prettier

This module does not enable stylistic/formatting rules by default. You can use Prettier alongside directly.

### ESLint Stylistic

If you prefer to use ESLint for formatting, we also directly integrate with [ESLint Stylistic](https://eslint.style/) to make it easy. You can opt-in by setting `config.stylistic` to `true` in the `eslint` module options.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: [
    '@nuxt/eslint'
  ],
  eslint: {
    config: {
      stylistic: true // <---
    }
  }
})
```

You can also pass an object to customize the rules:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: [
    '@nuxt/eslint'
  ],
  eslint: {
    config: {
      stylistic: {
        indent: 'tab',
        semi: true,
        // ...
      }
    }
  }
})
```

Learn more about all the available options in the [ESLint Stylistic documentation](https://eslint.style/guide/config-presets#configuration-factory).

### Config Customizations

`withNuxt()` returns a chainable [`FlatConfigComposer` instance](https://github.com/antfu/eslint-flat-config-utils#composer) from [`eslint-flat-config-utils`](https://github.com/antfu/eslint-flat-config-utils) which allows you to manipulate the ESLint flat config with ease.

```ts [eslint.config.mjs]
import withNuxt from './.nuxt/eslint.config.mjs'

export default withNuxt(
  // ...Custom flat configs append after nuxt's configs
)
  .prepend(
    // ...Prepend some flat configs in front
  )
  // Override some rules in a specific config, based on their name
  .override('nuxt/typescript/rules', {
    rules: {
      // ...Override rules, for example:
      '@typescript-eslint/ban-types': 'off'
    }
  })
  // ...you can chain more operations as needed
```

You can learn more about the options available with the types can JSDocs of the instance.

For all the available configure names, please use the DevTools to inspect.

### Config Inspector

This module ships [ESLint Config Inspector](https://github.com/eslint/config-inspector) in your [Nuxt DevTools](https://github.com/nuxt/devtools). You can inspect the resolved ESLint flat config there:

![ESLint Config Inspector in Nuxt DevTools](/images/devtools-inspector.png)

### Dev Server Checker

Usually you don't need this setting as most IDEs are capable of running ESLint directly to inform you of issues. It's also possible to set up a [pre-commit hook with `lint-staged`](https://github.com/lint-staged/lint-staged) to guard your codebase before committing.

That said, if you are working on a team using a variety of IDEs you may still want to run the ESLint checker along side the dev server (which might slow down the dev server) to ensure issues are raised no matter the environment. You can enable it by setting `checker` to `true` in the `eslint` module options.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: [
    '@nuxt/eslint'
  ],
  eslint: {
    checker: true // <---
  }
})
```

You will need to install extra dependencies `vite-plugin-eslint2` for Vite, or `eslint-webpack-plugin` if you are using the [Webpack builder](https://nuxt.com/docs/getting-started/configuration#with-webpack).

```bash
# For Vite
npm i -D vite-plugin-eslint2

# For Webpack
npm i -D eslint-webpack-plugin
```

This enables a similar experience to using [`@nuxtjs/eslint-module`](https://github.com/nuxt-modules/eslint).

The checker runs in flat config mode by default. If you want to run it in legacy mode, you will need to set `configType` to `eslintrc`

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: [
    '@nuxt/eslint'
  ],
  eslint: {
    checker: {
      configType: 'eslintrc' // <--- (consider migrating to flat config if possible)
    }
  }
})
```

### Custom Config Presets

By default, this module installs the JS, TS and Vue plugins with their recommended rules. This might already be covered by your config presets, so in that case you can disable the default setup by setting the `standalone` option to `false`.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: [
    '@nuxt/eslint'
  ],
  eslint: {
    config: {
      standalone: false // <---
    }
  }
})
```

This ensures the module only generates Nuxt-specific rules so that you can merge it with your own config presets.

For example, with [`@antfu/eslint-config`](https://github.com/antfu/eslint-config):

```js [eslint.config.mjs]
// @ts-check
import antfu from '@antfu/eslint-config'
import withNuxt from './.nuxt/eslint.config.mjs'

export default withNuxt(
  antfu({
    // ...@antfu/eslint-config options
  }),
  // ...your other rules
)
```

### Auto-Init

Upon server start, the module will look for an `eslint.config.*` file and generate one if it doesn't exist for easier usage. You can opt-out this be setting `autoInit` to `false` in the `eslint.config` module options.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: [
    '@nuxt/eslint'
  ],
  eslint: {
    config: {
      autoInit: false // <--- disable auto-init
    }
  }
})
```
