How to use Nuxt + Eslint in a monorepo?

[BenJackGill]

I have a monorepo that looks like this:

monorepo_root/
├─ apps/
│  ├─ api/
│  ├─ nuxt-web-app/
│  ├─ another-nuxt-web-app/
├─ packages/
│  ├─ internal-package/
│  ├─ another-internal-package/

I want to have one eslint.config.mjs file at my monorepo root which handles the entire codebase. This type of Eslint setup was discussed here on the Eslint repo as the best solution for Eslint in a monorepo. But I also want to use the Nuxt Eslint rules as a base starting point.

How should I go about doing that?

I first tried to use the recommended Nuxt Eslint Module in the monorepo root but I couldn't figure out how to set it up at the monorepo root (outside of a Nuxt app). I think it is designed only to be used inside a nuxt app? Is that correct?

So instead I tried to use @nuxt/eslint-config with @nuxt/eslint-config and eslint packages installed at the monorepo root along with a eslint.config.mjs file at the monorepo root like this:

import { createConfigForNuxt } from "@nuxt/eslint-config/flat";

export default createConfigForNuxt({
  // options here
});

But I am getting this error on layouts/default.vue inside my Nuxt web apps, which I thought would be handled:

Component name "default" should always be multi-word. eslint(vue/multi-word-component-names)

So I think I'm still doing something wrong.

Can you please give some guidance on the correct way to use Nuxt + Eslint in a monorepo?

[dsvgl]

@BenJackGill We currently do it similar as mentioned here: eslint/eslint#16960 (comment)

We use pnpm workspaces and have a separate "package" that defines basic presets, plugins and custom rules.

We export two config arrays.

One is just an array of presets etc that is used with the special withNuxt function inside eslint.config.js when inside a nuxt app – this eg. makes ESLint not complaining about multi-word name for layout and pages files.

The other export uses createConfigForNuxt from @nuxt/eslint-config/flat directly where the export happens. This config can then be used inside eslint.config.js of packages that are not nuxt apps (eg. an utils only package). We basically inherit all the defaults (ts, vue, imports, ...) from @nuxt/eslint-config with this approach. Even though the packages are not nuxt apps it doesn't harm (in our case). Eg. having vue rules but no vue files... ;)

All workspace packages have our linting package installed as a dev dependency. Each package has its own eslint.config.js. Nuxt apps have the ESLint nuxt-module defined in its modules array (nuxt.config.ts), so, nuxt auto-generates the special eslint.config.mjs inside .nuxt dir which exports the mentioned withNuxt function. Other packages (also repo root) just use the "standalone" version.

This works great for us.

---

Here is some code. Hope it helps.

linting package

{
  "name": "@company/lint",
  "version": "3.0.0",
  "private": true,
  "description": "",
  "type": "module",
  "exports": {
    "./eslint": {
      "import": "./src/eslint/index.mjs"
    },
    "./lint-staged": {
      "import": "./src/lint-staged/index.mjs"
    },
    "./stylelint": {
      "import": "./src/stylelint/index.mjs"
    }
  },
  "scripts": {
    "--------------- LINT ---------------": "",
    "lint:js": "eslint --cache .",
    "lint:js:quiet": "pnpm lint:js --quiet",
    "lint:js:fix": "pnpm lint:js --fix",
    "lint": "pnpm lint:js",
    "lint:quiet": "pnpm lint:js:quiet",
    "lintfix": "pnpm lint:js:fix"
  },
  "dependencies": {
    "@nuxt/eslint": "0.3.12",
    "@unocss/eslint-config": "0.60.2",
    "eslint": "9.2.0",
    "eslint-config-flat-gitignore": "0.1.5",
    "eslint-config-prettier": "9.1.0",
    "eslint-config-turbo": "1.13.3",
    "eslint-import-resolver-custom-alias": "1.3.2",
    "eslint-plugin-prettier": "5.1.3",
    "eslint-plugin-vuejs-accessibility": "2.3.0",
    "prettier": "3.2.5",
    "vite-plugin-eslint2": "4.4.0"
  },
  "devDependencies": {
    "typescript": "5.4.5"
  }
}

