eslint-config-axkit 1.1.0 → 1.2.0

package/dist/base-config.d.ts

@@ -0,0 +1,2 @@
+import type { Linter } from "eslint";
+export declare const baseConfig: Linter.Config;

package/dist/base-config.js

@@ -0,0 +1,76 @@
+import globals from "globals";
+export const baseConfig = {
+    name: "axkit/base",
+    files: ["**/*.{js,mjs,cjs,ts,tsx,mts,cts}"],
+    languageOptions: {
+        globals: globals.node,
+        parserOptions: {
+            projectService: true,
+        },
+    },
+    rules: {
+        // Security rules
+        "no-eval": "error",
+        "no-new-func": "error",
+        "no-script-url": "error",
+        // Correctness rules
+        "no-return-assign": ["error", "always"],
+        radix: ["error", "as-needed"],
+        "guard-for-in": "error",
+        "prefer-object-has-own": "error",
+        // Clarity rules
+        "prefer-regex-literals": ["error", { disallowRedundantWrapping: true }],
+        "require-unicode-regexp": "error",
+        "no-extend-native": "error",
+        "no-new-wrappers": "error",
+        "no-implicit-coercion": ["error", { allow: ["!!"] }],
+        // Allow numbers in template literals (safe and common)
+        "@typescript-eslint/restrict-template-expressions": [
+            "error",
+            { allowNumber: true },
+        ],
+        // Disallow value-returning functions where void-returning expected
+        "@typescript-eslint/strict-void-return": "error",
+        // Disallow unused private class members (extends ESLint rule for TS private keyword)
+        "@typescript-eslint/no-unused-private-class-members": "error",
+        // ===== ESLint Core Bug Prevention =====
+        // Catch missing returns in array methods (.map, .filter, etc.)
+        "array-callback-return": ["error", { allowImplicit: false }],
+        // Constructors shouldn't return values
+        "no-constructor-return": "error",
+        // Returns in Promise executors are meaningless
+        "no-promise-executor-return": "error",
+        // Comparing variable to itself is always a bug
+        "no-self-compare": "error",
+        // Catch template literal syntax in regular strings
+        "no-template-curly-in-string": "error",
+        // Loops that only run once are bugs
+        "no-unreachable-loop": "error",
+        // Infinite loop detection (loop condition never changes)
+        "no-unmodified-loop-condition": "error",
+        // Dead code - assignments never read
+        "no-useless-assignment": "error",
+        // Race condition detection in async code
+        "require-atomic-updates": "error",
+        // Require === and !== (allow == null for null/undefined check)
+        eqeqeq: ["error", "always", { null: "ignore" }],
+        // Comma operator is confusing
+        "no-sequences": "error",
+        // ===== TypeScript-ESLint Enhancements =====
+        // Ensure switch statements handle all enum/union cases
+        "@typescript-eslint/switch-exhaustiveness-check": "error",
+        // Use ?. instead of && chains (safer and cleaner)
+        "@typescript-eslint/prefer-optional-chain": "error",
+        // Require compare function for sort() to prevent string sorting bugs
+        "@typescript-eslint/require-array-sort-compare": "error",
+        // Prevent confusing ! placement next to == or !=
+        "@typescript-eslint/no-confusing-non-null-assertion": "error",
+        // Enforce import type for type-only imports
+        "@typescript-eslint/consistent-type-imports": [
+            "error",
+            { prefer: "type-imports" },
+        ],
+        // Enforce export type for type-only exports
+        "@typescript-eslint/consistent-type-exports": "error",
+    },
+};

package/dist/import-optional.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Dynamically import an optional dependency from the consumer's project.
+ *
+ * Uses `createRequire(cwd)` to resolve the module from the consumer's
+ * node_modules (not from this package), then `import()` the resolved path.
+ * This ensures transitive dependencies (e.g. `next` for `eslint-config-next`)
+ * are accessible.
+ */
+export declare function importOptional(name: string): Promise<unknown>;

package/dist/import-optional.js

@@ -0,0 +1,30 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+/**
+ * Dynamically import an optional dependency from the consumer's project.
+ *
+ * Uses `createRequire(cwd)` to resolve the module from the consumer's
+ * node_modules (not from this package), then `import()` the resolved path.
+ * This ensures transitive dependencies (e.g. `next` for `eslint-config-next`)
+ * are accessible.
+ */
+export async function importOptional(name) {
+    const require = createRequire(`${process.cwd()}/`);
+    let resolvedPath;
+    try {
+        resolvedPath = require.resolve(name);
+    }
+    catch {
+        throw new Error(`eslint-config-axkit: "${name}" must be installed to use this option. Run: pnpm add -D ${name}`);
+    }
+    const imported = (await import(__rewriteRelativeImportExtension(pathToFileURL(resolvedPath).href)));
+    return imported["default"] ?? imported;
+}

