@forthtilliath/eslint-config 0.8.0 → 0.9.0

package/README.md

@@ -24,10 +24,51 @@ Or, from within this monorepo, as a workspace dependency:
 ```
 
 `eslint` and `typescript` are peer dependencies — install them yourself (any
-recent flat-config-era ESLint 9+/10+, and TypeScript 5+). Every ESLint plugin
-each variant actually uses (`typescript-eslint`, `eslint-plugin-react`,
-`angular-eslint`, etc.) ships as a regular dependency of this package, so
-there's nothing else to install per variant.
+recent flat-config-era ESLint 9+/10+, and TypeScript 5+). Only what the base
+config needs (`typescript-eslint`, `@eslint/js`, `globals`, import sorting,
+Prettier conflict-resolution) ships as a regular dependency: every other
+plugin is an **optional peer dependency**, installed by the project only for
+the variant and options it actually uses. A React Native app doesn't get
+`angular-eslint` (and the Angular CLI it pulls in), nor a TypeScript library
+every React plugin.
+
+| Variant / option        | Also install                                                                                              |
+| ----------------------- | --------------------------------------------------------------------------------------------------------- |
+| `.` (base)              | —                                                                                                         |
+| `/react`                | `@eslint-react/eslint-plugin eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-react-refresh`   |
+| `/react-native`         | the `/react` list + `eslint-plugin-react-native`                                                          |
+| `/nextjs`               | the `/react` list + `@next/eslint-plugin-next`                                                            |
+| `/storybook`            | the `/react` list + `eslint-plugin-storybook`                                                             |
+| `/angular`              | `angular-eslint`                                                                                          |
+| `turbo: true` (default) | `eslint-plugin-turbo` — or pass `turbo: false` outside a Turborepo                                        |
+| `a11y: true`\*          | `eslint-plugin-jsx-a11y` — \*default for `/react`, `/nextjs`, `/storybook`; pass `a11y: false` to skip it |
+| `i18n: true`            | `eslint-plugin-i18next`                                                                                   |
+| `testingLibrary: true`  | `eslint-plugin-testing-library eslint-plugin-jest-dom`                                                    |
+
+```bash
+# e.g. a standalone React Native / Expo app, with createReactNativeConfig({ turbo: false })
+npm install --save-dev @forthtilliath/eslint-config eslint typescript \
+  @eslint-react/eslint-plugin eslint-plugin-react eslint-plugin-react-hooks \
+  eslint-plugin-react-refresh eslint-plugin-react-native
+```
+
+A missing plugin fails with an explicit error naming the package to install
+(or the option to turn off) as soon as ESLint loads the config.
+
+**ESLint 10:** `eslint-plugin-react` and `eslint-plugin-react-native` still
+declare `eslint` up to 9 only, so npm refuses to install them next to ESLint
+10 (`ERESOLVE`). They work under ESLint 10 (see the `react-native` rules
+below for the exceptions), so tell npm to accept it in the app's
+`package.json`:
+
+```json
+{
+  "overrides": {
+    "eslint-plugin-react": { "eslint": "$eslint" },
+    "eslint-plugin-react-native": { "eslint": "$eslint" }
+  }
+}
+```
 
 ## Usage
 
@@ -173,6 +214,10 @@ consumer here yet, so `src/angular.test.js` lints small fixture files under
 for that. Extend it (or add a sibling `<variant>.test.js`) whenever a variant
 changes without a real consumer to catch a regression.
 
+`src/package.test.js` guards the dependency layout: any plugin imported
+outside the base config must stay an optional peer dependency, never a
+regular one.
+
 ## Scripts
 
 ```bash

package/dist/angular.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"angular.d.ts","sourceRoot":"","sources":["../src/angular.js"],"names":[],"mappings":"AAMA;;;;;;;;;;GAUG;AACH,8CAHW,OAAO,WAAW,EAAE,iBAAiB,GACnC,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CA+D5C;AAED;;;;8CAI8C;AAC9C,4BADU,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CACS"}
+{"version":3,"file":"angular.d.ts","sourceRoot":"","sources":["../src/angular.js"],"names":[],"mappings":"AAOA;;;;;;;;;;GAUG;AACH,8CAHW,OAAO,WAAW,EAAE,iBAAiB,GACnC,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CA+D5C;AAED;;;;8CAI8C;AAC9C,4BADU,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAC2B"}

