@od-oneapp/config 2026.2.2001-canary.1

package/README.md

@@ -0,0 +1,830 @@
+# @od-oneapp/config
+
+Shared configuration for ESLint, Stylelint, and Prettier in the OneApp monorepo, optimized for Next.js 16, React 19,
+TypeScript 5, Node.js 22, and Expo.
+
+**✨ Latest Optimizations:**
+
+- ⚛️ **React 19**: Full support for new hooks (`use`, `useActionState`, `useFormStatus`, `useOptimistic`)
+- 🟢 **Node.js 22**: ES2024 target, native Fetch API, WebSocket, and Web globals
+- 📦 **Single Source of Truth**: Prettier config re-exports from root (zero duplication)
+- 🎨 **Enhanced Stylelint**: Comprehensive CSS rules with Tailwind and CSS Modules support
+- 🔒 **Immutable Configs**: No side effects or mutations in config composition
+- ✅ **All Tests Passing**: 21/21 tests, full type safety, zero lint errors
+
+## 📦 Packages
+
+This package provides modular configurations organized by type:
+
+### ESLint Configurations
+
+- **Node** (`@od-oneapp/config/eslint/node`) - Node.js projects
+- **React** (`@od-oneapp/config/eslint/react`) - React 19.2 projects
+- **Next.js** (`@od-oneapp/config/eslint/next`) - Next.js 16 projects (extends React)
+- **Expo** (`@od-oneapp/config/eslint/expo`) - React Native/Expo projects (extends React)
+- **Storybook** (`@od-oneapp/config/eslint/storybook`) - Storybook v10 projects (extends Next.js)
+- **Test** (`@od-oneapp/config/eslint/test`) - Test files for Vitest, Cypress, and Playwright
+
+Note: Base config is internal-only and not exported.
+
+### Other Configurations
+
+- **Stylelint** (`@od-oneapp/config/stylelint`) - CSS linting
+- **Prettier** (`@od-oneapp/config/prettier`) - Code formatting
+
+## 🚀 Quick Start
+
+### Next.js 16 Projects
+
+```javascript
+// eslint.config.mjs
+import nextConfig from "@od-oneapp/config/eslint/next";
+
+export default nextConfig;
+```
+
+### React 19.2 Projects
+
+```javascript
+// eslint.config.mjs
+import reactConfig from "@od-oneapp/config/eslint/react";
+
+export default reactConfig;
+```
+
+### Expo/React Native Projects
+
+```javascript
+// eslint.config.mjs
+import expoConfig from "@od-oneapp/config/eslint/expo";
+
+export default expoConfig;
+```
+
+### Node.js / TypeScript Projects
+
+```javascript
+// eslint.config.mjs
+import nodeConfig from "@od-oneapp/config/eslint/node";
+
+export default nodeConfig;
+```
+
+### Storybook v10 Projects (with Next.js)
+
+```javascript
+// eslint.config.mjs
+import nextConfig from "@od-oneapp/config/eslint/next";
+import storybookConfig from "@od-oneapp/config/eslint/storybook";
+import testConfig from "@od-oneapp/config/eslint/test";
+
+// Merge configs - Storybook extends Next.js
+const config = [...nextConfig, ...storybookConfig, ...testConfig];
+export default config;
+```
+
+### Test Files (Vitest, Cypress, Playwright)
+
+The test config automatically applies to test files. Include it alongside your framework config:
+
+```javascript
+// eslint.config.mjs
+import nextConfig from "@od-oneapp/config/eslint/next";
+import testConfig from "@od-oneapp/config/eslint/test";
+
+const config = [...nextConfig, ...testConfig];
+export default config;
+```
+
+### Stylelint
+
+```javascript
+// stylelint.config.mjs
+export { default } from '@od-oneapp/config/stylelint';
+
+// Or with custom overrides
+import baseConfig from '@od-oneapp/config/stylelint';
+
+export default {
+  ...baseConfig,
+  rules: {
+    // Your overrides
+  }
+};
+```
+
+### Prettier
+
+```javascript
+// prettier.config.mjs
+export { default } from '@od-oneapp/config/prettier';
+
+// Or with custom overrides
+import baseConfig from '@od-oneapp/config/prettier';
+
+export default {
+  ...baseConfig,
+  printWidth: 120, // Your override
+};
+```
+
+**Note:** For `.prettierignore` patterns, use the root `/.prettierignore` file which is kept in sync with
+`eslint/shared/common-ignores.mjs`.
+
+## ? Features
+
+This configuration package provides **23 ESLint plugins** with comprehensive rules for security, testing, code quality,
+and framework-specific best practices.
+
+### React 19.2 Optimizations
+
+- React 19.2 version detection
+- Support for new hooks (`use`, `useActionState`, `useFormStatus`, `useOptimistic`)
+- React 19 concurrent features rules
+- JSX optimizations
+
+### Next.js 16 Optimizations
+
+- Next.js 16 App Router rules
+- Core Web Vitals enforcement
+- Next.js-specific best practices
+- Performance optimizations
+
+### Code Quality
+
+- **55+ Unicorn rules** - Code quality improvements from ESLint XO
+- **14 strict TypeScript rules** - Enhanced type safety (floating promises, nullish coalescing, optional chaining, etc.)
+- **14 React performance rules** - Fragment optimization, context values, nested components, etc.
+- **JSDoc plugin** - Documentation consistency checks (format and style)
+- **Storybook v10 rules** - Storybook-specific linting rules
+- **Test framework support** - Vitest, Cypress, and Playwright test file linting
+- **Import organization** - Consistent import ordering with React/Next.js prioritization
+- **TypeScript strict mode** - Enhanced type safety
+- **Prettier integration** - No conflicts with Prettier formatting
+- **JavaScript file support** - Lints `.js`, `.jsx`, `.mjs` files (TypeScript `.ts`/`.tsx` preferred)
+
+### Security Rules (OWASP)
+
+- **Secret detection** - Find hardcoded API keys, tokens, and credentials
+- **Eval protection** - Detect dangerous code execution patterns
+- **Buffer security** - Prevent buffer overflow vulnerabilities
+- **Timing attacks** - Identify timing attack vulnerabilities
+- **Unsafe regex** - Find regex patterns vulnerable to ReDoS attacks
+- **Child process** - Detect unsafe child process usage
+- **Non-literal requires** - Prevent dynamic require() calls
+
+### Promise Handling
+
+- **Promise returns** - Ensure promises are properly returned or awaited
+- **Consistent patterns** - Enforce standard promise naming conventions
+- **Error handling** - Validate catch-or-return patterns
+- **Avoid callbacks** - Discourage callback usage within promises
+- **Prefer await** - Suggest await over .then() for cleaner code
+
+### Testing Enhancements
+
+- **Playwright rules** - Browser automation best practices (15+ rules)
+- **Testing Library** - React Testing Library best practices
+- **Jest-DOM matchers** - Encourage better DOM assertion methods
+- **Enhanced Vitest** - Comprehensive test quality rules (35+ rules)
+- **Cypress support** - E2E testing patterns
+
+### PNPM Workspace Validation
+
+- **Catalog enforcement** - Validate catalog: version references
+- **Workspace settings** - Ensure proper workspace configuration
+- **Unused catalog detection** - Find unused catalog entries
+- **Duplicate detection** - Prevent duplicate catalog items
+
+### Import Resolution
+
+- TypeScript path aliases supported (`#/*`, `@repo/*`)
+- Monorepo workspace imports resolved
+- Type-aware import validation
+
+## ?? Configuration Details
+
+### Base Config
+
+TypeScript-first configuration with:
+
+- Strict TypeScript rules
+- Consistent type imports
+- Unused variable handling (with `_` prefix pattern)
+- **14 additional strict TypeScript rules**
+- **OWASP security rules** - Detect dangerous code patterns
+- **Promise handling** - Ensure proper async/await usage
+- **Unused imports** - Automatic dead code detection
+- **PNPM validation** - Catalog and workspace enforcement
+- **File-specific overrides** - Context-aware linting for configs, scripts, types
+- **Custom underscore rule** - Prevent using `_` prefixed variables
+- **JavaScript file support** - Supports `.js`, `.jsx`, and `.mjs` files. TypeScript (`.ts`/`.tsx`) is preferred for
+  type safety.
+
+### React Config
+
+Extends base and adds:
+
+- React 19.2 optimizations
+- React Hooks rules (including React 19 hooks)
+- JSX best practices
+- **14 additional React performance/best practice rules**
+- **55+ Unicorn rules** (code quality)
+- **Accessibility rules** (jsx-a11y)
+- **Regexp optimization** - Improved regex pattern detection
+- **Secret detection** - Find hardcoded credentials in React code
+- Import organization
+- Prettier integration
+- **JavaScript file support** - Supports `.js`, `.jsx`, and `.mjs` files. TypeScript (`.ts`/`.tsx`) is preferred for
+  type safety.
+
+### Next.js Config
+
+Extends React and adds:
+
+- Next.js 16 rules
+- Core Web Vitals
+- App Router-specific rules
+- Next.js performance optimizations
+
+### Expo Config
+
+Extends React and adds:
+
+- React Native-specific rules
+- React Native prop handling
+- Platform-specific component rules
+
+### Test Config
+
+Extends base and adds:
+
+- **Vitest rules** - Comprehensive test quality rules (35+ rules)
+- **Cypress rules** - E2E testing patterns
+- **Playwright rules** - Browser automation best practices (15+ rules)
+- **Testing Library rules** - React Testing Library best practices
+- **Jest-DOM rules** - Better DOM assertion patterns
+- Test-specific overrides (relaxed TypeScript rules, disabled security/promise checks)
+
+## ?? Customization
+
+### Override Rules
+
+```javascript
+import nextConfig from "@od-oneapp/config/eslint/next";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(...nextConfig, {
+  rules: {
+    // Your custom overrides
+    "no-console": "off"
+  }
+});
+```
+
+### Add Plugins
+
+```javascript
+import reactConfig from "@od-oneapp/config/eslint/react";
+import tseslint from "typescript-eslint";
+import customPlugin from "eslint-plugin-custom";
+
+export default tseslint.config(...reactConfig, {
+  plugins: {
+    custom: customPlugin
+  },
+  rules: {
+    "custom/rule": "error"
+  }
+});
+```
+
+## ?? Rule Categories
+
+### TypeScript Rules
+
+- Type safety enforcement
+- Consistent type imports
+- Unused variable detection
+
+### React Rules
+
+- React 19.2 optimizations
+- Hooks rules
+- JSX best practices
+- Component patterns
+
+### Code Quality (Unicorn)
+
+- Array method improvements
+- String method improvements
+- Regex optimizations
+- Modern JavaScript patterns
+
+### Import Organization
+
+- Consistent import ordering
+- Duplicate import prevention
+- Circular dependency detection
+- Path segment cleanup
+
+## ⚠️ Edge Cases & Known Issues
+
+### Test Files with Type-Aware Rules
+
+**Issue:** Type-aware ESLint rules (like `@typescript-eslint/no-floating-promises`) are disabled in test files for
+performance.
+
+**Why:** Test files often use dynamic imports, mocks, and other patterns that make type-aware linting slow and
+unreliable.
+
+**Solution:** If you need type-aware rules in tests, create a custom config:
+
+```javascript
+import testConfig from "@od-oneapp/config/eslint/test";
+
+export default [
+  ...testConfig,
+  {
+    files: ["**/*.test.ts"],
+    rules: {
+      "@typescript-eslint/no-floating-promises": "error" // Re-enable
+    }
+  }
+];
+```
+
+### Next.js Config Without Next.js Installed
+
+**Issue:** The `@od-oneapp/config/eslint/next` config requires `next` and `eslint-config-next` as peer dependencies. If
+Next.js is not installed, imports will fail.
+
+**Error:**
+
+```
+Error: Cannot find module 'next/dist/compiled/babel/eslint-parser'
+```
+
+**Solution:** Ensure Next.js is installed:
+
+```bash
+pnpm add next eslint-config-next
+```
+
+Or use the React config instead if you're not using Next.js:
+
+```javascript
+import reactConfig from "@od-oneapp/config/eslint/react";
+```
+
+### Plugin Conflicts When Combining Configs
+
+**Issue:** Some configs intentionally filter out plugins to avoid conflicts (e.g., `next.mjs` removes `import` and
+`jsx-a11y` plugins from `react.mjs` because `eslint-config-next` provides them).
+
+**Why:** ESLint flat config doesn't allow redefining plugins, so configs must coordinate to avoid conflicts.
+
+**Solution:** The configs handle this automatically. If you encounter plugin conflicts:
+
+1. Check import order - later configs override earlier ones
+2. Don't manually add plugins that are already in parent configs
+3. Use `tseslint.config()` wrapper to properly merge configs
+
+### Underscore-Prefixed Variables
+
+**Issue:** The custom `no-used-underscore-vars` rule prevents using variables that start with `_` (they're for unused
+variables only).
+
+**Valid:**
+
+```javascript
+const _unused = 1; // ✅ Declaration
+function _helper() {} // ✅ Declaration
+obj._private; // ✅ Property access
+```
+
+**Invalid:**
+
+```javascript
+const x = _unused; // ❌ Usage
+if (_condition) {
+} // ❌ Usage
+console.log(_data); // ❌ Usage
+```
+
+**Exception:** Some names are allowed by default in Node config (`__dirname`, `__filename`):
+
+```javascript
+// Node.js config
+export default [
+  ...nodeConfig,
+  {
+    rules: {
+      "no-used-underscore-vars/no-used-underscore-vars": [
+        "error",
+        {
+          allow: ["__dirname", "__filename"] // Allowed in node.mjs
+        }
+      ]
+    }
+  }
+];
+```
+
+### Prettier Plugin Order
+
+**Issue:** `prettier-plugin-tailwindcss` must be last in the plugins array for proper composition.
+
+**Why:** Tailwind CSS plugin needs to run after other formatters to properly sort class names.
+
+**Correct:**
+
+```javascript
+{
+  plugins: [
+    "prettier-plugin-organize-imports",
+    "prettier-plugin-sh",
+    "prettier-plugin-packagejson",
+    "prettier-plugin-tailwindcss" // Must be last
+  ];
+}
+```
+
+**Incorrect:**
+
+```javascript
+{
+  plugins: [
+    "prettier-plugin-tailwindcss", // ❌ Too early
+    "prettier-plugin-organize-imports"
+  ];
+}
+```
+
+### YAML Quote Style
+
+**Issue:** ESLint rule `yml/quotes` enforces double quotes, but Prettier defaults to single quotes for YAML.
+
+**Why:** ESLint can enforce quote style, but Prettier can't change it (Prettier only formats structure, not semantics).
+
+**Solution:** The ESLint rule handles quote style enforcement. Prettier handles indentation and line length.
+
+### Stylelint Color Rules in Theme Files
+
+**Issue:** `stylelint-no-indistinguishable-colors` may flag similar colors in theme/token files.
+
+**Why:** Design systems often use intentionally similar colors (e.g., gray-100, gray-200).
+
+**Solution:** The config disables this rule for theme files:
+
+```javascript
+overrides: [
+  {
+    files: ["**/tailwind-theme.css", "**/theme.css", "**/tokens.css", "**/styles.css"],
+    rules: {
+      "plugin/stylelint-no-indistinguishable-colors": null // Disabled
+    }
+  }
+];
+```
+
+Add your theme files to this override if needed.
+
+## 🔧 Troubleshooting
+
+### Import Resolution Issues
+
+If imports aren't resolving:
+
+1. Ensure `tsconfig.json` has path mappings:
+
+   ```json
+   {
+     "compilerOptions": {
+       "paths": {
+         "#/*": ["./src/*"]
+       }
+     }
+   }
+   ```
+
+2. Verify `eslint-import-resolver-typescript` is installed in your project
+
+### Prettier Conflicts
+
+Prettier integration is included. If you see formatting conflicts:
+
+1. Run `pnpm prettier --write` to format files
+2. ESLint will not conflict with Prettier rules (they're disabled)
+
+### TypeScript Errors
+
+If TypeScript errors appear in ESLint:
+
+1. Ensure `typescript` is installed
+2. Verify `tsconfig.json` is properly configured
+3. Check that `projectService: true` is in parser options (already configured)
+
+## 🔧 Additional Documentation
+
+- [XO-Inspired Rules](./eslint/docs/XO_RULES.md) - Details on XO-inspired rules
+- [File Types](./eslint/docs/FILE_TYPES.md) - Supported file types
+- [Migration Guide](./eslint/docs/MIGRATION.md) - Upgrade guide from v0.1.0
+- [Troubleshooting](./eslint/docs/TROUBLESHOOTING.md) - Common issues and solutions
+- [Linting Analysis](../../docs/linting-analysis.md) - Comprehensive analysis
+
+## ⚙️ Development
+
+### Adding New Rules
+
+1. Add rules to the appropriate config file in `eslint/`, `stylelint/`, or `prettier/`
+2. Test with `pnpm lint`
+3. Document in this README or relevant docs
+4. Update version if breaking changes
+
+### Testing Configs
+
+```bash
+# Test an ESLint config
+node -e "import('./eslint/react.mjs').then(m => console.log('Loaded:', m.default))"
+```
+
+## 🏗️ Architecture & Design Decisions
+
+### Config Composition Strategy
+
+The package uses a hierarchical composition strategy where configs extend each other:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              BASE CONFIG                                     │
+│  Plugins: security, promise, unused-imports, no-used-underscore-vars,       │
+│           jsdoc, yml, pnpm                                                  │
+│  Spreads: tseslint.configs.recommended (@typescript-eslint), prettier       │
+└─────────────────────────────────────────────────────────────────────────────┘
+                    │                                    │
+          ┌─────────┴─────────┐                ┌─────────┴─────────┐
+          ▼                   ▼                ▼                   ▼
+┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
+│   REACT CONFIG  │  │   NODE CONFIG   │  │   TEST CONFIG   │
+│  +react         │  │  +unicorn       │  │  +vitest        │
+│  +react-hooks   │  │  +n (node)      │  │  +cypress       │
+│  +unicorn       │  │                 │  │  +playwright    │
+│  +import        │  │  ⚠️ Don't mix   │  │  +testing-lib   │
+│  +jsx-a11y      │  │  with react!    │  │  +jest-dom      │
+│  +regexp        │  │                 │  │                 │
+│  +no-secrets    │  │                 │  │                 │
+└─────────────────┘  └─────────────────┘  └─────────────────┘
+          │                                        │
+    ┌─────┴─────┐                                  │
+    ▼           ▼                                  │
+┌────────┐  ┌────────┐                            │
+│  EXPO  │  │  NEXT  │◄────────────────────────────┤
+│+react- │  │(filter)│                             │
+│native  │  │+nextjs │                             │
+└────────┘  └────────┘                             │
+                │                                  │
+                ▼                                  │
+         ┌────────────┐                    ┌───────┴───────┐
+         │ STORYBOOK  │                    │   NEXT-TEST   │
+         │ +storybook │                    │ next + test   │
+         └────────────┘                    │ (filtered)    │
+                                           └───────────────┘
+```
+
+**Plugin Inheritance Summary:**
+
+| Config        | Extends          | Additional Plugins                                                | Conflicts                                     |
+| ------------- | ---------------- | ----------------------------------------------------------------- | --------------------------------------------- |
+| react.mjs     | base             | react, react-hooks, unicorn, import, jsx-a11y, regexp, no-secrets | None                                          |
+| node.mjs      | base             | unicorn, n                                                        | ⚠️ Don't mix with react (unicorn conflict)    |
+| expo.mjs      | react            | react-native                                                      | None                                          |
+| next.mjs      | react (filtered) | @next/next                                                        | Filters: import, jsx-a11y, @typescript-eslint |
+| test.mjs      | base             | vitest, cypress, playwright, testing-library, jest-dom            | None                                          |
+| storybook.mjs | next             | storybook                                                         | None                                          |
+| next-test.mjs | next + test      | (combined)                                                        | Filters @typescript-eslint from test          |
+
+**Shared utilities (internal):**
+
+```
+shared/
+  ├── common-ignores.mjs          # Shared ignore patterns (single source of truth)
+  ├── disabled-type-aware-rules.mjs  # TypeScript rules to disable for performance
+  ├── file-patterns.mjs           # Reusable file glob patterns
+  └── node-globals.mjs            # Node.js 22+ global definitions
+utils/
+  ├── create-validated-config.mjs    # Config validation with caching
+  ├── filter-ts-eslint-configs.mjs   # Plugin conflict resolution for Next.js
+  └── validate-config.mjs            # Structure validation
+```
+
+**Why:** This reduces duplication and ensures consistency across related configs.
+
+### TypeScript Config Hierarchy
+
+TypeScript configs follow a similar pattern:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           BASE CONFIG (internal)                             │
+│  Target: ES2024 (Node 22+)    Module: ESNext    Resolution: Bundler         │
+│  Strict: true + noImplicitReturns + noUncheckedIndexedAccess                │
+│  Unused vars: delegated to ESLint (noUnusedLocals/Parameters: false)        │
+└─────────────────────────────────────────────────────────────────────────────┘
+                    │                              │
+                    ▼                              ▼
+       ┌────────────────────┐         ┌────────────────────┐
+       │    NODE CONFIG     │         │   REACT CONFIG     │
+       │  +types: ["node"]  │         │  +lib: DOM, ES2024 │
+       │  (Node 22+ APIs)   │         │  +jsx: react-jsx   │
+       └────────────────────┘         └────────────────────┘
+                                               │
+                              ┌────────────────┴────────────────┐
+                              ▼                                 ▼
+                   ┌────────────────────┐          ┌────────────────────┐
+                   │   NEXTJS CONFIG    │          │ REACT-NATIVE CONFIG│
+                   │  +jsx: preserve    │          │  +jsx: react-native│
+                   │  +types: ["node"]  │          │                    │
+                   │  +plugins: [next]  │          │                    │
+                   └────────────────────┘          └────────────────────┘
+```
+
+**Configuration Inheritance:**
+
+| Config            | Extends | Key Additions                                      |
+| ----------------- | ------- | -------------------------------------------------- |
+| base.json         | -       | ES2024, strict mode, bundler resolution            |
+| node.json         | base    | `types: ["node"]` for Node 22+ APIs                |
+| react.json        | base    | DOM libs, `jsx: react-jsx`                         |
+| nextjs.json       | react   | `jsx: preserve`, `types: ["node"]`, Next.js plugin |
+| react-native.json | react   | `jsx: react-native`                                |
+
+**Note:** `nextjs.json` includes Node types because Next.js apps need both DOM types (for client components) and Node
+types (for server components, API routes, and middleware).
+
+**Key Decision:** `base.json` is not exported because it contains monorepo-specific settings and should not be used
+directly by consumers.
+
+### Plugin Filtering in Next.js Config
+
+The `next.mjs` config uses `filterPluginsForNextJs()` utility to filter out plugins from `react.mjs` that conflict with
+`eslint-config-next`:
+
+- `import` → Provided by Next.js config
+- `jsx-a11y` → Provided by Next.js config
+- `@typescript-eslint` → Provided by Next.js config
+
+**Why:** ESLint flat config doesn't allow plugin redefinition. This approach prevents errors while maintaining all rules
+from both configs.
+
+**Implementation:** The `utils/filter-ts-eslint-configs.mjs` module provides immutable filtering operations.
+
+### Type-Aware Linting Performance
+
+Type-aware rules are disabled in:
+
+- Test files (`test.mjs`)
+- Storybook files (`storybook.mjs`)
+- Test config files (`vitest.config.ts`, etc.)
+
+**Why:** Type-aware linting requires TypeScript compilation, which is slow for test files and config files. Performance
+improvement: ~60-80% faster linting.
+
+**Trade-off:** Some type-safety checks are missed in test code.
+
+### Custom Rules
+
+The package includes one custom rule: `no-used-underscore-vars`
+
+**Why:** Enforces the convention that underscore-prefixed variables are for unused parameters only, preventing
+accidental usage.
+
+**Implementation:** AST-based rule that distinguishes declaration contexts from usage contexts.
+
+### Prettier Plugin Selection
+
+Includes 4 plugins:
+
+1. `prettier-plugin-organize-imports` - Import organization
+2. `prettier-plugin-sh` - Shell script formatting
+3. `prettier-plugin-packagejson` - package.json formatting
+4. `prettier-plugin-tailwindcss` - Tailwind class sorting (must be last)
+
+**Why:** These cover the most common file types in the monorepo while avoiding plugin conflicts.
+
+**Not included:** MDX, PHP, Ruby, etc. (not used in this monorepo)
+
+### Stylelint Minimal Configuration
+
+Only 2 plugins and 2 rules are enabled in Stylelint config.
+
+**Why:** The monorepo primarily uses Tailwind CSS and CSS-in-JS, which don't need extensive CSS linting. The minimal
+config focuses on performance and accessibility.
+
+**If you need more:** Extend with `stylelint-config-standard` or `stylelint-config-recommended`.
+
+### File Type Support
+
+**TypeScript preferred:** The configs support `.js`, `.jsx`, and `.mjs` files but encourage TypeScript (`.ts`, `.tsx`)
+for better type safety.
+
+**JavaScript discouraged:** The base config warns developers to prefer TypeScript for better DX.
+
+### Ignore Patterns
+
+Ignores are defined in base config rather than separate `.eslintignore` file.
+
+**Why:** ESLint flat config doesn't use `.eslintignore`. All ignores are in the config for visibility and version
+control.
+
+**Utilities provided:** `read-eslintignore.mjs` converts gitignore-style patterns to flat config glob patterns for
+migration.
+
+## 📌 Version
+
+Current version: `2025.11.1201` (see [package.json](./package.json))
+
+**Breaking Changes in v0.2.0 (now v2025.11.1201):**
+
+- Package renamed from `@od-oneapp/config-eslint` to `@od-oneapp/config`
+- All configs moved to subfolders (`eslint/`, `stylelint/`, `prettier/`)
+- All files converted to `.mjs` extension
+- Base config is no longer exported (internal use only)
+- No default export - use explicit imports like `@od-oneapp/config/eslint/node`
+
+## 📦 Exported vs Internal
+
+### Exported Configurations
+
+The following configurations are exported and available to consumers:
+
+**ESLint:**
+
+- `@od-oneapp/config/eslint/node` - Node.js projects
+- `@od-oneapp/config/eslint/react` - React 19.2 projects
+- `@od-oneapp/config/eslint/next` - Next.js 16 projects
+- `@od-oneapp/config/eslint/next-test` - Next.js 16 + Test configs combined
+- `@od-oneapp/config/eslint/expo` - React Native/Expo projects
+- `@od-oneapp/config/eslint/storybook` - Storybook v10 projects
+- `@od-oneapp/config/eslint/test` - Test files (Vitest, Cypress, Playwright)
+
+**Other:**
+
+- `@od-oneapp/config/stylelint` - Stylelint configuration
+- `@od-oneapp/config/prettier` - Prettier configuration
+- `@od-oneapp/config/typescript/node.json` - TypeScript for Node.js
+- `@od-oneapp/config/typescript/react.json` - TypeScript for React
+- `@od-oneapp/config/typescript/nextjs.json` - TypeScript for Next.js (includes Node types for server-side code)
+- `@od-oneapp/config/typescript/react-native.json` - TypeScript for React Native
+
+### Internal (Not Exported)
+
+The following are used internally by the exported configs but are not exported separately:
+
+- `eslint/base.mjs` - Internal base configuration (not exported)
+- `eslint/rules/*` - Custom ESLint rules (bundled in configs)
+- `eslint/utils/*` - Utility functions (bundled in configs)
+- `eslint/__tests__/*` - Test files (development only)
+- `typescript/base.json` - Base TypeScript configuration (internal only, not in package exports)
+
+**Note:** The `base.json` TypeScript configuration is internal-only and not exported. Projects should extend from
+`node.json`, `react.json`, `nextjs.json`, or `react-native.json` instead.
+
+## 🔗 Relationship with .linters/
+
+This package (`@od-oneapp/config`) and the `.linters/` directory serve complementary purposes:
+
+| Scope           | `.linters/`                                           | `@od-oneapp/config`         |
+| --------------- | ----------------------------------------------------- | ---------------------- |
+| **Primary Use** | MegaLinter CI pipeline                                | Direct package imports |
+| **Languages**   | Non-JS/TS (Python, Terraform, Docker, Markdown, YAML) | JS/TS ecosystem        |
+| **Runtime**     | CI/CD only                                            | Development + CI       |
+
+MegaLinter references configs from this package for consistency:
+
+- **Prettier**: `@od-oneapp/config/prettier` for TypeScript, JavaScript, JSON, YAML formatting
+- **Stylelint**: `@od-oneapp/config/stylelint` for CSS linting
+
+See `.linters/README.md` for MegaLinter configuration details.
+
+## 🎯 Contributing
+
+When adding rules:
+
+- Document why the rule is valuable
+- Test with existing codebase
+- Consider framework compatibility (React, Next.js, Expo)
+- Update documentation
+
+## ?? License
+
+Private package for OneApp monorepo.
+
+## 📚 Comprehensive Documentation
+
+For detailed documentation, see:
+
+- **[Audit Reports](../../apps/docs/content/docs/audits/config/)** - Comprehensive audits, fixes, and security reviews
+- **[Technical Guides](../../apps/docs/content/docs/packages/config/)** - Implementation guides and best practices
+
+All comprehensive documentation has been centralized in the docs app.