packages/lint/src/eslint/index.mjs

// @ts-check

import { createConfigForNuxt } from '@nuxt/eslint-config/flat';
// https://github.com/prettier/eslint-plugin-prettier?tab=readme-ov-file#configuration-new-eslintconfigjs
import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
import pluginUnicorn from 'eslint-plugin-unicorn';

/**
 * company ESLint rules
 *
 * @type {import('eslint').Linter.FlatConfig}
 */
export const companyEslintRules = {
  name: 'company/eslint-rules',
  plugins: {
    /**@type {any} missing types */
    unicorn: pluginUnicorn,
  },
  rules: {
    'vue/attribute-hyphenation': 'off',
    // ...
  },
};

/**
 * company dirs and files to ignore
 *
 * @type {import('eslint').Linter.FlatConfig}
 */
export const companyIgnores = {
  // NOTE: no "name" else, it wouldn't work; maybe a bug in ESLint
  ignores: ['**/node_modules', '**/public', '**/vendor', '**/dist', '**/.nuxt'],
};

/**
 * For usage within a Nuxt context
 *
 * The helper `withNuxt()` from auto-generated `.nuxt/eslint.config.mjs` can be used to append
 * these rules after the config tailored to the Nuxt-app where the eslint config is being used.
 * @see https://eslint.nuxt.com/packages/module
 *
 * It will also add all best-practices rules for js/ts/vue from `@nuxt/eslint-config`.
 * @see https://eslint.nuxt.com/packages/config
 */
export const companyEslintConfigNuxt = [eslintPluginPrettierRecommended, companyEslintRules, companyIgnores];

/**
 * For standalone usage in packages without Nuxt context.
 *
 * `createConfigForNuxt()` will create all best-practices rules for js/ts/vue from `@nuxt/eslint-config`.
 * @see https://eslint.nuxt.com/packages/config
 *
 * The activated `tooling` feature enables rules with unicorn and jsdoc.
 * @see https://eslint.nuxt.com/packages/config#module-authors
 */
export const companyEslintConfigStandalone = createConfigForNuxt({ features: { tooling: true } }).append(
  eslintPluginPrettierRecommended,
  companyEslintRules,
  companyIgnores,
);

packages/utils/eslint.config.js

import { companyEslintConfigStandalone } from '@company/lint/eslint';

export default companyEslintConfigStandalone;

apps/my-nuxt-app/eslint.config.js

import { companyEslintConfigNuxt } from '@company/lint/eslint';
import withNuxt from './.nuxt/eslint.config.mjs';

export default withNuxt(companyEslintConfigNuxt);

[dsvgl]

This is "only" a TS is yelling problem? Or does actual linting doesn't work? Plugin works perfectly fine for me in nuxt apps and standalone packages.
TS only complains about not being able to find a declaration file for the import (red squiggly line). Which is correct since eslint-plugin-perfectionist doesn't bundle types. But I don't have an error inside the append part you described.

One thing I noticed is that you have all your deps in devDependencies. I think they should be in dependencies instead (except typescript) since you install your linting package into other packages in your monorepo.
This is probably not the cause of your TS error since your index.js file is in this very package so all deps are present.

[BenJackGill]

Yes you are correct. That plugin does not bundle types. This I found an issue for it: azat-io/eslint-plugin-perfectionist#139

I am just adding // @ts-ignore above that line until it's fixed.

Thank you for all the help. Everything is working great now.

Although I have one last question about this line:

// NOTE: no "name" else, it wouldn't work; maybe a bug in ESLint

I'm not sure what this means. Can you elaborate?

I have noticed that the custom "ignores" object must be seperate from the custom "rules" object. Because even though the Linter.FlatConfig type would allows for them to be in one object, the ignores will not be applied unless they are seperate objects. Is this related to your comment?

[dsvgl]