package/dist/angular.js

@@ -1,6 +1,7 @@
 import angular from "angular-eslint";
 import { defineConfig } from "eslint/config";
 import tseslint from "typescript-eslint";
+import { lazyConfig } from "./internal/lazy-config.js";
 import { createBaseConfig, NODE_BUILTIN_IMPORT_GROUP } from "./base.js";
 /**
  * A custom ESLint configuration for Angular applications/libraries.
@@ -80,4 +81,4 @@ export function createAngularConfig(options) {
  * default options. Use `createAngularConfig(options)` instead to customize it.
  *
  * @type {import("eslint").Linter.Config[]} */
-export const angularConfig = createAngularConfig();
+export const angularConfig = lazyConfig(() => createAngularConfig());

package/dist/base.d.ts

@@ -9,8 +9,9 @@
  *   fall back to the plain `recommended` preset instead (useful while
  *   migrating an existing codebase that isn't ready for the strict rules).
  * @property {boolean} [turbo=true] - Enable eslint-plugin-turbo's
- *   `no-undeclared-env-vars` rule. Only relevant inside a Turborepo; set to
- *   `false` for a standalone project.
+ *   `no-undeclared-env-vars` rule (needs `eslint-plugin-turbo` installed).
+ *   Only relevant inside a Turborepo; set to `false` for a standalone
+ *   project.
  * @property {boolean} [snakeCase=false] - Also accept `snake_case` variable
  *   names in `@typescript-eslint/naming-convention` — for code that
  *   destructures rows straight from a SQL database (e.g. Supabase), whose
@@ -70,8 +71,9 @@ export type BaseConfigOptions = {
     strict?: boolean | undefined;
     /**
      * - Enable eslint-plugin-turbo's
-     * `no-undeclared-env-vars` rule. Only relevant inside a Turborepo; set to
-     * `false` for a standalone project.
+     * `no-undeclared-env-vars` rule (needs `eslint-plugin-turbo` installed).
+     * Only relevant inside a Turborepo; set to `false` for a standalone
+     * project.
      */
     turbo?: boolean | undefined;
     /**

package/dist/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../src/base.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;;;GAUG;AACH,mEALG;IAA0B,SAAS;IACT,KAAK;CAE/B,GAAU,OAAO,QAAQ,EAAE,MAAM,CAAC,SAAS,CA+B7C;AAED;;;;;GAKG;AACH,2EAHW,iBAAiB,GACf,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAiH5C;AAjMD;;;;;;GAMG;AACH,wCAFU,MAAM,EAAE,CAQhB;AAsLF;;;;;KAKK;AACL,yBAFU,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAEG"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../src/base.js"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;GAUG;AACH,mEALG;IAA0B,SAAS;IACT,KAAK;CAE/B,GAAU,OAAO,QAAQ,EAAE,MAAM,CAAC,SAAS,CA+B7C;AAED;;;;;GAKG;AACH,2EAHW,iBAAiB,GACf,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAiH5C;AAlMD;;;;;;GAMG;AACH,wCAFU,MAAM,EAAE,CAQhB;AAuLF;;;;;KAKK;AACL,yBAFU,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAEqB"}

package/dist/base.js

@@ -2,9 +2,13 @@ import eslint from "@eslint/js";
 import { defineConfig } from "eslint/config";
 import eslintConfigPrettier from "eslint-config-prettier";
 import simpleImportSortPlugin from "eslint-plugin-simple-import-sort";
-import turboPlugin from "eslint-plugin-turbo";
 import globals from "globals";
 import tseslint from "typescript-eslint";
+import { lazyConfig } from "./internal/lazy-config.js";
+import { importOptional, requirePlugin } from "./internal/optional-plugin.js";
+// Optional peer dependency: only a Turborepo needs it (and its own `turbo`
+// peer dependency, the whole Turborepo binary).
+const turboPlugin = await importOptional("eslint-plugin-turbo", () => import("eslint-plugin-turbo"));
 /**
  * Node.js builtins without the `node:` prefix, as the first
  * `simple-import-sort/imports` group. Exported so other variants (e.g.
@@ -30,8 +34,9 @@ export const NODE_BUILTIN_IMPORT_GROUP = [
  *   fall back to the plain `recommended` preset instead (useful while
  *   migrating an existing codebase that isn't ready for the strict rules).
  * @property {boolean} [turbo=true] - Enable eslint-plugin-turbo's
- *   `no-undeclared-env-vars` rule. Only relevant inside a Turborepo; set to
- *   `false` for a standalone project.
+ *   `no-undeclared-env-vars` rule (needs `eslint-plugin-turbo` installed).
+ *   Only relevant inside a Turborepo; set to `false` for a standalone
+ *   project.
  * @property {boolean} [snakeCase=false] - Also accept `snake_case` variable
  *   names in `@typescript-eslint/naming-convention` — for code that
  *   destructures rows straight from a SQL database (e.g. Supabase), whose
@@ -152,7 +157,7 @@ export function createBaseConfig({ prettier = true, strict = true, turbo = true,
         turbo
             ? {
                 plugins: {
-                    turbo: turboPlugin,
+                    turbo: requirePlugin(turboPlugin, "eslint-plugin-turbo", "turbo"),
                 },
                 rules: {
                     "turbo/no-undeclared-env-vars": "error",
@@ -194,4 +199,4 @@ export function createBaseConfig({ prettier = true, strict = true, turbo = true,
  *
  * @type {import("eslint").Linter.Config[]}
  * */
-export const baseConfig = createBaseConfig();
+export const baseConfig = lazyConfig(() => createBaseConfig());

package/dist/internal/lazy-config.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Wraps a config factory call so it only runs the first time the resulting
+ * array is actually read (spread, iterated, indexed...).
+ *
+ * Every variant module exports a ready-made default (`reactConfig`,
+ * `nextJsConfig`...) next to its factory. Built eagerly, that default would
+ * load every optional plugin its default options enable (`a11y`, `turbo`) as
+ * soon as the module is imported — so a project calling
+ * `createReactNativeConfig({ turbo: false })` would still crash on a missing
+ * eslint-plugin-turbo, just because `reactConfig` was evaluated on the way.
+ *
+ * @param {() => import("eslint").Linter.Config[]} create
+ * @returns {import("eslint").Linter.Config[]}
+ */
+export function lazyConfig(create: () => import("eslint").Linter.Config[]): import("eslint").Linter.Config[];
+//# sourceMappingURL=lazy-config.d.ts.map

package/dist/internal/lazy-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-config.d.ts","sourceRoot":"","sources":["../../src/internal/lazy-config.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,mCAHW,MAAM,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GACpC,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAe5C"}

package/dist/internal/lazy-config.js

@@ -0,0 +1,27 @@
+/**
+ * Wraps a config factory call so it only runs the first time the resulting
+ * array is actually read (spread, iterated, indexed...).
+ *
+ * Every variant module exports a ready-made default (`reactConfig`,
+ * `nextJsConfig`...) next to its factory. Built eagerly, that default would
+ * load every optional plugin its default options enable (`a11y`, `turbo`) as
+ * soon as the module is imported — so a project calling
+ * `createReactNativeConfig({ turbo: false })` would still crash on a missing
+ * eslint-plugin-turbo, just because `reactConfig` was evaluated on the way.
+ *
+ * @param {() => import("eslint").Linter.Config[]} create
+ * @returns {import("eslint").Linter.Config[]}
+ */
+export function lazyConfig(create) {
+    /** @type {import("eslint").Linter.Config[] | undefined} */
+    let config;
+    const resolve = () => (config ??= create());
+    // The target is a real (empty) array so `Array.isArray()` stays true —
+    // ESLint's `defineConfig()` relies on it to flatten nested configs.
+    return new Proxy(/** @type {import("eslint").Linter.Config[]} */ ([]), {
+        get: (_target, key) => Reflect.get(resolve(), key),
+        has: (_target, key) => Reflect.has(resolve(), key),
+        ownKeys: () => Reflect.ownKeys(resolve()),
+        getOwnPropertyDescriptor: (_target, key) => Reflect.getOwnPropertyDescriptor(resolve(), key),
+    });
+}

package/dist/internal/optional-plugin.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Plugins that only some variants or options use are optional peer
+ * dependencies (see package.json's `peerDependenciesMeta`): a React Native app
+ * must not end up installing angular-eslint (and the whole Angular CLI it
+ * pulls in), nor a plain TypeScript library every React plugin. Plugins a
+ * variant always needs are imported statically by that variant's module;
+ * plugins behind an option (`a11y`, `i18n`, `testingLibrary`, `turbo`) go
+ * through these helpers instead, so a project that leaves the option off
+ * doesn't have to install them.
+ */
+/**
+ * Imports an optional plugin, resolving to `undefined` when the package isn't
+ * installed. Any other failure (a broken install, a missing transitive
+ * dependency of the plugin itself) is rethrown rather than hidden.
+ *
+ * @template T
+ * @param {string} name - The package name, as passed to `import()`.
+ * @param {() => Promise<{ default: T }>} load - `() => import(name)`, written
+ *   out by the caller so the plugin keeps its type.
+ * @returns {Promise<T | undefined>}
+ */
+export function importOptional<T>(name: string, load: () => Promise<{
+    default: T;
+}>): Promise<T | undefined>;
+/**
+ * Returns `plugin`, or throws an error explaining which package to install
+ * (or which option to turn off) when it's missing.
+ *
+ * @template T
+ * @param {T | undefined} plugin
+ * @param {string} name - The package name.
+ * @param {string} option - The option that needs it, e.g. `a11y`.
+ * @returns {T}
+ */
+export function requirePlugin<T>(plugin: T | undefined, name: string, option: string): T;
+//# sourceMappingURL=optional-plugin.d.ts.map

package/dist/internal/optional-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-plugin.d.ts","sourceRoot":"","sources":["../../src/internal/optional-plugin.js"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;;GAUG;AACH,+BANa,CAAC,QACH,MAAM,QACN,MAAM,OAAO,CAAC;IAAE,OAAO,EAAE,CAAC,CAAA;CAAE,CAAC,GAE3B,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CASlC;AAmBD;;;;;;;;;GASG;AACH,8BANa,CAAC,UACH,CAAC,GAAG,SAAS,QACb,MAAM,UACN,MAAM,GACJ,CAAC,CAWb"}

package/dist/internal/optional-plugin.js

@@ -0,0 +1,63 @@
+/**
+ * Plugins that only some variants or options use are optional peer
+ * dependencies (see package.json's `peerDependenciesMeta`): a React Native app
+ * must not end up installing angular-eslint (and the whole Angular CLI it
+ * pulls in), nor a plain TypeScript library every React plugin. Plugins a
+ * variant always needs are imported statically by that variant's module;
+ * plugins behind an option (`a11y`, `i18n`, `testingLibrary`, `turbo`) go
+ * through these helpers instead, so a project that leaves the option off
+ * doesn't have to install them.
+ */
+/**
+ * Imports an optional plugin, resolving to `undefined` when the package isn't
+ * installed. Any other failure (a broken install, a missing transitive
+ * dependency of the plugin itself) is rethrown rather than hidden.
+ *
+ * @template T
+ * @param {string} name - The package name, as passed to `import()`.
+ * @param {() => Promise<{ default: T }>} load - `() => import(name)`, written
+ *   out by the caller so the plugin keeps its type.
+ * @returns {Promise<T | undefined>}
+ */
+export async function importOptional(name, load) {
+    try {
+        return (await load()).default;
+    }
+    catch (error) {
+        if (isPackageNotFound(error, name))
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * @param {unknown} error
+ * @param {string} name
+ * @returns {boolean}
+ */
+function isPackageNotFound(error, name) {
+    return (error instanceof Error &&
+        "code" in error &&
+        error.code === "ERR_MODULE_NOT_FOUND" &&
+        // Node names the package it couldn't find: checking it tells "the
+        // plugin isn't installed" apart from "the plugin is installed but one of
+        // its own dependencies is missing", which must not be swallowed.
+        error.message.includes(`'${name}'`));
+}
+/**
+ * Returns `plugin`, or throws an error explaining which package to install
+ * (or which option to turn off) when it's missing.
+ *
+ * @template T
+ * @param {T | undefined} plugin
+ * @param {string} name - The package name.
+ * @param {string} option - The option that needs it, e.g. `a11y`.
+ * @returns {T}
+ */
+export function requirePlugin(plugin, name, option) {
+    if (plugin === undefined) {
+        throw new Error(`@forthtilliath/eslint-config: the \`${option}\` option needs ${name}, ` +
+            `which isn't installed. Install it as a devDependency ` +
+            `(npm install --save-dev ${name}), or pass \`${option}: false\`.`);
+    }
+    return plugin;
+}

package/dist/nextjs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nextjs.d.ts","sourceRoot":"","sources":["../src/nextjs.js"],"names":[],"mappings":"AAKA;;;;;;;KAOK;AACL,6CAHW,OAAO,WAAW,EAAE,iBAAiB,GAAG,OAAO,YAAY,EAAE,kBAAkB,GAC7E,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAsD5C;AAED;;;;;KAKK;AACL,2BAFU,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAEO"}
+{"version":3,"file":"nextjs.d.ts","sourceRoot":"","sources":["../src/nextjs.js"],"names":[],"mappings":"AAMA;;;;;;;KAOK;AACL,6CAHW,OAAO,WAAW,EAAE,iBAAiB,GAAG,OAAO,YAAY,EAAE,kBAAkB,GAC7E,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAsD5C;AAED;;;;;KAKK;AACL,2BAFU,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAEyB"}

package/dist/nextjs.js

@@ -1,5 +1,6 @@
 import pluginNext from "@next/eslint-plugin-next";
 import { defineConfig } from "eslint/config";
+import { lazyConfig } from "./internal/lazy-config.js";
 import { createReactConfig } from "./react.js";
 /**
  * A custom ESLint configuration for Next.js applications, built on top of
@@ -68,4 +69,4 @@ export function createNextJsConfig(options) {
  *
  * @type {import("eslint").Linter.Config[]}
  * */
-export const nextJsConfig = createNextJsConfig();
+export const nextJsConfig = lazyConfig(() => createNextJsConfig());

package/dist/react-native.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react-native.d.ts","sourceRoot":"","sources":["../src/react-native.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AAEH;;;;iDAIiD;AACjD,+DAFW,OAAO,WAAW,EAAE,iBAAiB,GAAG,OAAO,YAAY,EAAE,kBAAkB,GAC7E,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAwC5C;AAED;;;;;8CAK8C;AAC9C,gCADU,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CACiB"}
+{"version":3,"file":"react-native.d.ts","sourceRoot":"","sources":["../src/react-native.js"],"names":[],"mappings":"AAMA;;;;;GAKG;AAEH;;;;iDAIiD;AACjD,+DAFW,OAAO,WAAW,EAAE,iBAAiB,GAAG,OAAO,YAAY,EAAE,kBAAkB,GAC7E,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAwC5C;AAED;;;;;8CAK8C;AAC9C,gCADU,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CACmC"}

package/dist/react-native.js

@@ -1,5 +1,6 @@
 import { defineConfig } from "eslint/config";
 import pluginReactNative from "eslint-plugin-react-native";
+import { lazyConfig } from "./internal/lazy-config.js";
 import { createReactConfig } from "./react.js";
 /**
  * eslint-plugin-react-native only ships a legacy (eslintrc) `configs.all`
@@ -58,4 +59,4 @@ export function createReactNativeConfig({ a11y = false, ...options } = {}) {
  * customize it.
  *
  * @type {import("eslint").Linter.Config[]} */
-export const reactNativeConfig = createReactNativeConfig();
+export const reactNativeConfig = lazyConfig(() => createReactNativeConfig());

package/dist/react.d.ts

@@ -1,14 +1,16 @@
 /**
  * @typedef {object} ReactConfigOptions
  * @property {boolean} [a11y=true] - Enable eslint-plugin-jsx-a11y's
- *   recommended rules.
+ *   recommended rules (needs `eslint-plugin-jsx-a11y` installed).
  * @property {boolean} [i18n=false] - Enable eslint-plugin-i18next's
- *   `no-literal-string` rule, forbidding any hardcoded string in JSX. Only
- *   makes sense for a project fully committed to i18n (e.g. driven by
- *   next-intl) — off by default since it flags every literal otherwise.
+ *   `no-literal-string` rule, forbidding any hardcoded string in JSX (needs
+ *   `eslint-plugin-i18next` installed). Only makes sense for a project fully
+ *   committed to i18n (e.g. driven by next-intl) — off by default since it
+ *   flags every literal otherwise.
  * @property {boolean} [testingLibrary=false] - Enable
  *   eslint-plugin-testing-library's React rules and eslint-plugin-jest-dom's
- *   recommended rules, scoped to test files only. Off by default:
+ *   recommended rules, scoped to test files only (needs both installed). Off
+ *   by default:
  *   `testing-library/no-manual-cleanup` in particular assumes
  *   `@testing-library/*`'s automatic `afterEach(cleanup)` is active, which
  *   only happens when `afterEach` is a real global (vitest's `test.globals:
@@ -31,20 +33,22 @@ export const reactConfig: import("eslint").Linter.Config[];
 export type ReactConfigOptions = {
     /**
      * - Enable eslint-plugin-jsx-a11y's
-     * recommended rules.
+     * recommended rules (needs `eslint-plugin-jsx-a11y` installed).
      */
     a11y?: boolean | undefined;
     /**
      * - Enable eslint-plugin-i18next's
-     * `no-literal-string` rule, forbidding any hardcoded string in JSX. Only
-     * makes sense for a project fully committed to i18n (e.g. driven by
-     * next-intl) — off by default since it flags every literal otherwise.
+     * `no-literal-string` rule, forbidding any hardcoded string in JSX (needs
+     * `eslint-plugin-i18next` installed). Only makes sense for a project fully
+     * committed to i18n (e.g. driven by next-intl) — off by default since it
+     * flags every literal otherwise.
      */
     i18n?: boolean | undefined;
     /**
      * - Enable
      * eslint-plugin-testing-library's React rules and eslint-plugin-jest-dom's
-     * recommended rules, scoped to test files only. Off by default:
+     * recommended rules, scoped to test files only (needs both installed). Off
+     * by default:
      * `testing-library/no-manual-cleanup` in particular assumes
      * `@testing-library/*`'s automatic `afterEach(cleanup)` is active, which
      * only happens when `afterEach` is a real global (vitest's `test.globals:

package/dist/react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.js"],"names":[],"mappings":"AAuCA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;GAKG;AACH,0FAHW,OAAO,WAAW,EAAE,iBAAiB,GAAG,kBAAkB,GACxD,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAwF5C;AAED;;;;8CAI8C;AAC9C,0BADU,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CACK"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.js"],"names":[],"mappings":"AA2DA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;GAKG;AACH,0FAHW,OAAO,WAAW,EAAE,iBAAiB,GAAG,kBAAkB,GACxD,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAyG5C;AAED;;;;8CAI8C;AAC9C,0BADU,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CACuB"}

package/dist/react.js

@@ -1,14 +1,20 @@
 import pluginEslintReact from "@eslint-react/eslint-plugin";
 import { defineConfig } from "eslint/config";
-import pluginI18next from "eslint-plugin-i18next";
-import pluginJestDom from "eslint-plugin-jest-dom";
-import pluginJsxA11y from "eslint-plugin-jsx-a11y";
 import pluginReact from "eslint-plugin-react";
 import pluginReactHooks from "eslint-plugin-react-hooks";
 import pluginReactRefresh from "eslint-plugin-react-refresh";
-import pluginTestingLibrary from "eslint-plugin-testing-library";
 import globals from "globals";
+import { lazyConfig } from "./internal/lazy-config.js";
+import { importOptional, requirePlugin } from "./internal/optional-plugin.js";
 import { createBaseConfig, createNamingConventionRule } from "./base.js";
+// Optional peer dependencies, each behind an option (see
+// ReactConfigOptions): a project leaving the option off doesn't install them.
+const [pluginJsxA11y, pluginI18next, pluginTestingLibrary, pluginJestDom] = await Promise.all([
+    importOptional("eslint-plugin-jsx-a11y", () => import("eslint-plugin-jsx-a11y")),
+    importOptional("eslint-plugin-i18next", () => import("eslint-plugin-i18next")),
+    importOptional("eslint-plugin-testing-library", () => import("eslint-plugin-testing-library")),
+    importOptional("eslint-plugin-jest-dom", () => import("eslint-plugin-jest-dom")),
+]);
 /**
  * Any file matching this is a test file, whatever runner or naming
  * convention is used to suffix it (`.test.`, `.spec.`, `.dom.test.`...) —
@@ -36,14 +42,16 @@ const RULES_COVERED_BY_ESLINT_REACT = [
 /**
  * @typedef {object} ReactConfigOptions
  * @property {boolean} [a11y=true] - Enable eslint-plugin-jsx-a11y's
- *   recommended rules.
+ *   recommended rules (needs `eslint-plugin-jsx-a11y` installed).
  * @property {boolean} [i18n=false] - Enable eslint-plugin-i18next's
- *   `no-literal-string` rule, forbidding any hardcoded string in JSX. Only
- *   makes sense for a project fully committed to i18n (e.g. driven by
- *   next-intl) — off by default since it flags every literal otherwise.
+ *   `no-literal-string` rule, forbidding any hardcoded string in JSX (needs
+ *   `eslint-plugin-i18next` installed). Only makes sense for a project fully
+ *   committed to i18n (e.g. driven by next-intl) — off by default since it
+ *   flags every literal otherwise.
  * @property {boolean} [testingLibrary=false] - Enable
  *   eslint-plugin-testing-library's React rules and eslint-plugin-jest-dom's
- *   recommended rules, scoped to test files only. Off by default:
+ *   recommended rules, scoped to test files only (needs both installed). Off
+ *   by default:
  *   `testing-library/no-manual-cleanup` in particular assumes
  *   `@testing-library/*`'s automatic `afterEach(cleanup)` is active, which
  *   only happens when `afterEach` is a real global (vitest's `test.globals:
@@ -59,21 +67,26 @@ const RULES_COVERED_BY_ESLINT_REACT = [
 export function createReactConfig({ a11y = true, i18n = false, testingLibrary = false, snakeCase = false, ...options } = {}) {
     return defineConfig([
         ...createBaseConfig({ snakeCase, ...options }),
-        a11y ? pluginJsxA11y.flatConfigs.recommended : [],
+        a11y
+            ? requirePlugin(pluginJsxA11y, "eslint-plugin-jsx-a11y", "a11y")
+                .flatConfigs.recommended
+            : [],
         i18n
             ? {
-                plugins: { i18next: pluginI18next },
+                plugins: {
+                    i18next: requirePlugin(pluginI18next, "eslint-plugin-i18next", "i18n"),
+                },
                 rules: { "i18next/no-literal-string": "error" },
             }
             : [],
         testingLibrary
             ? [
                 {
-                    ...pluginTestingLibrary.configs["flat/react"],
+                    ...requirePlugin(pluginTestingLibrary, "eslint-plugin-testing-library", "testingLibrary").configs["flat/react"],
                     files: TEST_FILE_GLOBS,
                 },
                 {
-                    ...pluginJestDom.configs["flat/recommended"],
+                    ...requirePlugin(pluginJestDom, "eslint-plugin-jest-dom", "testingLibrary").configs["flat/recommended"],
                     files: TEST_FILE_GLOBS,
                 },
             ]
@@ -140,4 +153,4 @@ export function createReactConfig({ a11y = true, i18n = false, testingLibrary =
  * default options. Use `createReactConfig(options)` instead to customize it.
  *
  * @type {import("eslint").Linter.Config[]} */
-export const reactConfig = createReactConfig();
+export const reactConfig = lazyConfig(() => createReactConfig());

package/dist/storybook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storybook.d.ts","sourceRoot":"","sources":["../src/storybook.js"],"names":[],"mappings":"AAKA;;;;iDAIiD;AACjD,gDAFW,OAAO,WAAW,EAAE,iBAAiB,GAAG,OAAO,YAAY,EAAE,kBAAkB,GAC7E,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAiB5C;AAED;;;;;8CAK8C;AAC9C,8BADU,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CACa"}
+{"version":3,"file":"storybook.d.ts","sourceRoot":"","sources":["../src/storybook.js"],"names":[],"mappings":"AAMA;;;;iDAIiD;AACjD,gDAFW,OAAO,WAAW,EAAE,iBAAiB,GAAG,OAAO,YAAY,EAAE,kBAAkB,GAC7E,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAiB5C;AAED;;;;;8CAK8C;AAC9C,8BADU,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAC+B"}

package/dist/storybook.js

@@ -1,5 +1,6 @@
 import { defineConfig } from "eslint/config";
 import storybook from "eslint-plugin-storybook";
+import { lazyConfig } from "./internal/lazy-config.js";
 import { createReactConfig } from "./react.js";
 /**
  * A custom ESLint configuration for libraries that use React and Storybook.
@@ -29,4 +30,4 @@ export function createStorybookConfig(options) {
  * customize it.
  *
  * @type {import("eslint").Linter.Config[]} */
-export const storybookConfig = createStorybookConfig();
+export const storybookConfig = lazyConfig(() => createStorybookConfig());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forthtilliath/eslint-config",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -18,14 +18,21 @@
   ],
   "exports": {
     ".": "./dist/base.js",
+    "./internal/*": null,
     "./*": "./dist/*.js"
   },
   "dependencies": {
-    "@eslint-react/eslint-plugin": "^5.18.3",
     "@eslint/js": "^9.39.5",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-simple-import-sort": "^13.0.0",
+    "globals": "^17.9.0",
+    "typescript-eslint": "^8.67.0"
+  },
+  "peerDependencies": {
+    "@eslint-react/eslint-plugin": "^5.18.3",
     "@next/eslint-plugin-next": "^16.3.0",
     "angular-eslint": "^21.4.0",
-    "eslint-config-prettier": "^10.1.8",
+    "eslint": "^9.0.0 || ^10.0.0",
     "eslint-plugin-i18next": "^6.1.5",
     "eslint-plugin-jest-dom": "^5.10.1",
     "eslint-plugin-jsx-a11y": "^6.10.2",
@@ -33,20 +40,68 @@
     "eslint-plugin-react-hooks": "^7.1.1",
     "eslint-plugin-react-native": "^5.0.0",
     "eslint-plugin-react-refresh": "^0.5.4",
-    "eslint-plugin-simple-import-sort": "^13.0.0",
     "eslint-plugin-storybook": "^10.6.1",
     "eslint-plugin-testing-library": "^7.16.2",
     "eslint-plugin-turbo": "^2.10.9",
-    "globals": "^17.9.0",
-    "typescript-eslint": "^8.67.0"
-  },
-  "peerDependencies": {
-    "eslint": "^9.0.0 || ^10.0.0",
     "typescript": ">=5.0.0"
   },
+  "peerDependenciesMeta": {
+    "@eslint-react/eslint-plugin": {
+      "optional": true
+    },
+    "@next/eslint-plugin-next": {
+      "optional": true
+    },
+    "angular-eslint": {
+      "optional": true
+    },
+    "eslint-plugin-i18next": {
+      "optional": true
+    },
+    "eslint-plugin-jest-dom": {
+      "optional": true
+    },
+    "eslint-plugin-jsx-a11y": {
+      "optional": true
+    },
+    "eslint-plugin-react": {
+      "optional": true
+    },
+    "eslint-plugin-react-hooks": {
+      "optional": true
+    },
+    "eslint-plugin-react-native": {
+      "optional": true
+    },
+    "eslint-plugin-react-refresh": {
+      "optional": true
+    },
+    "eslint-plugin-storybook": {
+      "optional": true
+    },
+    "eslint-plugin-testing-library": {
+      "optional": true
+    },
+    "eslint-plugin-turbo": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@angular/core": "^21.0.0",
+    "@eslint-react/eslint-plugin": "^5.18.3",
+    "@next/eslint-plugin-next": "^16.3.0",
+    "angular-eslint": "^21.4.0",
     "eslint": "10.7.0",
+    "eslint-plugin-i18next": "^6.1.5",
+    "eslint-plugin-jest-dom": "^5.10.1",
+    "eslint-plugin-jsx-a11y": "^6.10.2",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-native": "^5.0.0",
+    "eslint-plugin-react-refresh": "^0.5.4",
+    "eslint-plugin-storybook": "^10.6.1",
+    "eslint-plugin-testing-library": "^7.16.2",
+    "eslint-plugin-turbo": "^2.10.9",
     "rxjs": "^7.8.0",
     "typescript": "^5.9.3",
     "vitest": "^5.0.2",