skip to content

In ESLint 10's flat config, how do you consume a plugin's preset and an in-house shareable config package such as `@crewdeck/eslint-config`?

level: middleimportance: should knowfreq 20%

answer

  1. presets are plain objects or arrays
  2. extends inside defineConfig()
  3. a string needs plugins in that object
  4. each plugin picks its own export path
  5. shareable config is an installed dependency

basics

~20 s

Presets are config objects or arrays. Reference a plugin's preset by string, such as js/recommended, after registering the plugin in the same object, or insert the exported object; a shareable config is an installed package you import and extend.

solid answer

~40 s

In flat config a preset is just a configuration object or array, so you add it to the config. With `defineConfig()` from `eslint/config` (exported since ESLint 9.22.0), an object's `extends` array takes three kinds of entry: a string `"namespace/configName"` such as `"js/recommended"`, which resolves only if that same object's `plugins` registers the namespace; a config object; or a config array. Plugins expose presets in their own shapes, such as `js.configs.recommended`, `reactHooks.configs.flat.recommended` or `jsxA11y.flatConfigs.recommended`, so you follow each README. A shareable config like `@crewdeck/eslint-config` is an npm package, installed as a dependency, that exports an object or array; you import it and put it in `extends` or straight into the array. Through `extends`, a preset is limited to the object's `files` and placed before that object's own settings.

code

javascript · 20 lines
javascript
// @crewdeck/eslint-config - index.js
import js from "@eslint/js";
import reactHooks from "eslint-plugin-react-hooks";
import jsxA11y from "eslint-plugin-jsx-a11y";
import crewPlugin from "./plugin.js";
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    name: "crewdeck/base",
    files: ["**/*.{js,jsx}"],
    plugins: { js, crew: crewPlugin },
    extends: [
      "js/recommended",                    // string: needs `js` in plugins above
      reactHooks.configs.flat.recommended, // object: this plugin's own path
      jsxA11y.flatConfigs.recommended,     // object: a different path again
    ],
    rules: { "crew/no-raw-dates": "error" }, // the team's own plugin
  },
]);

go deeper

for a junior

Remember that a preset is just a config object or array: import it and put it into your config, or reference a plugin's preset with a namespace/configName string.

for a middle

Explain the three extends entry types, why a string needs plugins in the same object, and how extends scopes a preset to the object's files and puts it before its own rules.

for a senior

Expect each plugin to expose presets differently and to leave eslintrc presets behind; read the README and the peer range before you add a plugin to a shared config.

for a principal

Treat the shareable config as the one place presets are chosen and ordered, so each app imports a single package instead of repeating plugin paths and their quirks.