I have noticed that the custom "ignores" object must be seperate from the custom "rules" object. Because even though the Linter.FlatConfig type would allows for them to be in one object, the ignores will not be applied unless they are seperate objects. Is this related to your comment?

No, not exactly. This is about that every Flat config now could have an optional name property. Like an identifier:

export const companyIgnores = {
  name: 'company/eslint-ignores', // <----- this
  ignores: ['**/node_modules', '**/public', '**/vendor', '**/dist', '**/.nuxt', 'apps/_/**'],
};

I just tried again and now it seems to work. Files inside ignored dirs previously were (wrongly) linted when that config had a name.
Maybe one of the updates to this module/lib fixed this.

-> normally, ESLint would complain here (based on our rules) that const is declared but never used and missing space between = and 1.

[RodrigoCarvalhoCode]

@BenJackGill you said "From initial testing I can confirm it does work having one standalone config in the monorepo root, and then just adding a nuxt config in each nuxt app."

Can you give an example? I'm trying to figure it out still on my own but I'm finding it difficult. Like how you call the linting in the app that uses the linting package?

[BenJackGill]

@BenJackGill you said "From initial testing I can confirm it does work having one standalone config in the monorepo root, and then just adding a nuxt config in each nuxt app."

Can you give an example? I'm trying to figure it out still on my own but I'm finding it difficult. Like how you call the linting in the app that uses the linting package?

I have an internal monorepo package called @myrepo/lint that holds all my configs. It has an index.mjs file for all the configs that currently looks like this:

// @ts-check

// Adapated version of this setup: https://github.com/nuxt/eslint/discussions/420#discussioncomment-9564390

// @ts-ignore
import { FlatCompat } from "@eslint/eslintrc"; // https://eslint.org/docs/latest/use/configure/migration-guide#using-eslintrc-configs-in-flat-config
import { createConfigForNuxt } from "@nuxt/eslint-config/flat";
import eslintPluginPrettierRecommended from "eslint-plugin-prettier/recommended";
import path from "node:path";
import { fileURLToPath } from "node:url"; // https://github.com/prettier/eslint-plugin-prettier?tab=readme-ov-file#configuration-new-eslintconfigjs
// @ts-ignore
import perfectionistNatural from "eslint-plugin-perfectionist/configs/recommended-natural"; // https://eslint-plugin-perfectionist.azat.io/configs/recommended-natural

// mimic CommonJS variables -- not needed if using CommonJS
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const compat = new FlatCompat({
  baseDirectory: __dirname,
});

/**
 * Custom ESLint rules
 *
 * @type {import('eslint').Linter.FlatConfig}
 */
const customRules = {
  rules: {
    "@typescript-eslint/no-unused-vars": "warn",
    "perfectionist/sort-vue-attributes": [
      "error",
      {
        // Based on: https://eslint.vuejs.org/rules/attributes-order.html
        // Note: I think this matches on attribute strings for everything that comes BEFORE the equal sign (=), if there is one. This makes some things impossible to match.
        // See issue: https://github.com/azat-io/eslint-plugin-perfectionist/issues/112
        // See guide on extended glob matching: https://www.linuxjournal.com/content/bash-extended-globbing
        "custom-groups": {
          /* eslint-disable perfectionist/sort-objects */
          DEFINITION: "@(is|v-is)",
          LIST_RENDERING: "v-for",
          CONDITIONALS: "v-@(if|else-if|else|show|cloak)",
          RENDER_MODIFIERS: "v-@(pre|once)",
          GLOBAL: "@(id|:id)",
          UNIQUE: "@(ref|:ref|key|:key)",
          SLOT: "@(v-slot|slot|#*)",
          TWO_WAY_BINDING: "@(v-model|v-model:*)",
          OTHER_DIRECTIVES: "@(v-!(on|bind|html|text))", // Matches all "v-" directives except v-on, v-bind, v-html, v-text (these are defined separately below, which are lower in the order of operations)
          ATTR_DYNAMIC: "@(v-bind:*|:*)", // For dynamic bindings, like v-bind:prop or :prop.
          // ATTR_STATIC: "", // For normal props, like prop="example". No glob patterns possible since we are matching on everything BEFORE the equal sign (=), if there is one. Therefore we can't differentiate boolean props from static props.
          // ATTR_SHORTHAND_BOOL: "", // For boolean props, like custom-prop. No glob patterns possible since we are matching on everything BEFORE the equal sign (=), if there is one. Therefore we can't differentiate boolean props from static props.
          EVENTS: "@(v-on|@*)",
          CONTENT: "v-@(html|text)",
          /* eslint-enable perfectionist/sort-objects */
        },
        groups: [
          "DEFINITION",
          "LIST_RENDERING",
          "CONDITIONALS",
          "RENDER_MODIFIERS",
          "GLOBAL",
          ["UNIQUE", "SLOT"],
          "TWO_WAY_BINDING",
          "OTHER_DIRECTIVES",
          ["ATTR_DYNAMIC", "unknown"], // 'unknown' is a workaround because perfectionist/sort-vue-attributes cannot match on ATTR_STATIC or ATTR_SHORTHAND_BOOL
          "EVENTS",
          "CONTENT",
        ],
        type: "natural",
      },
    ],
  },
};