package/dist/index.d.ts

@@ -5,9 +5,20 @@ export type Options = {
      * will be added to ESLint's ignore list.
      */
     gitignorePath?: string;
+    /**
+     * Enable Next.js rules (eslint-config-next core-web-vitals + typescript).
+     * Includes React, React Hooks, JSX accessibility, and Next.js-specific rules.
+     * Requires `eslint-config-next` to be installed.
+     */
+    nextjs?: boolean;
+    /**
+     * Enable Storybook rules (eslint-plugin-storybook flat/recommended).
+     * Requires `eslint-plugin-storybook` to be installed.
+     */
+    storybook?: boolean;
 };
 /**
- * Creates a complete ESLint flat config for TypeScript + Node.js projects.
+ * Creates a complete ESLint flat config for TypeScript projects.
  *
  * Includes:
  * - ESLint recommended rules
@@ -15,6 +26,9 @@ export type Options = {
  * - Unicorn plugin (recommended)
  * - Vitest plugin for test files
  * - Prettier compatibility (disables conflicting rules)
+ *
+ * Optional:
+ * - Next.js rules (core-web-vitals + typescript) via `nextjs: true`
+ * - Storybook rules (flat/recommended) via `storybook: true`
  */
-export declare function axkit(options?: Options): Linter.Config[];
-export default axkit;
+export declare function axkit(options?: Options): Promise<Linter.Config[]>;

package/dist/index.js

@@ -1,12 +1,13 @@
 import js from "@eslint/js";
-import globals from "globals";
 import tseslint from "typescript-eslint";
 import { includeIgnoreFile } from "@eslint/compat";
 import eslintConfigPrettier from "eslint-config-prettier/flat";
-import vitest from "@vitest/eslint-plugin";
 import eslintPluginUnicorn from "eslint-plugin-unicorn";
+import { importOptional } from "./import-optional.js";
+import { baseConfig } from "./base-config.js";
+import { vitestConfig } from "./vitest-config.js";
 /**
- * Creates a complete ESLint flat config for TypeScript + Node.js projects.
+ * Creates a complete ESLint flat config for TypeScript projects.
  *
  * Includes:
  * - ESLint recommended rules
@@ -14,183 +15,57 @@ import eslintPluginUnicorn from "eslint-plugin-unicorn";
  * - Unicorn plugin (recommended)
  * - Vitest plugin for test files
  * - Prettier compatibility (disables conflicting rules)
+ *
+ * Optional:
+ * - Next.js rules (core-web-vitals + typescript) via `nextjs: true`
+ * - Storybook rules (flat/recommended) via `storybook: true`
  */
