@xwbx/eslint-config

A opinionated ESLint config preset for JavaScript, TypeScript, Vue 2 or Vue 3, and Prettier.

Features

• Format with Prettier.
• Designed to work with TypeScript, Vue 2 and 3 out-of-box.
• Support Astro, JSON(5), YAML, Markdown, ...
• Sort imports, package.json, tsconfig.json...
• ESLint Flat config, compose easily!
• Ignores common files like dist, node_modules, coverage, and files in .gitignore.
• Reasonable defaults, best practices, only one-line of config
• Reasonable strict, but with better code quality.
• Requires ESLint v9.10.0+

Install

npm i -D @xwbx/eslint-config

Require Node.js >= 18.18, and ESLint >= 9.5.0.

Usage

import { xwbx } from "@xwbx/eslint-config";
export default xwbx(
  {
    // TypeScript, Vue, Unocss And Astro are autodetected, you can also explicitly enable them:
    typescript: true,
    vue: true,
    unocss: true,
    astro: true,
    // Disable jsonc yaml and toml support
    jsonc: false,
    yaml: false,
    toml: false,

    // `.eslintignore` is no longer supported in Flat config, use `ignores` instead
    // The `ignores` option in the option (first argument) is specifically treated to always be global ignores
    // And will **extend** the config's default ignores, not override them
    // You can also pass a function to modify the default ignores
    ignores: [
      "**/fixtures",
      // ...globs
    ],
  },
  // From the second arguments they are ESLint Flat Configs
  // you can have multiple configs
  {
    files: ["**/*.ts"],
    rules: {},
  },
);

Unocss

Unocss support is detected automatically by checking if unocssor@unocss/webpackor@unocss/nuxt' is installed in your project. You can also explicitly enable/disable it:

// eslint.config.js
import xwbx from "@xwbx/eslint-config";

export default xwbx({
  unocss: true,
});

Running npx eslint should prompt you to install the required dependencies, otherwise, you can install them manually:

pnpm i -D @unocss/eslint-plugin

Astro

Astro support is detected automatically by checking if astro is installed in your project. You can also explicitly enable/disable it:

// eslint.config.js
import xwbx from "@xwbx/eslint-config";

export default xwbx({
  astro: true,
});

Running npx eslint should prompt you to install the required dependencies, otherwise, you can install them manually:

pnpm i -D astro-eslint-parser eslint-plugin-astro prettier-plugin-astro

Angular

To enable Angular support, you need to explicitly turn it on:

// eslint.config.js
import xwbx from "@xwbx/eslint-config";

export default xwbx({
  angular: true,
});

Running npx eslint should prompt you to install the required dependencies, otherwise, you can install them manually:

pnpm i -D @angular-eslint/eslint-plugin @angular-eslint/eslint-plugin-template @angular-eslint/template-parser

Prettier

Default option is

const prettierOptions = {
  tabWidth: 2,
  useTabs: false,
  trailingComma: "all",
  singleQuote: false,
  semi: true,
  endOfLine: "lf",
};

Override by formatters.prettierOptions

// eslint.config.js
export default xwbx({
  formatters: {
    prettierOptions: {
      semi: false,
    },
  },
});

perfectionist (sorting)

This plugin eslint-plugin-perfectionist allows you to sort object keys, imports, etc, with auto-fix.

The plugin is installed, but only perfectionist/sort-imports, perfectionist/sort-named-exports and perfectionist/sort-named-imports are enabled by default.

It's recommended to opt-in on each file individually using configuration comments.

/* eslint perfectionist/sort-exports: "error" */
export * from "./astro";
export * from "./command";
export * from "./comments";

command

Powered by eslint-plugin-command. It is not a typical rule for linting, but an on-demand micro-codemod tool that triggers by specific comments.

For a few triggers, for example:

• /// to-function - converts an arrow function to a normal function
• /// to-arrow - converts a normal function to an arrow function
• /// to-for-each - converts a for-in/for-of loop to .forEach()
• /// to-for-of - converts a .forEach() to a for-of loop
• /// keep-sorted - sorts an object/array/interface
• ... etc. - refer to the documentation

You can add the trigger comment one line above the code you want to transform, for example (note the triple slash):

/// to-function
const foo = async (msg: string): void => {
  console.log(msg)
}

Will be transformed to this when you hit save with your editor or run eslint . --fix:

async function foo(msg: string): void {
  console.log(msg);
}

The command comments are usually one-off and will be removed along with the transformation.

Plugins Renaming

Since flat config requires us to explicitly provide the plugin names (instead of the mandatory convention from npm package name), we renamed some plugins to make the overall scope more consistent and easier to write.

