# @bitfactory/eslint-config

[![Release](https://img.shields.io/badge/Release-14.x.x-ED4934)](https://www.npmjs.com/package/@bitfactory/eslint-config)
[![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](https://lbesson.mit-license.org/)
[![ESLint](https://img.shields.io/badge/ESLint-^9.38%20%7C%7C%20^10-4B3263?logo=eslint&logoColor=white)](https://eslint.org/)
[![NodeJS](https://img.shields.io/badge/Node.js-^22.22.2%20%7C%7C%20^24.15.0-6da55f?logo=node.js)](https://nodejs.org/)
[![NPM package version](https://badgen.net/npm/v/@bitfactory/eslint-config)](https://npmjs.com/package/@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](https://unpkg.com/@bitfactory/eslint-config@14/docs/migration-v14.md),
> 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](https://unpkg.com/@bitfactory/eslint-config@14/docs/01-installation.md) lists every break
> in order, with a migration guide for each that has one.

<!-- Separates adjacent alerts; without it markdownlint reports MD028. -->

> [!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](https://unpkg.com/@bitfactory/eslint-config@14/docs/known-issue-import-namespace.md)
> for the remedies.

<!-- Separates adjacent alerts; without it markdownlint reports MD028. -->

> [!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](https://unpkg.com/@bitfactory/eslint-config@14/docs/known-issue-eslint-js-peer.md)
> for the one-line remedy.

- [@bitfactory/eslint-config](#bitfactoryeslint-config)
  - [Quick Start](#quick-start)
  - [Contributing](#contributing)
  - [Installation](#installation)
  - [Configuration](#configuration)
  - [Vue 3 and Nuxt](#vue-3-and-nuxt)
  - [JSON](#json)
  - [Tailwind CSS](#tailwind-css)
  - [CLI Usage](#cli-usage)
  - [Editor Integration](#editor-integration)

## Quick Start

For a quick start guide with basic installation and configuration, see [QUICKSTART.md](https://unpkg.com/@bitfactory/eslint-config@14/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](https://unpkg.com/@bitfactory/eslint-config@14/docs/01-installation.md).

## 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](https://eslint.org/version-support) and the
[Node.js release schedule](https://github.com/nodejs/release#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](https://unpkg.com/@bitfactory/eslint-config@14/docs/02-configuration.md).

## Vue 3 and Nuxt

For the opt-in `/vue3` and `/nuxt` entrypoints, including usage recipes and peer requirements, see [Vue 3 and Nuxt Guide](https://unpkg.com/@bitfactory/eslint-config@14/docs/05-vue-and-nuxt.md).

## 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:

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

```js
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](https://github.com/DavidAnson/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.

```js
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:

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

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

```js
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`:

```js
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:

```js
{
    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](https://unpkg.com/@bitfactory/eslint-config@14/docs/03-cli-usage.md).

## Editor Integration

For editor integration instructions (Visual Studio Code, PhpStorm), see [Editor Integration Guide](https://unpkg.com/@bitfactory/eslint-config@14/docs/04-editor-integration.md).