-export function axkit(options = {}) {
-    const { gitignorePath } = options;
+export async function axkit(options = {}) {
+    const { gitignorePath, nextjs, storybook } = options;
     const configs = [];
+    // ── Gitignore ──────────────────────────────────────────────────────
     if (gitignorePath) {
         configs.push(includeIgnoreFile(gitignorePath, "Copy patterns from .gitignore"));
     }
-    configs.push(
-    // ESLint recommended
-    js.configs.recommended, 
-    // TypeScript strict type checking
-    ...tseslint.configs.strictTypeChecked, 
-    // Base config for all JS/TS files
-    {
-        name: "axkit/base",
-        files: ["**/*.{js,mjs,cjs,ts,tsx,mts,cts}"],
-        languageOptions: {
-            globals: globals.node,
-            parserOptions: {
-                projectService: true,
-            },
-        },
-        rules: {
-            // Security rules
-            "no-eval": "error",
-            "no-new-func": "error",
-            "no-script-url": "error",
-            // Correctness rules
-            "no-return-assign": ["error", "always"],
-            radix: ["error", "as-needed"],
-            "guard-for-in": "error",
-            "prefer-object-has-own": "error",
-            // Clarity rules
-            "prefer-regex-literals": ["error", { disallowRedundantWrapping: true }],
-            "require-unicode-regexp": "error",
-            "no-extend-native": "error",
-            "no-new-wrappers": "error",
-            "no-implicit-coercion": ["error", { allow: ["!!"] }],
-            // Allow numbers in template literals (safe and common)
-            "@typescript-eslint/restrict-template-expressions": [
-                "error",
-                { allowNumber: true },
-            ],
-            // Disallow value-returning functions where void-returning expected
-            "@typescript-eslint/strict-void-return": "error",
-            // Disallow unused private class members (extends ESLint rule for TS private keyword)
-            "@typescript-eslint/no-unused-private-class-members": "error",
-            // ===== ESLint Core Bug Prevention =====
-            // Catch missing returns in array methods (.map, .filter, etc.)
-            "array-callback-return": ["error", { allowImplicit: false }],
-            // Constructors shouldn't return values
-            "no-constructor-return": "error",
-            // Returns in Promise executors are meaningless
-            "no-promise-executor-return": "error",
-            // Comparing variable to itself is always a bug
-            "no-self-compare": "error",
-            // Catch template literal syntax in regular strings
-            "no-template-curly-in-string": "error",
-            // Loops that only run once are bugs
-            "no-unreachable-loop": "error",
-            // Infinite loop detection (loop condition never changes)
-            "no-unmodified-loop-condition": "error",
-            // Dead code - assignments never read
-            "no-useless-assignment": "error",
-            // Race condition detection in async code
-            "require-atomic-updates": "error",
-            // Require === and !== (allow == null for null/undefined check)
-            eqeqeq: ["error", "always", { null: "ignore" }],
-            // Comma operator is confusing
-            "no-sequences": "error",
-            // ===== TypeScript-ESLint Enhancements =====
-            // Ensure switch statements handle all enum/union cases
-            "@typescript-eslint/switch-exhaustiveness-check": "error",
-            // Use ?. instead of && chains (safer and cleaner)
-            "@typescript-eslint/prefer-optional-chain": "error",
-            // Require compare function for sort() to prevent string sorting bugs
-            "@typescript-eslint/require-array-sort-compare": "error",
-            // Prevent confusing ! placement next to == or !=
-            "@typescript-eslint/no-confusing-non-null-assertion": "error",
-            // Enforce import type for type-only imports
-            "@typescript-eslint/consistent-type-imports": [
-                "error",
-                { prefer: "type-imports" },
-            ],
-            // Enforce export type for type-only exports
-            "@typescript-eslint/consistent-type-exports": "error",
-        },
-    }, 
-    // Unicorn plugin recommended config
-    eslintPluginUnicorn.configs.recommended, 
-    // Enable unicorn rules that are off by default
+    // ── Next.js (before base so axkit's strict rules override) ─────────
+    //
+    // When nextjs is enabled, we must use the consumer's typescript-eslint
+    // instance (resolved from CWD) rather than our own bundled copy.
+    // eslint-config-next registers the @typescript-eslint plugin, and ESLint
+    // forbids redefining a plugin with a different object identity.
+    let tseslintModule = tseslint;
+    if (nextjs) {
+        tseslintModule = (await importOptional("typescript-eslint"));
+        const [nextVitals, nextTs] = await Promise.all([
+            importOptional("eslint-config-next/core-web-vitals"),
+            importOptional("eslint-config-next/typescript"),
+        ]);
+        configs.push(...nextVitals, ...nextTs);
+    }
+    // ── Core configs ───────────────────────────────────────────────────
+    configs.push(js.configs.recommended, ...tseslintModule.configs.strictTypeChecked, baseConfig, eslintPluginUnicorn.configs.recommended, 
+    // Unicorn rules that are off by default
     {
         name: "axkit/unicorn-extras",
         files: ["**/*.{js,mjs,cjs,ts,tsx,mts,cts}"],
         rules: {
-            // Prefer import.meta.dirname/filename over fileURLToPath (Node.js 20.11+)
             "unicorn/prefer-import-meta-properties": "error",
-            // Optimize regex patterns (/[0-9]/ → /\d/)
             "unicorn/better-regex": "error",
-            // Ensure correct Error subclassing (this.name, no redundant this.message)
             "unicorn/custom-error-definition": "error",
-            // Catch unused object properties (dead code)
             "unicorn/no-unused-properties": "error",
-            // Consistent numeric literal casing (0xFF, 2e5)
             "unicorn/number-literal-case": "error",
         },
-    }, 
-    // Disable type-checking for config files
-    {
+    }, {
         name: "axkit/config-files",
         files: ["*.config.{js,ts,mjs,mts}"],
-        ...tseslint.configs.disableTypeChecked,
-    }, 
-    // Vitest rules for test files
-    {
-        name: "axkit/vitest",
-        files: [
-            "**/*.{test,spec}.{ts,tsx,js,mjs,cjs,mts,cts}",
-            "tests/**/*.{ts,tsx,js,mjs,cjs,mts,cts}",
-        ],
-        plugins: { vitest },
-        rules: {
-            ...vitest.configs.recommended.rules,
-            // Ensure expect.poll() and expect.element() are awaited
-            "vitest/require-awaited-expect-poll": "error",
-            // Keep vi.mock() and other hoisted APIs at the top of files
-            "vitest/hoisted-apis-on-top": "warn",
-            // Prefer toHaveBeenCalledTimes() matcher
-            "vitest/prefer-to-have-been-called-times": "warn",
-            // Prefer mockResolvedValue() over mockImplementation(() => Promise.resolve())
-            "vitest/prefer-mock-promise-shorthand": "warn",
-            // Prefer expectTypeOf() for type testing
-            "vitest/prefer-expect-type-of": "warn",
-            // Enforce consistent use of .each vs .for for parameterized tests
-            "vitest/consistent-each-for": "warn",
-            // Keep hooks (beforeEach, afterEach, etc.) at the top of describe blocks
-            "vitest/prefer-hooks-on-top": "warn",
-            // ===== Test Logic Errors =====
-            // No conditionals (if/else) inside test bodies - tests should be deterministic
-            "vitest/no-conditional-in-test": "error",
-            // No conditionally defined tests - tests should always run
-            "vitest/no-conditional-tests": "error",
-            // No return statements in tests - just execute assertions
-            "vitest/no-test-return-statement": "warn",
-            // No duplicate lifecycle hooks
-            "vitest/no-duplicate-hooks": "warn",
-            // ===== Better Matchers (auto-fixable) =====
-            // Use toBe() for primitives (strict equality)
-            "vitest/prefer-to-be": "warn",
-            // Use toHaveLength() instead of expect(arr.length).toBe()
-            "vitest/prefer-to-have-length": "warn",
-            // Use toContain() instead of expect(arr.includes()).toBe(true)
-            "vitest/prefer-to-contain": "warn",
-            // Use toBeGreaterThan(), toBeLessThan(), etc.
-            "vitest/prefer-comparison-matcher": "warn",
-            // Use dedicated equality matchers
-            "vitest/prefer-equality-matcher": "warn",
-            // ===== Best Practices =====
-            // Use vi.spyOn() instead of direct property assignment
-            "vitest/prefer-spy-on": "warn",
-            // Use test.todo() for empty/placeholder tests
-            "vitest/prefer-todo": "warn",
-            // Use expect().resolves instead of expect(await promise)
-            "vitest/prefer-expect-resolves": "warn",
-            // No deprecated alias methods (toBeCalled → toHaveBeenCalled)
-            "vitest/no-alias-methods": "warn",
-            // Use vi.mocked() instead of type casting
-            "vitest/prefer-vi-mocked": "warn",
-            // Use .only/.skip instead of f/x prefixes
-            "vitest/no-test-prefixes": "warn",
-        },
-        languageOptions: {
-            globals: { ...vitest.environments.env.globals },
-        },
-    }, 
-    // Prettier compatibility (must be last)
-    eslintConfigPrettier);
+        ...tseslintModule.configs.disableTypeChecked,
+    }, vitestConfig);
+    // ── Storybook (after base, before Prettier) ────────────────────────
+    if (storybook) {
+        const storybookPlugin = (await importOptional("eslint-plugin-storybook"));
+        configs.push(...storybookPlugin.configs["flat/recommended"]);
+    }
+    // ── Prettier compatibility (must be last) ──────────────────────────
+    configs.push(eslintConfigPrettier);
     return configs;
 }