## What a preset is in flat config In flat config there is no special preset mechanism. A **preset** is a configuration object, or an array of them, that someone else wrote: ESLint's own `js/recommended`, a plugin's recommended rules, or a team's **shareable config** package. Consuming one means getting that object or array into your exported config array, in the right place. ## Three ways to reference one `defineConfig()`, imported from `eslint/config`, adds an `extends` key to configuration objects. Its entries can be: | Entry in `extends` | Example | Requirement | |---|---|---| | String `"namespace/configName"` | `"js/recommended"` | That same object's `plugins` must register the namespace (`plugins: { js }`). | | Config object | `reactHooks.configs.flat.recommended` | Whatever object the plugin exports. | | Config array | `crewdeck` (a package's default export) | Arrays are flattened in order. | A string is resolved by looking up the namespace in the object's own `plugins`, then the named config in the plugin's `configs`. If `configs.recommended` is still in eslintrc format, `defineConfig()` falls back to a `configs["flat/recommended"]` entry; if neither works it throws `Plugin config "recommended" in plugin "x" is an eslintrc config and cannot be used in this context.` You can also skip `extends` and place a preset object or array directly in the top-level array. The difference matters for scoping, below. ## Plugin presets: each plugin chooses its shape ESLint does not dictate where a plugin keeps its flat presets, and plugins that existed before flat config had to keep their eslintrc presets for older users. The result is a different path per plugin: - `@eslint/js`: `js.configs.recommended` (or the string `"js/recommended"` with `plugins: { js }`). - `eslint-plugin-react-hooks`: `reactHooks.configs.flat.recommended`. - `eslint-plugin-jsx-a11y`: `jsxA11y.flatConfigs.recommended`. Read the plugin's README; guessing a path from another plugin gives `undefined` or an eslintrc object. ## Shareable config packages A **shareable config** is an npm package that exports a config object or array from its main entry point. ESLint recommends naming it `eslint-config-<name>` or, scoped, `@scope/eslint-config` (so `@crewdeck/eslint-config` fits). The consuming app: 1. installs it as a dependency, so the package and the plugins it depends on are present; 2. imports it in `eslint.config.js`; 3. adds it to `extends` or to the top-level array; 4. writes its own settings after it. A package may export extra configs from other files, imported as `@crewdeck/eslint-config/markdown.js`. A shareable config cannot be passed to `eslint --config`; that flag takes a config file path, so you import the package from your own config instead. ## What `extends` adds over a plain array entry 1. **Scoping.** Each extended object is combined with the base object's `files`, so a preset inside `{ files: ["src/**/*.{js,jsx}"], extends: [...] }` applies only there. A preset at the top level, with no `files` of its own, applies to every file ESLint lints. 2. **Order.** The extended configs come first, in list order, and the object's own keys come after them, so its `rules` override the presets. 3. **Names.** Extended objects get names such as `crewdeck/base > js/recommended`, which show up in the config inspector. ## Top-level entry or `extends` Both forms put the same objects into the final array; they differ in what they assume about files: - A preset placed directly in the top-level array keeps whatever `files` it declares itself. Many plugin presets declare none (jsx-a11y's README says its presets set neither `files` nor `globals`), so they reach every file ESLint lints, including Markdown code blocks or JSON once those are added. - A preset in `extends` is combined with the base object's `files`, so `{ files: ["src/**/*.{js,jsx}"], extends: [jsxA11y.flatConfigs.recommended] }` keeps it on React sources. ESLint's documentation recommends always pairing `extends` with `files` for this reason. - A shareable config exported as an array is fine in either place; inside `extends` each of its objects is scoped to the base object's `files`, on top of any `files` it already has. For an app that consumes one team package, the usual shape is a single object with `files`, `extends: [crewdeck]` and the app's own `rules`. ## Errors that point at the reference - `Plugin "js" not found.` - a string in `extends` whose namespace is not registered in that object's `plugins`. - `Plugin config "strict" not found in plugin "crew".` - the plugin has no config by that name. - "This appears to be in eslintrc format rather than flat config format." - an `extends` key in a config exported without `defineConfig()`. ESLint itself treats `extends` as an eslintrc key; only `defineConfig()` expands it.

  • Why can't you run `eslint --config @crewdeck/eslint-config`?
    ESLint's docs state that shareable configs cannot be used with the `--config` flag. The flag names one configuration file to load instead of the usual lookup; a shareable config is a package to import. Create an `eslint.config.js` that imports the package and adds it to the array or to `extends`.
  • A plugin's README still shows only `"extends": ["plugin:x/recommended"]`. What does that tell you?
    That is the eslintrc form, which ESLint 10 no longer reads. Check whether the plugin also exports a flat preset, under `configs.recommended`, `configs["flat/recommended"]` or another documented path, and whether its `peerDependencies` range includes ESLint 10; jsx-a11y 6.10.2, for example, declares `^3 || ... || ^9`.

  • Write plugin:react-hooks/recommended in extends, as in .eslintrc.
  • Every plugin keeps its flat preset at configs.recommended.
  • A string in extends finds the plugin wherever it is registered.
  • Plain exported arrays support extends just like defineConfig().
  • A shareable config can be passed straight to eslint --config.

Assumes ESLint 10 with defineConfig() and extends, exported from eslint/config since 9.22.0; eslintrc extends strings such as plugin:x/recommended stopped working when 10.0.0 removed eslintrc.