@etchteam/eslint-config 2.2.201 → 2.6.0

package/AGENTS.md

@@ -0,0 +1,154 @@
+# AGENTS.md
+
+This file provides guidance to AI Agents when working with code in this repository.
+
+## Project Overview
+
+This is `@etchteam/eslint-config`, a shareable ESLint configuration package used by [Etch](https://etch.co). It provides modular, composable ESLint configurations for JavaScript, TypeScript, React, Angular, Next.js, Preact, Web Components, Node.js, and NestJS projects using ESLint 9's flat config format.
+
+## Development Commands
+
+### Linting
+```bash
+# Lint the source code
+npx eslint src
+
+# Lint with auto-fix
+npx eslint src --fix
+
+# Test the config against test files (should produce errors)
+npx eslint test-files/
+```
+
+### Release
+```bash
+# Create a new release (runs semantic-release)
+npm run release
+```
+
+Note: There are no unit tests in this project. Testing is done by running ESLint against the `test-files/` directory, which should intentionally produce linting errors to verify the config rules work.
+
+## Architecture
+
+### Modular Config Structure
+
+The configuration is split into composable modules:
+
+```
+src/
+├── index.mjs                    # Default export (full config) + named exports
+├── base.mjs                     # Core: JS, TS, security, imports, prettier
+├── configs/
+│   ├── json.mjs                 # JSON file linting
+│   ├── yaml.mjs                 # YAML file linting
+│   ├── storybook.mjs            # Storybook linting
+│   ├── react.mjs                # React + jsx-a11y
+│   └── environments/
+│       ├── nextjs.mjs           # Next.js (base + react + Next.js rules)
+│       ├── nodejs.mjs           # Node.js (base, no React)
+│       ├── angular.mjs          # Angular (base + angular-eslint)
+│       ├── preact.mjs           # Preact (base + react modified)
+│       ├── web-components.mjs   # Lit/Web Components
+│       └── nestjs.mjs           # NestJS (base + nestjs rules)
+├── utils/
+│   └── fixup.mjs                # Shared fixupPluginRules helper
+└── types.d.ts                   # TypeScript definitions
+```
+
+### Config Composition
+
+**Default export** (`src/index.mjs`): Backwards-compatible full config = `base + json + yaml + storybook + react`
+
+**Named exports** for composition:
+- `base`, `json`, `yaml`, `storybook`, `react` - Individual modules
+- `nodejs`, `nextjs`, `preact`, `angular`, `webComponents`, `nestjs` - Self-contained environment configs
+
+**Package.json exports map** provides direct imports:
+- `@etchteam/eslint-config` - Default (full config)
+- `@etchteam/eslint-config/base` - Base only
+- `@etchteam/eslint-config/nextjs` - Next.js environment
+- etc.
+
+### ESLint 9 Flat Config
+
+This config uses ESLint 9's flat config format exclusively:
+
+- **Compatibility layer**: `src/utils/fixup.mjs` wraps plugins that don't support flat config yet (import, jsx-a11y, you-dont-need-lodash-underscore, react)
+- **Native flat config plugins**: unused-imports, typescript-eslint, security, yml, storybook, json
+- **Parser configuration**: TypeScript ESLint parser in `languageOptions`
+
+### Dependencies
+
+**Core dependencies** (always installed):
+- `@eslint/compat`, `@eslint/js`, `typescript-eslint`
+- `eslint-plugin-security`, `eslint-plugin-import`, `eslint-plugin-unused-imports`
+- `eslint-plugin-prettier`, `eslint-config-prettier`
+- `eslint-plugin-json`, `eslint-plugin-yml`, `eslint-plugin-storybook`
+- `eslint-import-resolver-typescript`, `globals`
+
+**Optional dependencies** (for environment-specific configs):
+- `eslint-plugin-react`, `eslint-plugin-jsx-a11y` - React/Preact/Next.js
+- `@next/eslint-plugin-next`, `eslint-plugin-react-hooks` - Next.js
+- `angular-eslint` - Angular
+- `eslint-plugin-lit` - Web Components
+- `@darraghor/eslint-plugin-nestjs-typed` - NestJS
+
+### Key Rules
+
+- **Unused imports**: Enforced via `eslint-plugin-unused-imports`
+- **Import ordering**: Alphabetical with newlines between groups, `@/` paths treated as parent group
+- **TypeScript**: `no-explicit-any` is warning (not error), unused vars are errors
+- **React**: Forbids `<b>` and `<i>` elements, enforces read-only props, no useless fragments
+- **Accessibility**: Includes extended jsx-a11y rules beyond the preset
+- **Security**: Uses recommended config with `detect-object-injection` disabled
+- **Prettier**: Single quotes enforced, integrated via `eslint-plugin-prettier`
+
+## Git Workflow
+
+### Commit Messages
+
+This repo uses [Conventional Commits](https://www.conventionalcommits.org/) enforced by commitlint:
+- Format: `type(scope): description`
+- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+- Validated by husky pre-commit hook running commitlint
+
+### Semantic Release
+
+- Automatic versioning and publishing via semantic-release
+- Runs on push to `main` branch via `.github/workflows/publish.yml`
+- Release configuration in `release.config.js`
+- Generates CHANGELOG.md automatically
+- Publishes to npm with provenance
+
+### Git Hooks
+
+Husky hooks are configured in `.husky/`:
+- **pre-commit**: Runs `lint-staged` which executes `eslint --fix` on staged files matching `*.{ts,tsx,js,jsx,yml,yaml,json}`
+- **commit-msg**: Validates commit messages with commitlint
+
+Note: `HUSKY=0` environment variable disables hooks in CI.
+
+## CI/CD
+
+### CI Pipeline (`.github/workflows/ci.yml`)
+- Runs on pull requests
+- Tests against Node.js 18, 20, 22
+- Lints source code with `npx eslint src`
+- Validates config against `test-files/` (expects violations to prove rules work)
+
+### Publish Pipeline (`.github/workflows/publish.yml`)
+- Runs on push to `main`
+- Uses semantic-release to determine version, generate changelog, and publish
+- Requires `NPM_TOKEN` secret for publishing
+
+## Test Strategy
+
+This package uses a unique testing approach:
+- `test-files/` directory contains intentionally badly-formatted code
+- CI runs ESLint against these files and expects failures
+- If ESLint passes on test files, the CI fails (proves rules aren't working)
+- This validates that the config actually enforces the expected rules
+
+## Mergify Configuration
+
+Auto-merge is configured in `.github/mergify.yml` for Dependabot PRs that pass CI.

package/CHANGELOG.md

@@ -1,6 +1,3 @@
-## [2.2.201](https://github.com/etchteam/eslint/compare/v2.2.200...v2.2.201) (2026-01-06)
+## 2.6.0 (2026-01-28)
 
-
-### Bug Fixes
-
-* bump @typescript-eslint/parser from 8.51.0 to 8.52.0 ([5810ff2](https://github.com/etchteam/eslint/commit/5810ff2f6bbdabe90146ed0d46feafa6d0273679))
+* feat: upgrade to node 24 and set up node in publish ([0b5c3a4](https://github.com/etchteam/eslint/commit/0b5c3a4))

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/README.md

@@ -20,9 +20,103 @@ import etchConfig from '@etchteam/eslint-config';
 export default etchConfig;
 ```
 
-### With lint-staged
+## Environment-Specific Configs
 
-#### New project
+For projects that don't need the full config, use environment-specific imports to reduce dependencies:
+
+### Next.js
+
+```javascript
+import nextjs from '@etchteam/eslint-config/nextjs';
+
+export default nextjs;
+```
+
+### Node.js / Express
+
+```javascript
+import nodejs from '@etchteam/eslint-config/nodejs';
+
+export default nodejs;
+```
+
+### Angular
+
+```javascript
+import angular from '@etchteam/eslint-config/angular';
+
+export default angular;
+```
+
+### Preact
+
+```javascript
+import preact from '@etchteam/eslint-config/preact';
+
+export default preact;
+```
+
+### Web Components (Lit)
+
+```javascript
+import webComponents from '@etchteam/eslint-config/web-components';
+
+export default webComponents;
+```
+
+### NestJS
+
+```javascript
+import nestjs from '@etchteam/eslint-config/nestjs';
+
+export default nestjs;
+```
+
+## Composable Configs
+
+Build custom configs by combining individual modules:
+
+```javascript
+import { base, json, yaml, react } from '@etchteam/eslint-config';
+
+export default [
+  ...base,
+  ...json,
+  ...yaml,
+  ...react,
+  {
+    // Your custom overrides
+    rules: {
+      'react/prefer-read-only-props': 'warn',
+    },
+  },
+];
+```
+
+### Available Modules
+
+| Module | Description |
+|--------|-------------|
+| `base` | Core rules: JS, TypeScript, security, imports, prettier |
+| `json` | JSON file linting |
+| `yaml` | YAML file linting |
+| `storybook` | Storybook best practices |
+| `react` | React + JSX accessibility |
+
+### Environment Configs (Self-Contained)
+
+| Config | Includes |
+|--------|----------|
+| `nextjs` | base + json + yaml + storybook + react + Next.js rules |
+| `nodejs` | base + json + yaml + Node.js globals |
+| `angular` | base + json + yaml + storybook + Angular rules |
+| `preact` | base + json + yaml + storybook + react (Preact settings) |
+| `web-components` | base + json + yaml + storybook + Lit rules |
+| `nestjs` | base + json + yaml + NestJS rules + Jest globals |
+
+## With lint-staged
+
+### New project
 
 Run the following:
 
@@ -37,7 +131,7 @@ echo "npx --no-install -- lint-staged" > .husky/pre-commit
 
 ```
 
-#### Existing project with husky and lint staged
+### Existing project with husky and lint staged
 
 Add the following to your lint-staged config:
 
@@ -108,4 +202,4 @@ ESLint 9 uses flat config by default, so your existing npm scripts should work w
 - **Flat config format** - More explicit and performant
 - **ESLint 9 compatibility** - Latest features and fixes
 - **Updated plugins** - All plugins updated to latest versions
-- **Reduced compatibility layer** - Only 3 plugins need compatibility wrappers
+- **Modular configs** - Import only what you need for your environment

package/package.json

@@ -1,18 +1,30 @@
 {
   "name": "@etchteam/eslint-config",
-  "version": "2.2.201",
+  "version": "2.6.0",
   "description": "Etch's standard eslint config",
   "type": "module",
   "main": "src/index.mjs",
   "exports": {
-    ".": "./src/index.mjs"
+    ".": "./src/index.mjs",
+    "./base": "./src/base.mjs",
+    "./json": "./src/configs/json.mjs",
+    "./yaml": "./src/configs/yaml.mjs",
+    "./storybook": "./src/configs/storybook.mjs",
+    "./react": "./src/configs/react.mjs",
+    "./nodejs": "./src/configs/environments/nodejs.mjs",
+    "./nextjs": "./src/configs/environments/nextjs.mjs",
+    "./preact": "./src/configs/environments/preact.mjs",
+    "./angular": "./src/configs/environments/angular.mjs",
+    "./web-components": "./src/configs/environments/web-components.mjs",
+    "./nestjs": "./src/configs/environments/nestjs.mjs",
+    "./package.json": "./package.json"
   },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
     "release": "semantic-release"
   },
   "engines": {
-    "node": "^18 || ^20 || ^22"
+    "node": "^20 || ^22 || ^24"
   },
   "repository": {
     "type": "git",
@@ -34,28 +46,38 @@
     "lint-staged": "^16.0.0"
   },
   "dependencies": {
-    "@eslint/compat": "^1.3.0",
+    "@eslint/compat": "^2.0.1",
     "@eslint/js": "^9.29.0",
-    "@typescript-eslint/eslint-plugin": "^8.35.0",
-    "@typescript-eslint/parser": "^8.35.0",
-    "eslint": ">=9.0.0",
-    "eslint-config-next": "^16.0.0",
     "eslint-config-prettier": "^10.1.5",
+    "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-json": "^4.0.1",
-    "eslint-plugin-jsx-a11y": "^6.10.2",
     "eslint-plugin-prettier": "^5.5.0",
-    "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-security": "^3.0.1",
     "eslint-plugin-storybook": "^10.0.1",
     "eslint-plugin-unused-imports": "^4.1.3",
-    "eslint-plugin-yml": "^1.18.0",
+    "eslint-plugin-yml": "^3.0.0",
     "eslint-plugin-you-dont-need-lodash-underscore": "^6.14.0",
-    "prettier": ">=3.0.0",
+    "globals": "^16.0.0",
     "typescript-eslint": "^8.35.0"
   },
+  "optionalDependencies": {
+    "@darraghor/eslint-plugin-nestjs-typed": "^6.0.0",
+    "@next/eslint-plugin-next": "^15.0.0",
+    "angular-eslint": "^19.0.0",
+    "eslint-plugin-jsx-a11y": "^6.10.2",
+    "eslint-plugin-lit": "^1.15.0",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^5.0.0"
+  },
   "peerDependencies": {
     "eslint": ">=9.0.0",
-    "prettier": ">=3.0.0"
+    "prettier": ">=3.0.0",
+    "typescript": ">=4.8.4"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
   }
 }

package/src/base.mjs

@@ -0,0 +1,70 @@
+import js from '@eslint/js';
+import importPlugin from 'eslint-plugin-import';
+import prettier from 'eslint-plugin-prettier/recommended';
+import security from 'eslint-plugin-security';
+import unusedImports from 'eslint-plugin-unused-imports';
+import youDontNeedLodash from 'eslint-plugin-you-dont-need-lodash-underscore';
+import tseslint from 'typescript-eslint';
+
+import { fixupPluginRules } from './utils/fixup.mjs';
+
+/**
+ * Base ESLint configuration for all projects.
+ * Includes: JavaScript, TypeScript, security, import ordering, prettier, and common rules.
+ * Does NOT include: React, JSX accessibility, JSON, YAML, or Storybook configs.
+ */
+export default [
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  security.configs.recommended,
+  {
+    files: ['**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx}'],
+    plugins: {
+      'unused-imports': unusedImports,
+      import: fixupPluginRules(importPlugin),
+      'you-dont-need-lodash-underscore': fixupPluginRules(youDontNeedLodash),
+    },
+    languageOptions: {
+      parser: tseslint.parser,
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+    },
+    rules: {
+      'no-unused-vars': 'off',
+      '@typescript-eslint/no-unused-vars': 'error',
+      '@typescript-eslint/no-explicit-any': 'warn',
+      'unused-imports/no-unused-imports': 'error',
+      'unused-imports/no-unused-vars': 'off',
+      'import/order': [
+        'error',
+        {
+          'newlines-between': 'always',
+          alphabetize: {
+            order: 'asc',
+          },
+          pathGroups: [
+            {
+              pattern: '@/**',
+              group: 'parent',
+            },
+          ],
+        },
+      ],
+      'prettier/prettier': [
+        'error',
+        {
+          singleQuote: true,
+        },
+      ],
+      'security/detect-object-injection': 'off',
+      'spaced-comment': 'error',
+    },
+    settings: {
+      'import/resolver': {
+        typescript: true,
+        node: true,
+      },
+    },
+  },
+  prettier,
+];

package/src/configs/environments/angular.mjs

@@ -0,0 +1,53 @@
+import angular from 'angular-eslint';
+
+import base from '../../base.mjs';
+import json from '../json.mjs';
+import storybook from '../storybook.mjs';
+import yaml from '../yaml.mjs';
+
+/**
+ * Angular ESLint configuration.
+ * Includes: base + JSON + YAML + Storybook + Angular rules
+ *
+ * Usage:
+ * ```js
+ * import angular from '@etchteam/eslint-config/angular';
+ * export default angular;
+ * ```
+ */
+export default [
+  ...base,
+  ...json,
+  ...yaml,
+  ...storybook,
+  {
+    files: ['**/*.ts'],
+    extends: [...angular.configs.tsRecommended],
+    processor: angular.processInlineTemplates,
+    rules: {
+      '@angular-eslint/directive-selector': [
+        'error',
+        {
+          type: 'attribute',
+          prefix: 'app',
+          style: 'camelCase',
+        },
+      ],
+      '@angular-eslint/component-selector': [
+        'error',
+        {
+          type: 'element',
+          prefix: 'app',
+          style: 'kebab-case',
+        },
+      ],
+    },
+  },
+  {
+    files: ['**/*.html'],
+    extends: [
+      ...angular.configs.templateRecommended,
+      ...angular.configs.templateAccessibility,
+    ],
+  },
+];

package/src/configs/environments/nestjs.mjs

@@ -0,0 +1,31 @@
+import nestjs from '@darraghor/eslint-plugin-nestjs-typed';
+import globals from 'globals';
+
+import base from '../../base.mjs';
+import json from '../json.mjs';
+import yaml from '../yaml.mjs';
+
+/**
+ * NestJS ESLint configuration.
+ * Includes: base + JSON + YAML + NestJS rules + Node.js/Jest globals
+ *
+ * Usage:
+ * ```js
+ * import nestjs from '@etchteam/eslint-config/nestjs';
+ * export default nestjs;
+ * ```
+ */
+export default [
+  ...base,
+  ...json,
+  ...yaml,
+  {
+    languageOptions: {
+      globals: {
+        ...globals.node,
+        ...globals.jest,
+      },
+    },
+  },
+  nestjs.configs.flatRecommended,
+];

package/src/configs/environments/nextjs.mjs

@@ -0,0 +1,40 @@
+import nextPlugin from '@next/eslint-plugin-next';
+import reactHooks from 'eslint-plugin-react-hooks';
+
+import base from '../../base.mjs';
+import json from '../json.mjs';
+import react from '../react.mjs';
+import storybook from '../storybook.mjs';
+import yaml from '../yaml.mjs';
+
+/**
+ * Next.js ESLint configuration.
+ * Includes: base + JSON + YAML + Storybook + React + Next.js rules
+ *
+ * Usage:
+ * ```js
+ * import nextjs from '@etchteam/eslint-config/nextjs';
+ * export default nextjs;
+ * ```
+ */
+export default [
+  ...base,
+  ...json,
+  ...yaml,
+  ...storybook,
+  ...react,
+  {
+    plugins: {
+      '@next/next': nextPlugin,
+      'react-hooks': reactHooks,
+    },
+    rules: {
+      ...nextPlugin.configs.recommended.rules,
+      ...nextPlugin.configs['core-web-vitals'].rules,
+      ...reactHooks.configs.recommended.rules,
+      'import/no-anonymous-default-export': 'warn',
+      'react/react-in-jsx-scope': 'off',
+      'react/prop-types': 'off',
+    },
+  },
+];

package/src/configs/environments/nodejs.mjs

@@ -0,0 +1,27 @@
+import globals from 'globals';
+
+import base from '../../base.mjs';
+import json from '../json.mjs';
+import yaml from '../yaml.mjs';
+
+/**
+ * Node.js backend ESLint configuration.
+ * Includes: base + JSON + YAML + Node.js globals
+ * Does NOT include: React, Storybook
+ *
+ * Usage:
+ * ```js
+ * import nodejs from '@etchteam/eslint-config/nodejs';
+ * export default nodejs;
+ * ```
+ */
+export default [
+  ...base,
+  ...json,
+  ...yaml,
+  {
+    languageOptions: {
+      globals: globals.node,
+    },
+  },
+];

package/src/configs/environments/preact.mjs

@@ -0,0 +1,35 @@
+import base from '../../base.mjs';
+import json from '../json.mjs';
+import react from '../react.mjs';
+import storybook from '../storybook.mjs';
+import yaml from '../yaml.mjs';
+
+/**
+ * Preact ESLint configuration.
+ * Includes: base + JSON + YAML + Storybook + React (modified for Preact)
+ *
+ * Usage:
+ * ```js
+ * import preact from '@etchteam/eslint-config/preact';
+ * export default preact;
+ * ```
+ */
+export default [
+  ...base,
+  ...json,
+  ...yaml,
+  ...storybook,
+  ...react,
+  {
+    settings: {
+      react: {
+        pragma: 'h',
+        version: 'detect',
+      },
+    },
+    rules: {
+      'react/prop-types': 'off',
+      'react/react-in-jsx-scope': 'off',
+    },
+  },
+];

package/src/configs/environments/web-components.mjs

@@ -0,0 +1,24 @@
+import lit from 'eslint-plugin-lit';
+
+import base from '../../base.mjs';
+import json from '../json.mjs';
+import storybook from '../storybook.mjs';
+import yaml from '../yaml.mjs';
+
+/**
+ * Web Components (Lit) ESLint configuration.
+ * Includes: base + JSON + YAML + Storybook + Lit rules
+ *
+ * Usage:
+ * ```js
+ * import webComponents from '@etchteam/eslint-config/web-components';
+ * export default webComponents;
+ * ```
+ */
+export default [
+  ...base,
+  ...json,
+  ...yaml,
+  ...storybook,
+  lit.configs['flat/recommended'],
+];

package/src/configs/json.mjs

@@ -0,0 +1,11 @@
+import json from 'eslint-plugin-json';
+
+/**
+ * JSON file linting configuration.
+ */
+export default [
+  {
+    files: ['**/*.json'],
+    ...json.configs.recommended,
+  },
+];

package/src/configs/react.mjs

@@ -0,0 +1,42 @@
+import jsxA11y from 'eslint-plugin-jsx-a11y';
+import react from 'eslint-plugin-react';
+
+import { fixupPluginRules } from '../utils/fixup.mjs';
+
+/**
+ * React and JSX accessibility linting configuration.
+ */
+export default [
+  {
+    files: ['**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx}'],
+    plugins: {
+      react: fixupPluginRules(react),
+      'jsx-a11y': fixupPluginRules(jsxA11y),
+    },
+    rules: {
+      'jsx-a11y/anchor-ambiguous-text': 'error',
+      'jsx-a11y/no-aria-hidden-on-focusable': 'error',
+      'react/forbid-elements': [
+        'error',
+        {
+          forbid: [
+            { element: 'b', message: 'Do not use HTML for styling' },
+            { element: 'i', message: 'Do not use HTML for styling' },
+          ],
+        },
+      ],
+      'react/jsx-no-useless-fragment': [
+        'error',
+        {
+          allowExpressions: true,
+        },
+      ],
+      'react/prefer-read-only-props': 'error',
+    },
+    settings: {
+      react: {
+        version: 'detect',
+      },
+    },
+  },
+];

package/src/configs/storybook.mjs

@@ -0,0 +1,6 @@
+import storybook from 'eslint-plugin-storybook';
+
+/**
+ * Storybook linting configuration.
+ */
+export default storybook.configs['flat/recommended'];

package/src/configs/yaml.mjs

@@ -0,0 +1,6 @@
+import yml from 'eslint-plugin-yml';
+
+/**
+ * YAML file linting configuration.
+ */
+export default yml.configs['flat/recommended'];

package/src/index.mjs

@@ -1,101 +1,36 @@
-import { fixupPluginRules } from '@eslint/compat';
-import js from '@eslint/js';
-import importPlugin from 'eslint-plugin-import';
-import json from 'eslint-plugin-json';
-import jsxA11y from 'eslint-plugin-jsx-a11y';
-import prettier from 'eslint-plugin-prettier/recommended';
-import react from 'eslint-plugin-react';
-import security from 'eslint-plugin-security';
-import storybook from 'eslint-plugin-storybook';
-import unusedImports from 'eslint-plugin-unused-imports';
-import yml from 'eslint-plugin-yml';
-import youDontNeedLodash from 'eslint-plugin-you-dont-need-lodash-underscore';
-import tseslint from 'typescript-eslint';
+import base from './base.mjs';
+import json from './configs/json.mjs';
+import reactConfig from './configs/react.mjs';
+import storybook from './configs/storybook.mjs';
+import yaml from './configs/yaml.mjs';
 
-export default [
-  js.configs.recommended,
-  ...tseslint.configs.recommended,
-  security.configs.recommended,
-  ...yml.configs['flat/recommended'],
-  ...storybook.configs['flat/recommended'],
-  {
-    files: ['**/*.json'],
-    ...json.configs.recommended,
-  },
-  {
-    plugins: {
-      // Plugins with native flat config support
-      'unused-imports': unusedImports,
+// Named exports for composable configs
+export { default as base } from './base.mjs';
+export { default as json } from './configs/json.mjs';
+export { default as react } from './configs/react.mjs';
+export { default as storybook } from './configs/storybook.mjs';
+export { default as yaml } from './configs/yaml.mjs';
 
-      // Plugins requiring compatibility layer
-      import: fixupPluginRules(importPlugin),
-      'jsx-a11y': fixupPluginRules(jsxA11y),
-      'you-dont-need-lodash-underscore': fixupPluginRules(youDontNeedLodash),
-      react: fixupPluginRules(react),
-    },
-    languageOptions: {
-      parser: tseslint.parser,
-      ecmaVersion: 'latest',
-      sourceType: 'module',
-    },
-    rules: {
-      // Migrate existing rules from src/index.js
-      'no-unused-vars': 'off',
-      '@typescript-eslint/no-unused-vars': 'error',
-      '@typescript-eslint/no-explicit-any': 'warn',
-      'unused-imports/no-unused-imports': 'error',
-      'unused-imports/no-unused-vars': 'off',
-      'import/order': [
-        'error',
-        {
-          'newlines-between': 'always',
-          alphabetize: {
-            order: 'asc',
-          },
-          pathGroups: [
-            {
-              pattern: '@/**',
-              group: 'parent',
-            },
-          ],
-        },
-      ],
-      'prettier/prettier': [
-        'error',
-        {
-          singleQuote: true,
-        },
-      ],
-      'jsx-a11y/anchor-ambiguous-text': 'error',
-      'jsx-a11y/no-aria-hidden-on-focusable': 'error',
-      'security/detect-object-injection': 'off',
-      'react/forbid-elements': [
-        'error',
-        {
-          forbid: [
-            { element: 'b', message: 'Do not use HTML for styling' },
-            { element: 'i', message: 'Do not use HTML for styling' },
-          ],
-        },
-      ],
-      'react/jsx-no-useless-fragment': [
-        'error',
-        {
-          allowExpressions: true,
-        },
-      ],
-      'react/prefer-read-only-props': 'error',
-      'spaced-comment': 'error',
-    },
-    settings: {
-      'import/resolver': {
-        typescript: true,
-        node: true,
-      },
-      react: {
-        version: 'detect',
-      },
-    },
-  },
-  prettier, // Prettier recommended config
-];
+/**
+ * Default export - Full ESLint configuration (backwards compatible)
+ * Includes: base + JSON + YAML + Storybook + React
+ *
+ * Usage:
+ * ```js
+ * import etchConfig from '@etchteam/eslint-config';
+ * export default etchConfig;
+ * ```
+ *
+ * For environment-specific or composable usage, use named exports:
+ * ```js
+ * import { base, react } from '@etchteam/eslint-config';
+ * export default [...base, ...react];
+ * ```
+ *
+ * Or import specific environment configs:
+ * ```js
+ * import nextjs from '@etchteam/eslint-config/nextjs';
+ * export default nextjs;
+ * ```
+ */
+export default [...base, ...json, ...yaml, ...storybook, ...reactConfig];

package/src/types.d.ts

@@ -0,0 +1,72 @@
+import type { Linter } from 'eslint';
+
+type FlatConfigArray = Linter.Config[];
+
+/**
+ * Base ESLint configuration for all projects.
+ * Includes: JavaScript, TypeScript, security, import ordering, prettier, and common rules.
+ */
+export declare const base: FlatConfigArray;
+
+/**
+ * JSON file linting configuration.
+ */
+export declare const json: FlatConfigArray;
+
+/**
+ * YAML file linting configuration.
+ */
+export declare const yaml: FlatConfigArray;
+
+/**
+ * Storybook linting configuration.
+ */
+export declare const storybook: FlatConfigArray;
+
+/**
+ * React and JSX accessibility linting configuration.
+ */
+export declare const react: FlatConfigArray;
+
+/**
+ * Node.js backend ESLint configuration.
+ * Includes: base + JSON + YAML + Node.js globals
+ */
+export declare const nodejs: FlatConfigArray;
+
+/**
+ * Next.js ESLint configuration.
+ * Includes: base + JSON + YAML + Storybook + React + Next.js rules
+ */
+export declare const nextjs: FlatConfigArray;
+
+/**
+ * Preact ESLint configuration.
+ * Includes: base + JSON + YAML + Storybook + React (modified for Preact)
+ */
+export declare const preact: FlatConfigArray;
+
+/**
+ * Angular ESLint configuration.
+ * Includes: base + JSON + YAML + Storybook + Angular rules
+ */
+export declare const angular: FlatConfigArray;
+
+/**
+ * Web Components (Lit) ESLint configuration.
+ * Includes: base + JSON + YAML + Storybook + Lit rules
+ */
+export declare const webComponents: FlatConfigArray;
+
+/**
+ * NestJS ESLint configuration.
+ * Includes: base + JSON + YAML + NestJS rules + Node.js/Jest globals
+ */
+export declare const nestjs: FlatConfigArray;
+
+/**
+ * Default export - Full ESLint configuration (backwards compatible)
+ * Includes: base + JSON + YAML + Storybook + React
+ */
+declare const config: FlatConfigArray;
+export default config;

package/src/utils/fixup.mjs

@@ -0,0 +1,21 @@
+import { fixupPluginRules } from '@eslint/compat';
+
+/**
+ * Wraps plugins that don't yet support ESLint 9 flat config natively.
+ * This provides a centralized place to manage compatibility wrappers.
+ */
+export { fixupPluginRules };
+
+/**
+ * Helper to wrap multiple plugins at once
+ * @param {Record<string, object>} plugins - Object mapping plugin names to plugin modules
+ * @returns {Record<string, object>} - Object with wrapped plugins
+ */
+export function fixupPlugins(plugins) {
+  return Object.fromEntries(
+    Object.entries(plugins).map(([name, plugin]) => [
+      name,
+      fixupPluginRules(plugin),
+    ]),
+  );
+}