-export default axkit;

package/dist/vitest-config.d.ts

@@ -0,0 +1,2 @@
+import type { Linter } from "eslint";
+export declare const vitestConfig: Linter.Config;

package/dist/vitest-config.js

@@ -0,0 +1,62 @@
+import vitest from "@vitest/eslint-plugin";
+export const vitestConfig = {
+    name: "axkit/vitest",
+    files: [
+        "**/*.{test,spec}.{ts,tsx,js,mjs,cjs,mts,cts}",
+        "tests/**/*.{ts,tsx,js,mjs,cjs,mts,cts}",
+    ],
+    plugins: { vitest },
+    rules: {
+        ...vitest.configs.recommended.rules,
+        // Ensure expect.poll() and expect.element() are awaited
+        "vitest/require-awaited-expect-poll": "error",
+        // Keep vi.mock() and other hoisted APIs at the top of files
+        "vitest/hoisted-apis-on-top": "warn",
+        // Prefer toHaveBeenCalledTimes() matcher
+        "vitest/prefer-to-have-been-called-times": "warn",
+        // Prefer mockResolvedValue() over mockImplementation(() => Promise.resolve())
+        "vitest/prefer-mock-promise-shorthand": "warn",
+        // Prefer expectTypeOf() for type testing
+        "vitest/prefer-expect-type-of": "warn",
+        // Enforce consistent use of .each vs .for for parameterized tests
+        "vitest/consistent-each-for": "warn",
+        // Keep hooks (beforeEach, afterEach, etc.) at the top of describe blocks
+        "vitest/prefer-hooks-on-top": "warn",
+        // ===== Test Logic Errors =====
+        // No conditionals (if/else) inside test bodies - tests should be deterministic
+        "vitest/no-conditional-in-test": "error",
+        // No conditionally defined tests - tests should always run
+        "vitest/no-conditional-tests": "error",
+        // No return statements in tests - just execute assertions
+        "vitest/no-test-return-statement": "warn",
+        // No duplicate lifecycle hooks
+        "vitest/no-duplicate-hooks": "warn",
+        // ===== Better Matchers (auto-fixable) =====
+        // Use toBe() for primitives (strict equality)
+        "vitest/prefer-to-be": "warn",
+        // Use toHaveLength() instead of expect(arr.length).toBe()
+        "vitest/prefer-to-have-length": "warn",
+        // Use toContain() instead of expect(arr.includes()).toBe(true)
+        "vitest/prefer-to-contain": "warn",
+        // Use toBeGreaterThan(), toBeLessThan(), etc.
+        "vitest/prefer-comparison-matcher": "warn",
+        // Use dedicated equality matchers
+        "vitest/prefer-equality-matcher": "warn",
+        // ===== Best Practices =====
+        // Use vi.spyOn() instead of direct property assignment
+        "vitest/prefer-spy-on": "warn",
+        // Use test.todo() for empty/placeholder tests
+        "vitest/prefer-todo": "warn",
+        // Use expect().resolves instead of expect(await promise)
+        "vitest/prefer-expect-resolves": "warn",
+        // No deprecated alias methods (toBeCalled → toHaveBeenCalled)
+        "vitest/no-alias-methods": "warn",
+        // Use vi.mocked() instead of type casting
+        "vitest/prefer-vi-mocked": "warn",
+        // Use .only/.skip instead of f/x prefixes
+        "vitest/no-test-prefixes": "warn",
+    },
+    languageOptions: {
+        globals: { ...vitest.environments.env.globals },
+    },
+};