/**
 * dirs and files to ignore
 *
 * Note: For this to work it has to be kept seperate from customRules. It cannot be combined with customRules above.
 *
 * @type {import('eslint').Linter.FlatConfig}
 */
export const customIgnores = {
  ignores: [
    "**/node_modules",
    "**/public",
    "**/dist",
    "**/.nuxt",
    "**/primevue-presets",
  ],
};

/**
 * For usage within a Nuxt context
 *
 * The helper `withNuxt()` from auto-generated `.nuxt/eslint.config.mjs` can be used to append
 * these rules after the config tailored to the Nuxt-app where the eslint config is being used.
 * @see https://eslint.nuxt.com/packages/module
 *
 * It will also add all best-practices rules for js/ts/vue from `@nuxt/eslint-config`.
 * @see https://eslint.nuxt.com/packages/config
 */
export const eslintConfigNuxt = [
  perfectionistNatural,
  eslintPluginPrettierRecommended,
  ...compat.extends("eslint-config-turbo"), // mimic ESLintRC-style extends
  customRules,
  customIgnores,
];

export const perfectionistNat = perfectionistNatural;

/**
 * For standalone usage in packages without Nuxt context.
 *
 * The `eslint.config.js` file uses ECMAScript import/export, so if `"type": "module"` is not set in `package.json` then use `eslint.config.mjs` so node.js knows to interpret the file as ECMAScript.
 * @see https://stackoverflow.com/a/57492606/1526396
 *
 * `createConfigForNuxt()` will create all best-practices rules for js/ts/vue from `@nuxt/eslint-config`.
 * @see https://eslint.nuxt.com/packages/config
 *
 * The activated `tooling` feature enables rules with unicorn, regexp and jsdoc.
 * @see https://eslint.nuxt.com/packages/config#module-authors
 *
 * When there are conflicting rules the last matching config always takes precedence.
 * Therefore order of appending rules is important. Anything in .preappend() -> The default Nuxt Eslint rules -> Anything in .append(). With the last .append() taking precedence.
 *
 */
export const eslintConfigStandalone = createConfigForNuxt({
  features: { tooling: true },
}).append(
  // @ts-ignore. // Workaround until this issue fixed: https://github.com/azat-io/eslint-plugin-perfectionist/issues/139
  perfectionistNatural,
  eslintPluginPrettierRecommended,
  ...compat.extends("eslint-config-turbo"), // mimic ESLintRC-style extends
  customRules,
  customIgnores,
);

And then in each Nuxt app I have this eslint.config.js file:

import { eslintConfigNuxt } from "@ myrepo/lint";

import withNuxt from "./.nuxt/eslint.config.mjs";

export default withNuxt(eslintConfigNuxt);

And at the root of my monorepo has this eslint.config.js file:

import { eslintConfigStandalone } from "@myrepo/lint";

export default eslintConfigStandalone;

Hope that helps!