@kirill.konshin/lint 0.1.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -24,33 +24,58 @@ node-linker=hoisted
24
24
  `eslint.config.mjs`:
25
25
 
26
26
  ```js
27
- import { defineConfig } from 'eslint/config';
28
- import customConfig, { nextPlugin, includeIgnoreFile, tsExts } from '@kirill.konshin/lint';
27
+ import { defineLintConfig } from '@kirill.konshin/lint';
29
28
 
30
- export default defineConfig([
31
- ...customConfig,
32
- {
33
- files: [`**/*.${tsExts}`],
34
- plugins: {
35
- next: nextPlugin,
36
- },
37
- settings: {
38
- next: {
39
- rootDir: process.cwd() + '/path/to/next-app',
40
- },
41
- },
42
- },
29
+ export default defineLintConfig(); // every tool integration auto-detected
30
+ ```
31
+
32
+ Every tool integration — Next.js, Nx, Turborepo, Storybook, Jest, Vitest, Tailwind — is auto-detected (the detection results are exported as `has*` booleans for debugging). Pass options (JSDoc-typed, see `LintOptions` in `index.js`) to force any of them on/off or to supply tool-specific settings:
33
+
34
+ ```js
35
+ export default defineLintConfig({
36
+ defaultIgnore: { importMetaUrl: import.meta.url }, // .gitignore + .prettierignore as ESLint ignores
37
+ next: { rootDir: 'path/to/next-app' }, // an options object means ON + settings; auto-detected when omitted
38
+ tailwind: true, // force ON when detection misses it
39
+ turbo: false, // force OFF
40
+ });
41
+ ```
42
+
43
+ - `undefined` (default) — auto-detect
44
+ - `true` or an options object — force ON. Detection probes resolve from this package's install location, so in a monorepo where a tool lives only in **leaf** packages (not the root `package.json`) detection can miss it — force the flag in that case
45
+ - `false` — force OFF
46
+ - in the object form `enabled` defaults to `true` — providing options implies turning the tool on; set `enabled: false` to force OFF while keeping the other options in place (e.g. `tailwind: { enabled: false, cssConfigPath: '...' }`)
47
+
48
+ `defaultIgnore` and `typeAware` have nothing to auto-detect, so they are OFF unless set. `defaultIgnore` converts the `.gitignore` and `.prettierignore` sitting next to your config file (both must exist) into ESLint ignores — it needs your `import.meta.url`, so `defaultIgnore: true` alone is a hard error.
49
+
50
+ `next.rootDir` is auto-detected when omitted: the directories containing a `next.config.*`. None found → the setting is simply left out (it's optional); several apps → all of them as an array.
51
+
52
+ All file scans (Tailwind entry, `next.config.*`) and `nx.json` detection are anchored to the **workspace root**, not cwd — linting from inside a package (lint-staged, IDE, `yarn workspace x lint`) still sees the whole repo. The root is detected by asking the package manager (env: Yarn Berry `PROJECT_CWD`, npm `npm_config_local_prefix`; CLIs: `pnpm root -w`, Yarn Berry via `yarn node`, `npm prefix`), falling back to a lockfile walk bounded by `.git`; `findWorkspaceRoot` is exported for debugging alongside the `has*` flags. Yarn 1 (classic) provides neither a root env nor a root command — classic workspaces resolve via `npm prefix` (same package.json `workspaces` field) or the yarn.lock walk.
53
+
54
+ Options can also be produced by a (possibly async) function: `defineLintConfig(() => ({ tailwind: true }))`.
55
+
56
+ `defineLintConfig` returns a `Promise` — ESLint natively awaits a Promise default export, so the plain form above just works. To compose with your own blocks, `await` it:
57
+
58
+ ```js
59
+ import { defineLintConfig, includeIgnoreFile } from '@kirill.konshin/lint';
60
+
61
+ export default [
62
+ ...(await defineLintConfig({ defaultIgnore: { importMetaUrl: import.meta.url } })),
43
63
  {
44
64
  name: 'Custom rules',
45
65
  rules: {
46
66
  // overrides
47
67
  },
48
68
  },
49
- includeIgnoreFile(import.meta.url, '.gitignore'),
50
- includeIgnoreFile(import.meta.url, '.prettierignore'),
51
- ]);
69
+ includeIgnoreFile(import.meta.url, '.customignore'), // extra ignore files beyond defaultIgnore
70
+ ];
52
71
  ```
53
72
 
73
+ **Every** block lives in a themed `configs/*.js` file and is exported as a standalone function for manual composition (and easy testing/mocking), in the order `defineLintConfig` applies them — blocks from the same file stay consecutive, which matters inside a family (Next: base config → the TS wiring stemming from it → overrides → settings): `baseConfig` (JS recommended + global ignores + globals + core-rule overrides), `defaultIgnoreConfig`, `nextConfig`, `typescriptOverridesConfig`, `nextOverridesConfig`, `reactSettingsConfig`, `prettierConfig`, `storybookConfig`, `typeAwareConfig` (off by default — see [Type-aware rules](#type-aware-rules); ordered before the import blocks so its naming-convention rule loses to the default-export relaxation), `importXConfig` (includes the default-export relaxation for conventional files), `importSortConfig`, `unusedImportsConfig`, `promiseConfig`, `unicornConfig`, `turboConfig`, `tailwindConfig`, `nxConfig`, `jestConfig`, `vitestConfig`, `testConfig`.
74
+
75
+ Tool-gated functions take the same value as their `defineLintConfig` flag and gate themselves (`tailwindConfig(true)`, `nxConfig(false)` → `[]`, `tailwindConfig({ cssConfigPath })`). `nextConfig` is a composite: `nextBaseConfig` (the pure Next blocks, also exported) when Next is enabled, the `reactConfig` fallback otherwise — both are exported for direct use too.
76
+
77
+ The package ships hand-written types (`index.d.ts`) that pull real types from the underlying packages — `Linter.Config` from `eslint`, `PluginSettings` from `eslint-plugin-tailwindcss`, `prettier`'s `Config`, `lint-staged`'s `Configuration` — so `defineLintConfig` options and all exports are fully typed in `eslint.config.mjs` (via editor inference) and `eslint.config.ts`.
78
+
54
79
  `.prettierrc.mjs`:
55
80
 
56
81
  ```js
@@ -104,6 +129,42 @@ indent_style = tab
104
129
  }
105
130
  ```
106
131
 
132
+ ### Tailwind CSS rules
133
+
134
+ When Tailwind is enabled — auto-detected via `tailwindcss` (v4+) being installed, or forced with `tailwind: true` — the config enables [`eslint-plugin-tailwindcss`](https://github.com/francoismassart/eslint-plugin-tailwindcss) recommended rules. The plugin **must** be able to resolve the Tailwind entry CSS — it hard-crashes lint (ENOENT) otherwise — so the entry is auto-detected: the workspace is scanned for `*.css` files containing `@import "tailwindcss"` (up to five directory levels below the workspace root — covers `packages/<x>/src/styles` — skipping dot dirs, `node_modules`, build outputs like `dist`/`.next`, and everything in `.gitignore`).
135
+
136
+ - Exactly **one** entry found → rules enable automatically with it (added as a standalone config block, easy to override).
137
+ - **Zero or several** entries:
138
+ - auto-detected → nothing is added (inert); pass the entry explicitly (below)
139
+ - forced (`tailwind: true`) → **hard error** — you explicitly asked for Tailwind linting, so a silent skip would be a lie
140
+ - An explicit entry always wins over the scan:
141
+
142
+ ```js
143
+ export default defineLintConfig({
144
+ tailwind: {
145
+ cssConfigPath: './src/styles/tailwind.css', // relative to the package root
146
+ },
147
+ });
148
+ ```
149
+
150
+ ### Type-aware rules (optional, disabled by default for performance)
151
+
152
+ Off by default (typed linting is slow); enable with `typeAware: true` or an options object.
153
+
154
+ Config files living outside any tsconfig `include` (`vite.config.ts`, `.storybook/main.ts`, …) need typescript-eslint's `allowDefaultProject` — it has **no default** here, and upstream forbids `**` in its patterns, so either spell out each directory level or generate the exact file list with the exported `scanWorkspace` (workspace-root-anchored, `.gitignore`- and build-output-aware; its absolute paths are relativized against `tsconfigRootDir` automatically):
155
+
156
+ ```js
157
+ import { defineLintConfig, scanWorkspace } from '@kirill.konshin/lint';
158
+
159
+ export default defineLintConfig({
160
+ typeAware: {
161
+ allowDefaultProject: scanWorkspace('{vite,vitest}.config.ts'),
162
+ maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING: 50, // defaults to allowDefaultProject.length when the list is given (typescript-eslint's own default is 8) - set it explicitly only when supplying multi-match globs
163
+ tsconfigRootDir: '...', // defaults to the detected workspace root
164
+ },
165
+ });
166
+ ```
167
+
107
168
  ### IDEA settings
108
169
 
109
170
  - Eslint: `**/*.{js,jsx,ts,tsx,cjs,cts,mjs,mts,md,mdx,htm,html,vue}`
@@ -185,12 +246,70 @@ paths:
185
246
  ---
186
247
  ```
