Refreshed Nuxt ESLint Integrations · Nuxt Blog

Ecosystem·Apr 10, 2024·10 min read
We revamped our ESLint integrations to support ESLint v9 with the flat config, as well as a new module with many more capabilities.
We revamped our ESLint integrations to support ESLint v9 with the new flat config. Along the way, we have explored many new possibilities to make it more personalized, powerful, and with better developer experience.
You can run the following command to install the new @nuxt/eslint module:
Continue reading the story or learn more with the documentation.
ESLint has become an essential tool for today's web development. It helps you to catch errors and enforce a consistent coding style in your project. At Nuxt, we do our best to provide an out-of-the-box experience for ESLint, making it easy to use, configure and follow the best practices we recommend.
Since, both Nuxt and ESLint have evolved a lot. Historically, we ended up with a few different packages and integrations for ESLint in Nuxt, and it wasn't always obvious which one to use for what purpose. We have received a lot of feedback from our community.
To improve the situation and also make it future-proof, we recently refreshed our ESLint integrations to support ESLint v9 with the flat config. It opens up many more capabilities for customizing your ESLint setup, providing a more straightforward and unified experience.
We moved ESLint-related packages scattered across different repositories into a single monorepo: nuxt/eslint, with a dedicated new documentation site: eslint.nuxt.com.
To help understand the differences between each package and what to use, we also have a FAQ page comparing them and explaining their scopes.
This monorepo now includes:
Before diving into new Nuxt integrations, let me introduce you to the concept of ESLint flat config.
Flat config is a configuration format introduced in ESLint v8.21.0 as experimental, and became the default format in ESLint v9.
A quick reference to differentiate:
This blog post from ESLint explains the motivation behind the flat config system in detail. In short, the legacy eslintrc format was designed in the early time of JavaScript, when ES modules and modern JavaScript features were not yet standardized. Many implicit conventions involved, and the extends feature makes the final config result hard to understand and predict. Which also makes shared configs hard to maintain and debug.
The new flat config moves the plugins and configs resolution from ESLint's internal convention to the native ES module resolution. This in turn makes it more explicit and transparent, allowing you to even import it from other modules. Since the flat config is just a JavaScript module, it also opens the door for much more customization.
In the latest @nuxt/eslint-config package, we leverage the flexibility we have to provide a factory function that allows you to customize the config presets easily in a more high-level way. Here is an example of how you can use it:
@nuxt/eslint-config starts with an unopinionated base config, which means we only include rules for best practices of TypeScript, Vue and Nuxt, and leave the rest like code style, formatting, etc for you to decide. You can also run Prettier alongside for formatting with the defaults.
The config also allows you to opt-in to more opinionated features as needed. For example, if you want ESLint to take care of the formatting as well, you can turn it on by passing features.stylistic to the factory function (powered by ESLint Stylistic):
Or tweak your preferences with an options object (learn more with the options here):
And if you are authoring a Nuxt Module, you can turn on features.tooling to enable the rules for the Nuxt module development:
...and so on. The factory function in flat config allows the presets to cover the complexity of the underlying ESLint configuration, and provide high-level and user-friendly abstractions for end users to customize. All this without requiring users to worry about the internal details.
While this approach offers you a Prettier-like experience with minimal configurations (because it's powered by ESLint), you still get the full flexibility to customize and override fine-grained rules and plugins as needed.
We also made a FlatConfigComposer utility from eslint-flat-config-utils to make it even easier to override and extend the flat config. The factory function in @nuxt/eslint-config/flat returns a FlatConfigComposer instance:
With this approach, we get the best of both worlds: the simplicity and high-level abstraction for easy to use, and the power for customization and fine-tuning.
Taking this even further, we made the new, all-in-one @nuxt/eslint module for Nuxt 3. It leverages Nuxt's context to generate project-aware and type-safe ESLint configurations for your project.
We know that Vue's Style Guide suggests the use of multi-word names for components to avoid conflicts with existing and future HTML elements. Thus, in eslint-plugin-vue, we have the rule vue/multi-word-component-names enabled by default. It's a good practice to follow, but we know that in a Nuxt project, not all .vue files are registered as components. Files like app.vue, pages/index.vue, layouts/default.vue, etc. are not available as components in other Vue files, and the rule will be irrelevant to them.
Usually, we could turn off the rule for those files like:
It should work for the majority of the cases. However, we know that in Nuxt you can customize the path for each directory, and layers allow you to have multiple sources for each directory. This means the linter rules will be less accurate and potentially cause users extra effort to keep them aligned manually.
Similarly, we want to have vue/no-multiple-template-root enabled only for pages and layouts, etc. As the cases grow, it becomes unrealistic to ask users to maintain the rules manually.
That's where the magic of @nuxt/eslint comes in! It leverages Nuxt's context to generate the configurations and rules specific to your project