aboutbits · lukasvice · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026
diff --git a/readme.md b/readme.md
@@ -1,187 +1,227 @@
 # @aboutbits/eslint-config
 
-[![npm package](https://badge.fury.io/js/%40aboutbits%2Feslint-config.svg)](https://badge.fury.io/js/%40aboutbits%2Feslint-config)
-[![license](https://img.shields.io/github/license/aboutbits/eslint-config)](https://github.com/aboutbits/eslint-config/blob/main/license.md)
+AboutBits' [ESLint](https://eslint.org/) config presets.
 
-AboutBit's [ESLint](https://eslint.org/) config presets
+This package targets **ESLint 9 (flat config)** and ships a set of composable presets for our TypeScript, React, Next.js, Tailwind CSS and related projects. All plugins are bundled as direct dependencies, so you only need to install ESLint itself and a few peer tools.
 
 ## Table of content
 
-- [Usage](#usage)
-  - [TypeScript](#typescript)
-  - [TypeScript + React](#typescript--react)
-  - [TypeScript + Next.js](#typescript--nextjs)
-  - [FormatJS](#formatjs)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Configuration](#configuration)
+  - [Presets](#presets)
+  - [Basic setup](#basic-setup)
   - [Combining presets](#combining-presets)
-  - [Overriding Rules](#overriding-rules)
+  - [Ignoring files](#ignoring-files)
+  - [Overriding rules](#overriding-rules)
+- [Scripts](#scripts)
+- [Preset-specific notes](#preset-specific-notes)
+  - [Prettier](#prettier)
+  - [Tailwind CSS](#tailwind-css)
+  - [Next.js](#nextjs)
+  - [Storybook](#storybook)
+  - [FormatJS](#formatjs)
 - [Build & Publish](#build--publish)
-- [About](#about)
+- [Information](#information)
+
+## Requirements
 
-## Usage
+- **ESLint** `^9` (flat config, i.e. an `eslint.config.js` file)
 
-Install the package:
+## Installation
+
+Install the config together with its required peer dependencies:
 
 ```sh
-npm i -D @aboutbits/eslint-config
+npm i -D @aboutbits/eslint-config eslint prettier typescript
 ```
 
-We recommend linting by running `eslint` without `--ext` option. What files are to be linted should be specified inside the ESLint config and the TypeScript config.
-All files included (or not ignored) by the ESLint config (`.eslintrc.json`) must be included by the TypeScript config (`tsconfig.json`).
-For example, if this is your `.eslintrc.json`:
+Unlike the previous (ESLint 8) version, you no longer need to install `@typescript-eslint/*`, `eslint-plugin-import`, `eslint-plugin-react` and the rest by hand — they are bundled with this package.
 
-```jsonc
-{
-  // ...remaining config
-  "ignorePatterns": ["node_modules", "dist"]
-}
-```
+Some presets rely on additional peer dependencies that you install only when you use them:
 
-You may include the following files inside your `tsconfig.json`:
+| Preset      | Additional peer dependency                          |
+| ----------- | --------------------------------------------------- |
+| `next`      | `@next/eslint-plugin-next` (`^14 \|\| ^15 \|\| ^16`) |
+| `storybook` | `eslint-plugin-storybook` (`^10`)                   |
 
-```jsonc
-{
-  // ...remaining config
-  "exclude": ["node_modules", "dist"],
-  "include": ["**/*.ts", "**/*.tsx"]
-}
-```
+We also recommend using our shared Prettier config — see [Prettier](#prettier).
 
-Should you have files that you want to be linted, but not inside your `tsconfig.json`, you can create a `tsconfig.eslint.json` file.
-Then change `.eslintrc.json` to be:
+## Configuration
 
-```jsonc
-{
-  // ...omitted
-  "parserOptions": {
-    "project": "./tsconfig.eslint.json"
-  }
-  // ...omitted
-}
-```
+### Presets
 
-### TypeScript
+Start from the base preset and add optional presets as needed. Each preset is imported from `@aboutbits/eslint-config/configs/<name>`.
 
-Install the required packages, assuming that you have TypeScript already installed:
+**Base**
 
-```sh
-npm i -D eslint prettier @typescript-eslint/eslint-plugin eslint-plugin-prettier eslint-plugin-import eslint-plugin-unused-imports@^3
-```
+- **`configs/ts`** — Base configuration for all TypeScript projects. Enables type-aware linting, import ordering, `unused-imports`, Prettier integration and JSON/JSONC linting.
 
-`.eslintrc.json`
+**Optional**
 
-```json
-{
-  "extends": "@aboutbits/eslint-config/ts",
-  "parserOptions": {
-    "project": true
-  }
-}
+- **`configs/react`** — Rules for React projects (React, React Hooks, JSX a11y).
+- **`configs/next`** — Rules for Next.js projects (Core Web Vitals).
+- **`configs/tailwind`** — Rules for Tailwind CSS (via `eslint-plugin-better-tailwindcss`).
+- **`configs/formatjs`** — Rules for FormatJS / `react-intl` usage and translation files.
+- **`configs/jest`** — Rules for Jest tests.
+- **`configs/storybook`** — Rules for Storybook stories and `.mdx` docs.
+
+### Basic setup
+
+Create an `eslint.config.js` file in the root of your project:
+
+```js
+import ts from '@aboutbits/eslint-config/configs/ts'
+
+export default [...ts]
 ```
 
-### TypeScript + React
+> Each preset is an array of flat-config objects, so spread it with `...`.
+> Type-aware linting is enabled automatically (via the TypeScript project service) — you do **not** need to set `parserOptions.project`.
+
+### Combining presets
 
-Install the required packages, assuming that you have TypeScript already installed:
+Add optional presets after the base preset. A typical Next.js + Tailwind project looks like this:
 
-```sh
-npm i -D eslint prettier @typescript-eslint/eslint-plugin eslint-plugin-prettier eslint-plugin-import eslint-plugin-unused-imports@^3 eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-jsx-a11y eslint-plugin-better-tailwindcss
+```js
+import ts from '@aboutbits/eslint-config/configs/ts'
+import react from '@aboutbits/eslint-config/configs/react'
+import next from '@aboutbits/eslint-config/configs/next'
+import tailwind from '@aboutbits/eslint-config/configs/tailwind'
+import formatjs from '@aboutbits/eslint-config/configs/formatjs'
+
+export default [...ts, ...react, ...next, ...tailwind, ...formatjs]
 ```
 
-`.eslintrc.json`
+### Ignoring files
 
-```json
-{
-  "extends": "@aboutbits/eslint-config/ts-react",
-  "parserOptions": {
-    "project": true
-  }
-}
+Add an object with an `ignores` key. Note that in flat config an object containing **only** `ignores` applies globally:
+
+```js
+import ts from '@aboutbits/eslint-config/configs/ts'
+
+export default [...ts, { ignores: ['node_modules', 'dist', '.next'] }]
 ```
 
-### TypeScript + Next.js
+### Overriding rules
 
-Install the required packages, assuming that you have TypeScript already installed:
+Append your own flat-config object after the presets:
 
-```sh
-npm i -D eslint prettier @typescript-eslint/eslint-plugin eslint-plugin-prettier eslint-plugin-import eslint-plugin-unused-imports@^3 eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-jsx-a11y eslint-plugin-better-tailwindcss @next/eslint-plugin-next
+```js
+import ts from '@aboutbits/eslint-config/configs/ts'
+
+export default [
+  ...ts,
+  {
+    files: ['**/*.{js,mjs,cjs,jsx}'],
+    rules: {
+      // your overrides...
+      'no-console': 'off',
+    },
+  },
+]
 ```
 
-`.eslintrc.json`
+## Scripts
+
+Add the following scripts to your `package.json`:
 
 ```json
 {
-  "extends": "@aboutbits/eslint-config/ts-next",
-  "parserOptions": {
-    "project": true
+  "scripts": {
+    "lint": "eslint --cache .",
+    "lint:fix": "npm run lint -- --fix"
   }
 }
 ```
 
-### FormatJS
-
-Install the required packages, assuming that you have TypeScript already installed:
+Then run:
 
 ```sh
-npm i -D eslint eslint-plugin-formatjs
+npm run lint      # Check for issues
+npm run lint:fix  # Fix issues automatically
 ```
 
-`.eslintrc.json`
+## Preset-specific notes
+
+### Prettier
+
+The `ts` preset integrates Prettier through `eslint-plugin-prettier`, so formatting problems are reported (and auto-fixed) by ESLint. You still need a Prettier configuration. We recommend our shared config:
+
+```sh
+npm i -D @aboutbits/prettier-config
+```
 
 ```json
 {
-  "extends": "@aboutbits/eslint-config/formatjs",
-  "parserOptions": {
-    "project": true
-  }
+  "prettier": "@aboutbits/prettier-config"
 }
 ```
 
-### Combining presets
+### Tailwind CSS
 
-Most presets are mutually exclusive, which means that you should not combine them.
-However, you may combine the preset `formatjs` with any other preset you like.
-The following shows how to combine it with the preset `ts-next`:
+The `tailwind` preset is preconfigured to recognise classes in `className` props as well as `classNames`/`*ClassName(s)` helpers. It supports both Tailwind 3 and 4, but you must tell the plugin where your Tailwind setup lives.
 
-Install the required packages, assuming that you have TypeScript already installed:
+**Tailwind 4** — point to your CSS entry point:
 
-```sh
-npm i -D eslint prettier @typescript-eslint/eslint-plugin eslint-plugin-prettier eslint-plugin-import eslint-plugin-unused-imports@^3 eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-jsx-a11y eslint-plugin-better-tailwindcss @next/eslint-plugin-next eslint-plugin-formatjs
+```js
+import tailwind from '@aboutbits/eslint-config/configs/tailwind'
+
+export default [
+  ...tailwind,
+  {
+    settings: {
+      'better-tailwindcss': {
+        entryPoint: 'src/app.css',
+      },
+    },
+  },
+]
 ```
 
-`.eslintrc.json`
+**Tailwind 3** — point to your config file:
 
-```json
-{
-  "extends": [
-    "@aboutbits/eslint-config/ts-next",
-    "@aboutbits/eslint-config/formatjs"
-  ],
-  "parserOptions": {
-    "project": true
-  }
-}
+```js
+import tailwind from '@aboutbits/eslint-config/configs/tailwind'
+
+export default [
+  ...tailwind,
+  {
+    settings: {
+      'better-tailwindcss': {
+        tailwindConfig: 'tailwind.config.js',
+      },
+    },
+  },
+]
 ```
 
-### Overriding rules
+### Next.js
 
-`.eslintrc.json`
+Install `@next/eslint-plugin-next` as a dev dependency, matching your installed Next.js version:
 
-```jsonc
-{
-  "extends": "@aboutbits/eslint-config/ts",
-  "parserOptions": {
-    "project": true
-  },
-  "rules": {
-    // your rules...
-  }
-}
+```sh
+npm i -D @next/eslint-plugin-next
 ```
 
+### Storybook
+
+Install `eslint-plugin-storybook` as a dev dependency, matching your installed Storybook version:
+
+```sh
+npm i -D eslint-plugin-storybook
+```
+
+### FormatJS
+
+The `formatjs` preset enforces our message conventions and additionally sorts the keys of translation files under any `translations/` directory (`**/translations/*.json`).
+
 ## Build & Publish
 
 To build and publish the package, visit the GitHub Actions page of the repository.
 
 You can choose between two workflows:
+
 - `Release Package` to publish a new version of the package.
 - `Pre-Release Package` to publish a new pre-release version of the package.