187
248
 
249
+ ## Migration
250
+
251
+ ### 0.2.x → 0.3.x
252
+
253
+ The default-exported config array was replaced by the `defineLintConfig()` factory (see [Settings](#settings)) — every tool integration is auto-detected and controlled via options instead of hand-written blocks.
254
+
255
+ Before (0.2.x):
256
+
257
+ ```js
258
+ import { defineConfig } from 'eslint/config';
259
+ import customConfig, { nextPlugin, includeIgnoreFile, tsExts } from '@kirill.konshin/lint';
260
+
261
+ export default defineConfig([
262
+ ...customConfig,
263
+ {
264
+ files: [`**/*.${tsExts}`],
265
+ plugins: { next: nextPlugin },
266
+ settings: { next: { rootDir: 'path/to/next-app' } },
267
+ },
268
+ { name: 'Custom rules', rules: {} },
269
+ includeIgnoreFile(import.meta.url, '.gitignore'),
270
+ includeIgnoreFile(import.meta.url, '.prettierignore'),
271
+ ]);
272
+ ```
273
+
274
+ After (0.3.x):
275
+
276
+ ```js
277
+ import { defineLintConfig } from '@kirill.konshin/lint';
278
+
279
+ export default [
280
+ ...(await defineLintConfig({
281
+ defaultIgnore: { importMetaUrl: import.meta.url },
282
+ next: { rootDir: 'path/to/next-app' },
283
+ })),
284
+ { name: 'Custom rules', rules: {} },
285
+ ];
286
+ ```
287
+
288
+ - **Default export removed** — import `defineLintConfig` and call it. ESLint awaits the returned Promise, so a plain `export default defineLintConfig({...})` works when no extra blocks are needed
289
+ - **Manual `settings.next.rootDir` block** → `next: { rootDir }` option — or nothing at all: it is auto-detected from `next.config.*` locations (several apps → array)
290
+ - **Scans are workspace-root-anchored** — the Tailwind entry / `next.config.*` scans and `nx.json` detection resolve the workspace root via the package manager instead of trusting cwd, so linting from inside a package behaves like linting from the root
291
+ - **Manual Tailwind block** (`settings.tailwindcss.cssConfigPath`) → `tailwind: { cssConfigPath }` option; `tailwind: true` without a resolvable entry CSS is now a **hard error** instead of a silent skip
292
+ - **`includeIgnoreFile(import.meta.url, '.gitignore' / '.prettierignore')` pair** → `defaultIgnore: { importMetaUrl: import.meta.url }` (`includeIgnoreFile` stays exported for extra ignore files)
293
+ - **`tailwindEntry` const removed** → call the exported `findTailwindEntry(ignores)` when needed
294
+ - **New:** every block is a composable exported `*Config()` function; gated ones accept `true` / `false` / an options object with optional `enabled` (defaults to `true` in the object form); `typeAware: true` enables the (slow) type-aware rules
295
+ - **`prettier` is now a declared (required) peer dependency** — it was always required by the setup, so no action needed in practice
296
+ - **TypeScript consumers get real types** — `index.d.ts` ships with the package (`LintOptions` and friends)
297
+
298
+ Everything else — `prettier`, `listStaged`, extension lists (`tsExts`, …), `has*` detection exports, plugin re-exports (`nxPlugin`, …) — is unchanged.
299
+
188
300
  ## Why raw JS (no build)
189
301
 
190
302
  Deliberately plain ESM, **no TypeScript build**: the config is loaded by `eslint.config.mjs` and pre-commit `lint:staged` before anything is built, so a `dist/` `main` would force a build before the repo could lint — not worth it for a config package.
191
303
 
192
304
  ## Issues
193
305
 
306
+ - Package managers
307
+ - [ ] TODO verify the package end-to-end (workspace-root detection, Tailwind / `next.config.*` scans, `has*` capability probes, plugin resolution, `defineLintConfig` under a real lint run) with each manager:
308
+ - [x] Yarn Berry, node-modules linker — this repo, fully covered
309
+ - [ ] Yarn Berry **PnP** — entirely unverified: no `node_modules`, resolution/hoisting differs, `import.meta.resolve` probes and leaf-package detection may behave differently
310
+ - [ ] Yarn 1 (classic) — workspace-root detection verified in a scratch workspace (no root env, `npm prefix`/lockfile-walk path); full config unverified
311
+ - [ ] pnpm — workspace-root detection verified in a scratch workspace (`pnpm root -w`, no usable env); full config unverified
312
+ - [ ] npm — root probes verified (`npm_config_local_prefix`, workspace-aware `npm prefix`); full config unverified
194
313
  - ESLint 9
195
314
  - [x] https://github.com/microsoft/rushstack/issues/4635 Failed to patch ESLint because the calling module was not recognized
196
315
  - [x] https://github.com/microsoft/rushstack/issues/4965 Failed to patch ESLint because the calling module was not recognized
@@ -0,0 +1,98 @@
1
+ import { dirname, resolve } from 'node:path';
2
+ import { fileURLToPath } from 'node:url';
3
+ import { includeIgnoreFile as includeIgnoreFileCompat } from '@eslint/compat';
4
+ import js from '@eslint/js';
5
+ import globals from 'globals';
6
+
7
+ import { asOptions, GLOBAL_IGNORES } from '../lib.js';
8
+
9
+ /**
10
+ * Core JS recommended rules, global ignores, browser + Node globals, and overrides of core ESLint
11
+ * rules.
12
+ *
13
+ * `eslint-config-next` already ignores `next-env.d.ts`, but only as a bare pattern ('next-env.d.ts'),
14
+ * which only matches at the config's own root - not when the Next app (and its generated
15
+ * next-env.d.ts) lives in a subdirectory, like demo/web-static/ here. It's auto-generated and
16
+ * explicitly marked "should not be edited", so exclude it recursively instead of just working
17
+ * around individual rules (its `///` reference directives otherwise trip multiline-comment-style,
18
+ * which would corrupt them if autofixed into a `/* *\/` block).
19
+ *
20
+ * @returns {import('eslint').Linter.Config[]}
21
+ */
22
+ export function baseConfig() {
23
+ return [
24
+ js.configs.recommended,
25
+ {
26
+ name: 'Global Ignores',
27
+ ignores: GLOBAL_IGNORES,
28
+ },
29
+ {
30
+ name: 'Globals',
31
+ languageOptions: {
32
+ globals: {
33
+ ...globals.browser,
34
+ ...globals.node,
35
+ },
36
+ },
37
+ },
38
+ {
39
+ name: 'ESLint overrides',
40
+ rules: {
41
+ 'no-restricted-imports': [
42
+ 'error',
43
+ {
44
+ paths: [
45
+ {
46
+ name: 'next/router',
47
+ message: 'Please use next/navigation instead of next/router',
48
+ },
49
+ ],
50
+ },
51
+ ],
52
+ // 'multiline-comment-style': ['warn', 'starred-block'],
53
+ 'multiline-comment-style': 'off',
54
+ },
55
+ },
56
+ ];
57
+ }
58
+
59
+ /**
60
+ * Convert an ignore file (`.gitignore`, `.prettierignore`, ...) into an ESLint ignores block,
61
+ * resolved next to the consumer's config file.
62
+ *
63
+ * @param {string} importMetaUrl `import.meta.url` of the consumer's `eslint.config.mjs`
64
+ * @param {string} ignoreFile
65
+ * @returns {import('eslint').Linter.Config}
66
+ */
67
+ export function includeIgnoreFile(importMetaUrl, ignoreFile) {
68
+ // @see https://blog.linotte.dev/eslint-9-next-js-935c2b6d0371
69
+ return includeIgnoreFileCompat(resolve(dirname(fileURLToPath(importMetaUrl)), ignoreFile));
70
+ }
71
+
72
+ /** @typedef {import('../index.js').DefaultIgnoreOptions} DefaultIgnoreOptions Defined in index.d.ts. */
73
+
74
+ /**
75
+ * The conventional ignore setup of this toolkit: `.gitignore` + `.prettierignore` next to the
76
+ * consumer's config file, both converted into ESLint ignores via {@link includeIgnoreFile} (both
77
+ * files must exist - the prettier scripts in README use the same two).
78
+ *
79
+ * There is nothing to auto-detect here - the consumer's config file location can't be known - so
80
+ * the flag is off by default and enabling it without `importMetaUrl` is a hard error.
81
+ *
82
+ * @param {boolean | DefaultIgnoreOptions} [option] the defineLintConfig `defaultIgnore` flag
83
+ * @returns {import('eslint').Linter.Config[]}
84
+ */
85
+ export function defaultIgnoreConfig(option) {
86
+ const { enabled = false, importMetaUrl } = asOptions(option);
87
+ if (!enabled) return [];
88
+
89
+ if (!importMetaUrl) {
90
+ throw new Error(
91
+ '[@kirill.konshin/lint] `defaultIgnore` was enabled, but `importMetaUrl` was not provided - the ' +
92
+ 'location of the consumer config file cannot be auto-detected. ' +
93
+ 'Pass `defaultIgnore: { importMetaUrl: import.meta.url }`.',
94
+ );
95
+ }
96
+
97
+ return [includeIgnoreFile(importMetaUrl, '.gitignore'), includeIgnoreFile(importMetaUrl, '.prettierignore')];
98
+ }
@@ -0,0 +1,162 @@
1
+ import { createTypeScriptImportResolver } from 'eslint-import-resolver-typescript';
2
+ import importXPlugin, { createNodeResolver } from 'eslint-plugin-import-x';
3
+ import simpleImportSortPlugin from 'eslint-plugin-simple-import-sort';
4
+ import unusedImportsPlugin from 'eslint-plugin-unused-imports';
5
+
6
+ import { tsExts } from '../lib.js';
7
+
8
+ /**
9
+ * Import linting via eslint-plugin-import-x: recommended rules + overrides + the default-export
10
+ * relaxation for files that legitimately default-export (framework/tooling conventions) - the
11
+ * latter makes no sense without `import-x/no-default-export`, so it is not a separate block.
12
+ *
13
+ * eslint-config-next already registers `eslint-plugin-import` under the 'import' key, and ESLint 10
14
+ * hard-errors ("Cannot redefine plugin") if a later config tries to reuse that same key with a
15
+ * different plugin instance. eslint-plugin-import-x is a drop-in replacement, registered under its
16
+ * own 'import-x' key instead (its own recommended config does this registration for us).
17
+ *
18
+ * @returns {import('eslint').Linter.Config[]}
19
+ */
20
+ export function importXConfig() {
21
+ return [
22
+ importXPlugin.configs['flat/recommended'],
23
+ {
24
+ name: 'eslint-plugin-import-x overrides',
25
+ settings: {
26
+ /*
27
+ * `createTypeScriptImportResolver` correctly resolves relative imports and simple TS path
28
+ * aliases, but NOT cross-workspace-package imports in this monorepo (e.g. `@kirill.konshin/node`)
29
+ * or subpath exports (e.g. `next/constants`) - verified empirically. That's why the
30
+ * resolution-dependent rules below are turned off rather than left on the recommended default.
31
+ */
32
+ 'import-x/resolver-next': [createTypeScriptImportResolver(), createNodeResolver()],
33
+ },
34
+ rules: {
35
+ /*
36
+ * Off because of the workspace/subpath resolution gaps above - re-enable per-project once
37
+ * resolution is confirmed reliable there (e.g. a single-app, non-monorepo consumer).
38
+ */
39
+ 'import-x/no-unresolved': 'off',
40
+ 'import-x/named': 'off',
41
+ 'import-x/namespace': 'off',
42
+ 'import-x/default': 'off',
43
+ 'import-x/export': 'off',
44
+ /*
45
+ * Same resolution caveat, and also the two most expensive rules in the recommended set
46
+ * (they parse every imported module looking for its named exports).
47
+ */
48
+ 'import-x/no-named-as-default': 'off',
49
+ 'import-x/no-named-as-default-member': 'off',
50
+ 'import-x/no-default-export': 'warn', // relaxed for conventional files below
51
+ },
52
+ },
53
+ {
54
+ name: 'Default export overrides',
55
+ // files that legitimately default-export (framework/tooling conventions)
56
+ files: [
57
+ '**/*.config.*',
58
+ `**/*.stories.${tsExts}`,
59
+ `**/.storybook/main.${tsExts}`,
60
+ `**/.storybook/preview.${tsExts}`,
61
+ '**/.lintstagedrc*',
62
+ '**/.prettierrc*',
63
+ `**/App.${tsExts}`,
64
+ `**/index.${tsExts}`,
65
+ `**/main.${tsExts}`,
66
+ '**/*.d.ts',
67
+ `**/default.${tsExts}`,
68
+ `**/error.${tsExts}`,
69
+ `**/forbidden.${tsExts}`,
70
+ `**/global-error.${tsExts}`,
71
+ `**/layout.${tsExts}`,
72
+ `**/loading.${tsExts}`,
73
+ `**/not-found.${tsExts}`,
74
+ `**/page.${tsExts}`,
75
+ `**/template.${tsExts}`,
76
+ `**/unauthorized.${tsExts}`,
77
+ `**/apple-icon.${tsExts}`,
78
+ `**/icon.${tsExts}`,
79
+ `**/manifest.${tsExts}`,
80
+ `**/opengraph-image.${tsExts}`,
81
+ `**/robots.${tsExts}`,
82
+ `**/sitemap.${tsExts}`,
83
+ `**/twitter-image.${tsExts}`,
84
+ ],
85
+ rules: {
86
+ /*
87
+ * Stories always default-export `meta`, and story exports (`Default`, `WithArgs`, ...) are PascalCase by
88
+ * Storybook's own convention, which the general rules disallow. The stray naming-convention entry is
89
+ * deliberately out of place here - the rule itself lives in typescriptTypeAware.js, which
90
+ * defineLintConfig orders BEFORE this block precisely so this exemption wins (flat config is
91
+ * last-wins).
92
+ */
93
+ 'import-x/no-default-export': 'off',
94
+ '@typescript-eslint/naming-convention': 'off',
95
+ },
96
+ },
97
+ ];
98
+ }
99
+
100
+ /**
101
+ * Deterministic import ordering.
102
+ *
103
+ * @returns {import('eslint').Linter.Config[]}
104
+ */
105
+ export function importSortConfig() {
106
+ return [
107
+ {
108
+ name: 'eslint-plugin-simple-import-sort',
109
+ files: [`**/*.${tsExts}`],
110
+ plugins: { 'simple-import-sort': simpleImportSortPlugin },
111
+ rules: {
112
+ /*
113
+ * Side-effect imports (polyfills, CSS) ARE sorted into their group; the sorter only
114
+ * preserves the relative order of multiple side-effect imports that land in the SAME
115
+ * group (so order-dependent side effects stay put). Non-import code between imports
116
+ * splits them into independently-sorted chunks (standard simple-import-sort behavior).
117
+ */
118
+ 'simple-import-sort/imports': [
119
+ 'error',
120
+ {
121
+ groups: [
122
+ // 1. Polyfills - side-effect imports that must run first
123
+ ['^\\u0000.*(polyfill|core-js|regenerator-runtime|whatwg-fetch|@vitest/web-worker)'],
124
+ // 2. React
125
+ ['^react(-dom)?(/|$)'],
126
+ // 3. Third-party packages (node: builtins + npm packages)
127
+ ['^node:', '^@?\\w'],
128
+ // 4. Local imports - path aliases then relative
129
+ ['^@/', '^\\.'],
130
+ // 5. CSS/styles from libraries (side-effect, package path)
131
+ ['^\\u0000@?\\w'],
132
+ // 6. Local CSS/styles (side-effect, relative path)
133
+ ['^\\u0000'],
134
+ ],
135
+ },
136
+ ],
137
+ },
138
+ },
139
+ ];
140
+ }
141
+
142
+ /**
143
+ * Autofixable removal of unused imports.
144
+ *
145
+ * @returns {import('eslint').Linter.Config[]}
146
+ */
147
+ export function unusedImportsConfig() {
148
+ return [
149
+ {
150
+ name: 'eslint-plugin-unused-imports',
151
+ plugins: { 'unused-imports': unusedImportsPlugin },
152
+ rules: {
153
+ /*
154
+ * Unlike `@typescript-eslint/no-unused-vars/core` `no-unused-vars`, this rule is
155
+ * autofixable - `--fix` deletes the unused import specifier (or the whole import
156
+ * statement if nothing from it is used) instead of just reporting it.
157
+ */
158
+ 'unused-imports/no-unused-imports': 'error',
159
+ },
160
+ },
161
+ ];
162
+ }
@@ -0,0 +1,179 @@
1
+ import { dirname } from 'node:path';
2
+ import nextTs from 'eslint-config-next/typescript';
3
+ import jsxA11yPlugin from 'eslint-plugin-jsx-a11y';
4
+ import reactPlugin from 'eslint-plugin-react';
5
+ import reactHooksPlugin from 'eslint-plugin-react-hooks';
6
+
7
+ import { asOptions, GLOBAL_IGNORES, hasNext, scanWorkspace, tsExts } from '../lib.js';
8
+
9
+ // lazy so consumers without Next don't pay the load cost - re-exported from index.js
10
+ export const nextPlugin = hasNext ? (await import('@next/eslint-plugin-next')).default : null;
11
+
12
+ /** @typedef {import('../index.js').NextOptions} NextOptions Defined in index.d.ts. */
13
+
14
+ /**
15
+ * Auto-find Next.js app roots: every directory below the workspace root containing a
16
+ * `next.config.*` (scanned like the Tailwind entry - see `scanWorkspace`).
17
+ *
18
+ * @param {string[]} ignores glob patterns to skip
19
+ * @returns {string[]} absolute directories
20
+ */
21
+ export function findNextRoots(ignores) {
22
+ // Set: a dir can hold several matches (next.config.js + next.config.ts mid-migration);
23
+ // sorted so the emitted settings block is deterministic across filesystems
24
+ return [...new Set(scanWorkspace('next.config.*', ignores).map((file) => dirname(file)))].sort();
25
+ }
26
+
27
+ /**
28
+ * Next.js blocks: the whole `eslint-config-next` flat config, plus `settings.next.rootDir`.
29
+ *
30
+ * `rootDir` is auto-detected via {@link findNextRoots} when omitted: zero apps found → no settings
31
+ * block (the setting is optional and the plugin works without it - NOT an error, unlike the
32
+ * Tailwind entry); one or several → ALL of them (`settings.next.rootDir` accepts an array -
33
+ * pointing at just one app would break linting of the others).
34
+ *
35
+ * `eslint-config-next`'s own parser module does `require('next/dist/compiled/babel/eslint-parser')` -
36
+ * a file INSIDE the `next` package itself - so merely *importing* `eslint-config-next` crashes if
37
+ * `next` isn't installed at all (verified empirically: it throws "Cannot find module
38
+ * 'next/dist/compiled/babel/eslint-parser'" the instant the module loads). Hence the lazy import
39
+ * here; when the block is forced on without `next` around, that error IS the failure mode.
40
+ *
41
+ * @param {NextOptions} [options]
42
+ * @returns {Promise<import('eslint').Linter.Config[]>}
43
+ */
44
+ export async function nextBaseConfig({ rootDir = findNextRoots(GLOBAL_IGNORES) } = {}) {
45
+ const next = (await import('eslint-config-next')).default;
46
+ return [
47
+ ...next,
48
+ // eslint-config-next already registers the @next/next plugin, only the settings are needed
49
+ ...(rootDir?.length ? [{ name: '@next/eslint-plugin-next settings', settings: { next: { rootDir } } }] : []),
50
+ ];
51
+ }
52
+
53
+ /**
54
+ * Non-Next React projects - this config is also used for Vite+React apps - still want React/React
55
+ * Hooks/jsx-a11y linting, which `eslint-config-next` normally provides but only via the Next-specific
56
+ * parser. Cover the same ground directly instead, with whatever parser is already active
57
+ * (typescript-eslint for .ts/.tsx via typescriptConfig, the default parser otherwise).
58
+ *
59
+ * @returns {import('eslint').Linter.Config[]}
60
+ */
61
+ export function reactConfig() {
62
+ return [
63
+ reactPlugin.configs.flat.recommended,
64
+ reactPlugin.configs.flat['jsx-runtime'],
65
+ reactHooksPlugin.configs.flat['recommended-latest'],
66
+ jsxA11yPlugin.flatConfigs.recommended,
67
+ ];
68
+ }
69
+
70
+ /**
71
+ * Composite: {@link nextBaseConfig} when Next is enabled (auto-detected or forced via the flag),
72
+ * the {@link reactConfig} fallback otherwise.
73
+ *
74
+ * @param {boolean | NextOptions} [option] the defineLintConfig `next` flag
75
+ * @returns {Promise<import('eslint').Linter.Config[]>}
76
+ */
77
+ export async function nextConfig(option) {
78
+ const { enabled = hasNext, ...options } = asOptions(option);
79
+ return enabled ? await nextBaseConfig(options) : reactConfig();
80
+ }
81
+
82
+ /**
83
+ * TypeScript blocks - lives here because the wiring stems from `eslint-config-next/typescript`
84
+ * (typescript-eslint recommended setup, useful with or without Next itself) + deliberate overrides
85
+ * of its rule set.
86
+ *
87
+ * @returns {import('eslint').Linter.Config[]}
88
+ */
89
+ export function typescriptOverridesConfig() {
90
+ return [
91
+ ...nextTs,
92
+ {
93
+ name: '@typescript-eslint overrides',
94
+ files: [`**/*.${tsExts}`],
95
+ rules: {
96
+ '@typescript-eslint/explicit-module-boundary-types': 'off',
97
+ '@typescript-eslint/no-empty-function': 'off',
98
+ '@typescript-eslint/no-explicit-any': 'off',
99
+ '@typescript-eslint/no-require-imports': 'off',
100
+ '@typescript-eslint/no-unused-vars': 'off', // superseded by 'unused-imports/no-unused-imports', which is actually autofixable
101
+ '@typescript-eslint/consistent-type-definitions': ['error', 'type'],
102
+ '@typescript-eslint/consistent-type-imports': [
103
+ 'error',
104
+ { prefer: 'type-imports', fixStyle: 'inline-type-imports' },
105
+ ],
106
+ '@typescript-eslint/ban-ts-comment': [
107
+ 'error',
108
+ {
109
+ 'ts-expect-error': 'allow-with-description',
110
+ 'ts-ignore': true,
111
+ 'ts-nocheck': true,
112
+ 'ts-check': false,
113
+ minimumDescriptionLength: 3,
114
+ },
115
+ ],
116
+ /*
117
+ * `as const` is the mechanical half of "Prefer `as const` and `readonly` for immutable
118
+ * constants and objects" - the `readonly` half is a per-case judgment call (which objects
119
+ * deserve it), so that guidance stays in typescript.md instead of being lint-enforced here.
120
+ */
121
+ '@typescript-eslint/prefer-as-const': 'error',
122
+ },
123
+ },
124
+ {
125
+ name: '@typescript-eslint declaration-file overrides',
126
+ files: ['**/*.d.ts'],
127
+ rules: {
128
+ /*
129
+ * `typeof import('pkg')` annotations are the standard mechanism in declaration files
130
+ * (tsc itself emits them when generating .d.ts) - the annotation ban of
131
+ * consistent-type-imports is meant for source files.
132
+ */
133
+ '@typescript-eslint/consistent-type-imports': [
134
+ 'error',
135
+ { prefer: 'type-imports', fixStyle: 'inline-type-imports', disallowTypeAnnotations: false },
136
+ ],
137
+ },
138
+ },
139
+ ];
140
+ }
141
+
142
+ /**
143
+ * Overrides of rules set by `eslint-config-next`. Always applied (not gated on Next): the
144
+ * jsx-a11y/react entries matter for {@link reactConfig} consumers too, and turning off rules of an
145
+ * unregistered plugin is harmless.
146
+ *
147
+ * @returns {import('eslint').Linter.Config[]}
148
+ */
149
+ export function nextOverridesConfig() {
150
+ return [
151
+ {
152
+ name: 'eslint-config-next overrides',
153
+ rules: {
154
+ '@next/next/no-html-link-for-pages': 'off',
155
+ '@next/next/no-img-element': 'off',
156
+ 'import/no-anonymous-default-export': 'off', // overrides eslint-config-next's own default
157
+ 'jsx-a11y/alt-text': 'off',
158
+ 'react/prop-types': 'off', // ts does it statically
159
+ },
160
+ },
161
+ ];
162
+ }
163
+
164
+ /**
165
+ * FIXME ESLint 10 + Next fix
166
+ * https://github.com/vercel/next.js/issues/89764
167
+ * https://gist.github.com/OscarGauss/1f305edf5b7c103bb2ee32ba479f4261
168
+ *
169
+ * @returns {import('eslint').Linter.Config[]}
170
+ */
171
+ export function reactSettingsConfig() {
172
+ return [
173
+ {
174
+ settings: {
175
+ react: { version: '19' },
176
+ },
177
+ },
178
+ ];
179
+ }