@bitfactory/eslint-config

@bitfactory/eslint-config

Shareable ESLint config for ESLint v9+ Flat Config (ESM). All rules and configurations are pre-configured. Rules can be overridden as needed.

[!IMPORTANT] This package is flat-config only (ESM) and requires ESLint ^9.38.0 || ^10.0.0. Upgrading from an older major? Start with the 14.0.0 Migration Guide, which is organised by project shape: which entrypoints your stack takes, which ignores go with it, and how to adopt the rule changes in stages. The Installation Guide lists every break in order, with a migration guide for each that has one.

[!WARNING] This config owns the import-x namespace, so the run can abort if your project registers a second eslint-plugin-import-x copy that does not dedupe with this one, for files both registrations cover. See Known issue: import plugin namespace collision for the remedies.

[!WARNING] On ESLint 9, pin @eslint/js to 9.38.0 or a newer 9.x. Left to resolve by range it selects an ESLint 10 build whose own peer excludes ESLint 9, and the install fails. See Known issue: @eslint/js resolves to an ESLint 10 build on ESLint 9 for the one-line remedy.

• @bitfactory/eslint-config
  • Quick Start
  • Contributing
  • Installation
  • Configuration
  • Vue 3 and Nuxt
  • JSON
  • Tailwind CSS
  • CLI Usage
  • Editor Integration

Quick Start

For a quick start guide with basic installation and configuration, see QUICKSTART.md.

Contributing

For information about contributing to this project, including publishing guidelines, local development setup, and debugging tips, see CONTRIBUTING.md in the repository. It is not published to npm.

Installation

For detailed installation instructions including peer dependencies and Vue/TypeScript setup, see Installation Guide.

Version support

The major line latest points at is the supported one, and every patch on it stays installable. A line is retired - deprecated as a whole, with no backports from then on - when its successor major publishes. What brings that major about is usually an end of life upstream: the oldest ESLint major the line's peer range admits, or the oldest Node line its engines.node declares, going out of support; see ESLint's version support and the Node.js release schedule for those dates.

An individual version is deprecated only when it is defective, and its message names the first version without the defect. npm view @bitfactory/eslint-config@<version> deprecated shows any version's message.

Configuration

For configuration examples (Vue, TypeScript) and advanced configuration options (custom plugins, ECMAScript version overrides), see Configuration Guide.

Vue 3 and Nuxt

For the opt-in /vue3 and /nuxt entrypoints, including usage recipes and peer requirements, see Vue 3 and Nuxt Guide.

JSON

Opt-in entrypoint for linting JSON files, built on eslint-plugin-jsonc and eslint-plugin-package-json. It is additive and not enabled by the base config:

pnpm add -D eslint-plugin-jsonc eslint-plugin-package-json

import bitfactory from '@bitfactory/eslint-config';
import json from '@bitfactory/eslint-config/json';

export default [
    ...bitfactory,
    ...json,
];

The /json entrypoint lints .json, .json5, and .jsonc files, sorting keys and enforcing a two-space indent. Array values are sorted only in tsconfig*.json and jsconfig.json, and only the arrays there that are sets. Comments belong to the .jsonc and .json5 grammars, and are allowed in tsconfig*.json, jsconfig.json, and .vscode/*.json as well.

package.json is ordered instead by eslint-plugin-package-json, so a repository running sort-package-json as a separate step can drop it. It also checks that whichever fields the manifest declares are well formed, and that no dependency is declared twice.

Markdown is not linted here. Use markdownlint directly: it covers roughly fifty rules where the entrypoint this replaces covered seventeen, nine of them duplicating markdownlint already.

Published packages

/package-json is /json plus the requirement that a published package actually declares those fields - attribution (author or contributors), exports, engines, keywords, and the rest - and that no dependency resolves to a local path. Use it in place of /json when the project is published to a registry. An application keeps /json, which never requires a field it has no reason to declare.

import bitfactory from '@bitfactory/eslint-config';
import packageJson from '@bitfactory/eslint-config/package-json';

export default [
    ...bitfactory,
    ...packageJson,
];

Tailwind CSS

Opt-in entrypoint for linting Tailwind CSS class usage, built on eslint-plugin-tailwindcss. It is additive and not enabled by the base config, and it supports both Tailwind majors. Both exports bring the parser their globs need beyond ESLint's default, so both import @typescript-eslint/parser, and /tailwind-vue also imports vue-eslint-parser. Install the plugin version matching your Tailwind major, plus whichever parsers your project does not already have; your project's existing tailwindcss install provides the rest:

# Tailwind 4
pnpm add -D eslint-plugin-tailwindcss@4

# Tailwind 3
pnpm add -D eslint-plugin-tailwindcss@3

import bitfactory from '@bitfactory/eslint-config';
import tailwind from '@bitfactory/eslint-config/tailwind';

export default [
    ...bitfactory,
    ...tailwind,
];

The plugin supplies no parser of its own, so an entrypoint that claims .vue has to bring one. A Vue project's class names live in templates, so /tailwind-vue carries the same rules for .vue and supplies vue-eslint-parser:

import bitfactoryVue3 from '@bitfactory/eslint-config/vue3';
import tailwind from '@bitfactory/eslint-config/tailwind';
import tailwindVue from '@bitfactory/eslint-config/tailwind-vue';

export default [
    ...bitfactoryVue3,
    ...tailwind,
    ...tailwindVue,
];

The plugin needs your project's own Tailwind entry point, which no shared configuration can supply, and each major reads a different key for it. Plugin v4 takes a stylesheet from cssConfigPath, defaulting to src/style.css, and aborts the whole run with ENOENT when that file is missing:

{
    settings: {
        tailwindcss: {
            cssConfigPath: 'resources/css/app.css',
        },
    },
},

Plugin v3 has no cssConfigPath. It reads config, which names your tailwind.config.js rather than a stylesheet, and when it cannot load that file it falls back to Tailwind's default theme without warning, so class names are judged against a theme that is not yours.

Both entrypoints enable tailwindcss/classnames-order at warn, and it is auto-fixable, so the editor setup in the integration guide sorts on save. It reaches only the extensions each entrypoint claims - .js, .jsx, .ts, .tsx and .vue - so a formatter plugin still covers .mjs, .cjs, .mts and .cts. Set the entry point above before removing the other plugin.

Both apply no house rule set of their own: each carries the Tailwind plugin's rules for the files it names, and each parses those files, so each works alone. Both need the entry point set above. The entrypoints adapt to whichever plugin major is installed (v3's flat/recommended array or v4's recommended config).

CLI Usage

For CLI usage instructions and command examples, see CLI Usage Guide.

Editor Integration

For editor integration instructions (Visual Studio Code, PhpStorm), see Editor Integration Guide.