| New Prefix | Original Prefix | Source Plugin | | ---------- | ---------------------- | ------------------------------------------------------------------------------------------ | | import/* | import-lite/* | eslint-plugin-import-lite | | node/* | n/* | eslint-plugin-n | | yaml/* | yml/* | eslint-plugin-yml | | ts/* | @typescript-eslint/* | @typescript-eslint/eslint-plugin | | style/* | @stylistic/* | @stylistic/eslint-plugin | | test/* | vitest/* | @vitest/eslint-plugin | | test/* | no-only-tests/* | eslint-plugin-no-only-tests |

When you want to override rules, or disable them inline, you need to update to the new prefix:

-// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+// eslint-disable-next-line ts/consistent-type-definitions
type foo = { bar: 2 }

Editor Specific Disables

Auto-fixing for the following rules are disabled when ESLint is running in a code editor:

• prefer-const
• unused-imports/no-unused-imports
• test/no-only-tests
• pnpm/json-enforce-catalog
• pnpm/json-prefer-workspace-settings
• pnpm/json-valid-catalog

Since v0.4.0, they are no longer disabled, but made non-fixable using this helper.

This is to prevent unused imports from getting removed by the editor during refactoring to get a better developer experience. Those rules will be applied when you run ESLint in the terminal or lint-staged. If you don't want this behavior, you can disable them:

// eslint.config.js
import xwbx from "@xwbx/eslint-config";

export default xwbx({
  isInEditor: false,
});

Rules Overrides

Certain rules would only be enabled in specific files, for example, ts/* rules would only be enabled in .ts files and vue/* rules would only be enabled in .vue files. If you want to override the rules, you need to specify the file extension:

// eslint.config.js
import xwbx from "@xwbx/eslint-config";

export default xwbx(
  {
    vue: true,
    typescript: true,
  },
  {
    // Remember to specify the file glob here, otherwise it might cause the vue plugin to handle non-vue files
    files: ["**/*.vue"],
    rules: {
      "vue/operator-linebreak": ["error", "before"],
    },
  },
  {
    // Without `files`, they are general rules for all files
    rules: {
      "style/semi": ["error", "never"],
    },
  },
);

We also provided the overrides options in each integration to make it easier:

// eslint.config.js
import xwbx from "@xwbx/eslint-config";

export default xwbx({
  vue: {
    overrides: {
      "vue/operator-linebreak": ["error", "before"],
    },
  },
  typescript: {
    overrides: {
      "ts/consistent-type-definitions": ["error", "interface"],
    },
  },
  yaml: {
    overrides: {
      // ...
    },
  },
});

Vue

Vue support is detected automatically by checking if vue is installed in your project. You can also explicitly enable/disable it:

// eslint.config.js
import xwbx from "@xwbx/eslint-config";

export default xwbx({
  vue: true,
});

Vue 2

We have limited support for Vue 2 (as it's already reached EOL). If you are still using Vue 2, you can configure it manually by setting vueVersion to 2:

// eslint.config.js
import xwbx from "@xwbx/eslint-config";

export default xwbx({
  vue: {
    vueVersion: 2,
  },
});

As it's in maintenance mode, we only accept bug fixes for Vue 2. It might also be removed in the future when eslint-plugin-vue drops support for Vue 2. We recommend upgrading to Vue 3 if possible.

Vue Accessibility

To enable Vue accessibility support, you need to explicitly turn it on:

// eslint.config.js
import xwbx from "@xwbx/eslint-config";

export default xwbx({
  vue: {
    a11y: true,
  },
});

Running npx eslint should prompt you to install the required dependencies, otherwise, you can install them manually:

npm i -D eslint-plugin-vuejs-accessibility

VSCode

Enable flat config if you are using ESLint < 9.

{
  // Disable the default formatter, use eslint instead
  "prettier.enable": false,
  "eslint.experimental.useFlatConfig": true,
  "eslint.useFlatConfig": true,
  // Auto fix
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit",
    "source.organizeImports": "never",
  },
  // Enable eslint for all supported languages
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact",
    "vue",
    "html",
    "markdown",
    "json",
    "jsonc",
    "yaml",
    "toml",
    "xml",
    "svg",
    "gql",
    "graphql",
    "astro",
    "css",
    "less",
    "scss",
    "pcss",
    "postcss",
  ],
}

Zed

Add the following settings to your .zed/settings.json:

{
  "format_on_save": "on",
  "formatter": [
    // Use ESLint's --fix:
    { "code_action": "source.fixAll.eslint" },
  ],
  // Enable eslint for all supported languages
  // Defaults only include https://github.com/search?q=repo%3Azed-industries%2Fzed%20eslint_languages&type=code
  "languages": {
    "HTML": {
      "language_servers": ["...", "eslint"],
    },
    "Markdown": {
      "language_servers": ["...", "eslint"],
    },
    "JSON": {
      "language_servers": ["...", "eslint"],
    },
    "JSONC": {
      "language_servers": ["...", "eslint"],
    },
    "YAML": {
      "language_servers": ["...", "eslint"],
    },
    "CSS": {
      "language_servers": ["...", "eslint"],
    },
    // Add other languages as needed
  },
  "lsp": {
    "eslint": {
      "settings": {
        // Remove after https://github.com/zed-industries/zed/issues/49387
        "experimental": {
          "useFlatConfig": false,
        },

        // Silent the stylistic rules in your IDE, but still auto fix them
        "rulesCustomizations": [
          { "rule": "style/*", "severity": "off", "fixable": true },
          { "rule": "format/*", "severity": "off", "fixable": true },
          { "rule": "*-indent", "severity": "off", "fixable": true },
          { "rule": "*-spacing", "severity": "off", "fixable": true },
          { "rule": "*-spaces", "severity": "off", "fixable": true },
          { "rule": "*-order", "severity": "off", "fixable": true },
          { "rule": "*-dangle", "severity": "off", "fixable": true },
          { "rule": "*-newline", "severity": "off", "fixable": true },
          { "rule": "*quotes", "severity": "off", "fixable": true },
          { "rule": "*semi", "severity": "off", "fixable": true },
        ],
      },
    },
  },
}

Credits

This setup is heavily inspired on a few projects:

• @antfu/eslint-config
• @sxzz/eslint-config