package/package.json

@@ -2,7 +2,7 @@
   "name": "eslint-config-axkit",
   "author": "Łukasz Jerciński",
   "license": "MIT",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Reusable ESLint flat config for TypeScript + Node.js projects with strict type checking, Prettier, Unicorn, and Vitest",
   "repository": {
     "type": "git",
@@ -53,33 +53,43 @@
     "vitest",
     "axkit"
   ],
-  "packageManager": "pnpm@10.26.1",
+  "packageManager": "pnpm@10.30.1",
   "engines": {
     "node": ">=22.14.0"
   },
   "peerDependencies": {
-    "eslint": ">=9"
+    "eslint": ">=10",
+    "eslint-config-next": ">=16",
+    "eslint-plugin-storybook": ">=10"
+  },
+  "peerDependenciesMeta": {
+    "eslint-config-next": {
+      "optional": true
+    },
+    "eslint-plugin-storybook": {
+      "optional": true
+    }
   },
   "dependencies": {
-    "@eslint/compat": "^2.0.1",
-    "@eslint/js": "^9.39.2",
-    "@vitest/eslint-plugin": "^1.6.6",
+    "@eslint/compat": "^2.0.2",
+    "@eslint/js": "^10.0.1",
+    "@vitest/eslint-plugin": "^1.6.9",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-unicorn": "^62.0.0",
-    "globals": "^17.0.0",
-    "typescript-eslint": "^8.53.0"
+    "eslint-plugin-unicorn": "^63.0.0",
+    "globals": "^17.3.0",
+    "typescript-eslint": "^8.56.0"
   },
   "devDependencies": {
     "@total-typescript/ts-reset": "^0.6.1",
-    "@types/node": "^25.0.9",
-    "@vitest/coverage-v8": "^4.0.17",
-    "eslint": "^9.39.2",
+    "@types/node": "^25.3.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^10.0.0",
     "fta-check": "^1.5.1",
     "fta-cli": "^3.0.0",
-    "knip": "^5.81.0",
-    "prettier": "3.7.4",
-    "semantic-release": "^25.0.2",
+    "knip": "^5.84.1",
+    "prettier": "3.8.1",
+    "semantic-release": "^25.0.3",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.17"
+    "vitest": "^4.0.18"
   }
 }