Merge pull request #158

chore(release): v0.7.10 - documentation improvements and minor fixes

Author: amery

AGENT.md

@@ -300,6 +300,16 @@ import { forNuxt } from '@poupe/eslint-config/nuxt';
 import withNuxt from './.nuxt/eslint.config.mjs';
 export default withNuxt(...forNuxt());
 
+// Nuxt Module usage
+import { createConfigForNuxt } from '@nuxt/eslint-config/flat';
+import { forNuxtModules } from '@poupe/eslint-config/nuxt';
+export default createConfigForNuxt({
+  features: {
+    tooling: true,
+    stylistic: true,
+  }
+}, ...forNuxtModules());
+
 // Custom composition with withConfig
 import { configs, withConfig } from '@poupe/eslint-config';
 export default withConfig(
@@ -309,6 +319,47 @@ export default withConfig(
 );
 ```
 
+## Nuxt Configuration Complexity
+
+### Why Different Configs for Nuxt Apps vs Modules?
+
+Nuxt applications and Nuxt modules have different ESLint setups:
+
+1. **Nuxt Applications** use `@nuxt/eslint` which generates a config at
+   `.nuxt/eslint.config.mjs`. This is integrated with the Nuxt build process.
+
+2. **Nuxt Modules** use `@nuxt/eslint-config/flat` directly with
+   `createConfigForNuxt`. The `tooling` feature enables module-author-specific
+   rules including their own version of unicorn rules.
+
+### The Unicorn Plugin Conflict
+
+The issue with unicorn rules stems from:
+
+1. **Plugin Instance Conflicts**: When both our config and Nuxt's tooling config
+   try to load the unicorn plugin, ESLint detects different instances and throws
+   an error: "Different instances of plugin 'unicorn' found"
+
+2. **Version Mismatches**: Historically, Nuxt tooling used an older version of
+   unicorn that didn't include these rules:
+   - `unicorn/no-unnecessary-array-flat-depth`
+   - `unicorn/no-unnecessary-array-splice-count`
+   - `unicorn/no-unnecessary-slice-end`
+   - `unicorn/prefer-single-call`
+
+3. **Current Solution**: For Nuxt modules, we:
+   - Remove the unicorn plugin using `withoutPlugin('unicorn', ...)`
+   - Filter out rules that might not exist using `withoutRules(...)`
+   - This allows Nuxt's tooling to provide its own unicorn configuration
+
+### Future Considerations
+
+- The version mismatch may no longer exist if Nuxt has updated their unicorn
+  dependency
+- The filtered rules should be periodically reviewed to check if they're still
+  necessary
+- Consider using feature detection instead of hardcoding rule names
+
 ## Git Workflow
 
 ### Commit Guidelines

CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.7.10] - 2025-07-02
+
+### Documentation
+
+- Enhanced README with comprehensive documentation including supported file types,
+  advanced configuration examples, migration guide, and troubleshooting section
+- Added package.json description field for better npm registry visibility
+
+### Fixed
+
+- Removed redundant export in index.ts that was duplicating configs exports
+
 ## [0.7.9] - 2025-07-01
 
 ### Added

README.md

@@ -1,6 +1,7 @@
 # `@poupe/eslint-config`
 
-Sharable ESLint config preset for usage across Poupe UI projects.
+Sharable ESLint configuration preset for Poupe UI projects with TypeScript,
+Vue.js, and Tailwind CSS support.
 
 ✅ Includes:
 
@@ -19,7 +20,8 @@ Sharable ESLint config preset for usage across Poupe UI projects.
 ## Getting started
 
 > [!NOTE]
-> This preset uses the new [ESLint flat config][flat-config].
+> This preset uses the new [ESLint flat config][flat-config] format and
+> requires ESLint v9+ and Node.js v18.20.8+.
 
 Install dependencies:
 
@@ -36,7 +38,7 @@ import poupeConfig from '@poupe/eslint-config';
 export default poupeConfig;
 ```
 
-For Nuxt.js projects (with @nuxt/eslint module):
+For Nuxt.js applications (with @nuxt/eslint):
 
 ```js
 // @ts-check
@@ -50,6 +52,21 @@ export default withNuxt(...forNuxt({
 }));
 ```
 
+For Nuxt modules (with @nuxt/eslint-config):
+
+```js
+// @ts-check
+import { createConfigForNuxt } from '@nuxt/eslint-config/flat';
+import { forNuxtModules } from '@poupe/eslint-config/nuxt';
+
+export default createConfigForNuxt({
+  features: {
+    tooling: true,    // Enables rules for module authors
+    stylistic: true,  // Enables formatting rules
+  },
+}, ...forNuxtModules());
+```
+
 Custom configuration:
 
 ```js
@@ -77,8 +94,24 @@ The filtering system categorizes plugins and rules to ensure only appropriate
 rules apply to CSS files. See [AGENT.md](./AGENT.md#css-configuration-system)
 for implementation details.
 
+## Supported File Types
+
+This configuration automatically lints the following file types:
+
+* **JavaScript**: `.js`, `.mjs`, `.cjs`
+* **TypeScript**: `.ts`, `.tsx`
+* **Vue.js**: `.vue` (Single File Components)
+* **JSON/JSONC**: `.json`, `.jsonc`, `package.json`
+* **Markdown**: `.md`
+* **CSS**: `.css` (with Tailwind CSS v4 syntax support)
+
 ## Features
 
+### Self-Dogfooding
+
+This package uses its own ESLint configuration for validation, ensuring
+quality and serving as a real-world test case.
+
 ### Automatic Import/Export Sorting
 
 This configuration includes `eslint-plugin-perfectionist` which automatically
@@ -131,6 +164,114 @@ type Status =
   | 'success';
 ```
 
+## Advanced Configuration
+
+### Custom Rule Overrides
+
+```js
+// @ts-check
+import { defineConfig } from '@poupe/eslint-config';
+
+export default defineConfig({
+  rules: {
+    // Disable specific rules
+    'unicorn/filename-case': 'off',
+
+    // Customize rule severity and options
+    '@typescript-eslint/no-unused-vars': ['warn', {
+      argsIgnorePattern: '^_',
+      varsIgnorePattern: '^_',
+    }],
+  },
+});
+```
+
+### Selective Configuration Import
+
+```js
+// @ts-check
+import { configs, withConfig } from '@poupe/eslint-config';
+
+// Import only specific configurations
+export default withConfig(
+  configs.javascript,
+  configs.typescript,
+  configs.stylistic,
+  configs.vue,
+  // Add custom overrides
+  {
+    rules: {
+      'vue/multi-word-component-names': 'off',
+    },
+  },
+);
+```
+
+## Poupe UI Recommended Rules
+
+In addition to the rules from included plugins, this configuration adds these
+custom rules:
+
+### TypeScript Rules
+
+* Enforces explicit return types on exported functions
+* Requires consistent type imports (`import type`)
+* Disables `@ts-` comment directives
+
+### Vue.js Rules
+
+* Enforces multi-word component names
+* Requires `defineEmits` and `defineProps` type declarations
+* Ensures proper `v-model` usage patterns
+
+### General JavaScript Rules
+
+* Enforces camelCase naming convention
+* Requires explicit radix in `parseInt`
+* Prevents console statements in production code
+
+### Stylistic Rules
+
+* Single quotes for strings
+* Semicolons required
+* 1tbs (one true brace style)
+* 2-space indentation for web files
+* 80-character line limit for Markdown
+
+## Migration Guide
+
+### From Legacy ESLint Config
+
+If you're migrating from a legacy `.eslintrc` configuration:
+
+1. **Remove old config files**: Delete `.eslintrc`, `.eslintrc.js`,
+   `.eslintrc.json`, etc.
+
+2. **Update dependencies**:
+
+   ```sh
+   pnpm remove eslint-config-* eslint-plugin-*
+   pnpm install -D eslint@^9 typescript @poupe/eslint-config
+   ```
+
+3. **Create new config**: Add `eslint.config.mjs` as shown in Getting Started
+
+4. **Update scripts**: ESLint v9 automatically finds `eslint.config.mjs`
+
+   ```json
+   {
+     "scripts": {
+       "lint": "eslint .",
+       "lint:fix": "eslint . --fix"
+     }
+   }
+   ```
+
+5. **Handle breaking changes**:
+   * Some rules have been renamed or moved to different plugins
+   * The flat config uses different property names (`files` instead of `overrides`)
+   * Plugin names are now used as object keys instead of strings
+
 ## Examples
 
 The `examples/` directory contains working examples demonstrating how to use
@@ -159,11 +300,74 @@ pnpm -r --filter "./examples/*" lint:fix
 pnpm --filter "@poupe/eslint-config-playground-standard" lint
 ```
 
+## Troubleshooting
+
+### Common Issues
+
+#### "Cannot find module '@poupe/eslint-config'"
+
+Ensure you've installed the package and are using the correct import path:
+
+```sh
+pnpm install -D @poupe/eslint-config
+```
+
+#### "Plugin conflict" errors with Nuxt
+
+For Nuxt applications, make sure to use the appropriate helper:
+
+* Use `forNuxt()` for Nuxt applications
+* Use `forNuxtModules()` for Nuxt module development
+
+#### CSS rules applying to JavaScript files
+
+This should not happen with the default configuration. If it does, ensure
+you're using the latest version and report an issue.
+
+#### "Unknown rule" warnings
+
+These warnings help the CSS filtering system learn about new rules. They're
+informational and don't affect functionality.
+
+### Debugging
+
+To debug ESLint configuration issues:
+
+```sh
+# Show resolved configuration for a specific file
+eslint --print-config path/to/file.js
+
+# Enable ESLint debug output
+DEBUG=eslint:* eslint .
+
+# Debug specific aspects
+DEBUG=eslint:eslint eslint .
+```
+
 ## Development
 
 For AI assistants working with this codebase, refer to [AGENT.md](./AGENT.md)
 for detailed guidance and conventions.
 
+### Project Structure
+
+```text
+src/
+├── configs/        # Individual ESLint rule configurations
+├── core/           # Core utilities and type definitions
+├── config.ts       # Main configuration builder
+├── configs.ts      # Configuration presets
+├── index.ts        # Main entry point
+└── nuxt.ts         # Nuxt-specific configurations
+```
+
+### Contributing
+
+1. Make changes to configuration files in `src/configs/`
+2. Run `pnpm build` to compile the package
+3. Test with `pnpm lint` (self-linting)
+4. Test in examples: `pnpm -r --filter "./examples/*" lint`
+
 ## License
 
 MIT

package.json

@@ -1,8 +1,8 @@
 {
   "name": "@poupe/eslint-config",
-  "version": "0.7.9",
+  "version": "0.7.10",
   "type": "module",
-  "description": "",
+  "description": "Sharable ESLint configuration preset for Poupe UI projects with TypeScript, Vue.js, and Tailwind CSS support",
   "author": "Alejandro Mery <[email protected]>",
   "license": "MIT",
   "homepage": "https://github.com/poupe-ui/eslint-config",
@@ -24,12 +24,12 @@
   ],
   "scripts": {
     "build": "unbuild",
-    "clean": "rm -rf dist node_modules && pnpm -r --filter \"./examples/*\" clean",
+    "clean": "rimraf dist node_modules && pnpm -r --filter \"./examples/*\" clean",
     "dev:prepare": "unbuild --stub",
-    "lint": "unbuild --stub && env DEBUG=eslint:eslint eslint --fix .",
+    "lint": "unbuild --stub && cross-env DEBUG=eslint:eslint eslint --fix .",
     "lint:all": "run-s lint lint:examples",
     "lint:examples": "pnpm -r --filter \"playground-*\" lint:fix",
-    "postinstall": "[ -s dist/index.mjs ] || unbuild --stub",
+    "postinstall": "node -e \"require('fs').existsSync('dist/index.mjs') || process.exit(1)\" || unbuild --stub",
     "precommit": "run-s lint:all type-check test:all build",
     "prepack": "run-s lint type-check test:all build publint",
     "publint": "publint",
@@ -58,10 +58,12 @@
   },
   "devDependencies": {
     "@vitest/ui": "^3.2.4",
+    "cross-env": "^7.0.3",
     "globals": "^16.3.0",
     "npm-run-all2": "^8.0.4",
     "pkg-pr-new": "^0.0.54",
     "publint": "^0.3.12",
+    "rimraf": "^6.0.1",
     "typescript": "~5.8.3",
     "unbuild": "3.5.0",
     "vitest": "^3.2.4"
@@ -72,7 +74,7 @@
     }
   },
   "engines": {
-    "node": ">= 18.20.8",
+    "node": ">= 18.20.0",
     "pnpm": ">= 10.10.0"
   },
   "packageManager": "[email protected]+sha512.d615db246fe70f25dcfea6d8d73dee782ce23e2245e3c4f6f888249fb568149318637dca73c2c5c8ef2a4ca0d5657fb9567188bfab47f566d1ee6ce987815c39"