@poupe/eslint-config

Sharable ESLint configuration preset for Poupe UI projects with TypeScript, Vue.js, and Tailwind CSS support.

✅ Includes:

• eslint recommended rules
• stylistic recommended formatting rules
• typescript-eslint integration
• unicorn rules
• perfectionist rules for import/export and union type sorting
• vue recommended rules with TypeScript support
• tsdoc rules for TypeScript documentation
• markdownlint rules for Markdown files
• jsonc rules for JSON and package.json files
• css rules for CSS files with Tailwind CSS support
• Poupe UI recommended rules

Getting started

[!NOTE] This preset uses the new ESLint flat config format and requires ESLint v9+ and Node.js v18.20.8+.

Install dependencies:

1pnpm install -D eslint typescript @poupe/eslint-config

Create eslint.config.mjs in your project root:

1// @ts-check
2import poupeConfig from '@poupe/eslint-config';
3
4export default poupeConfig;

For Nuxt.js applications (with @nuxt/eslint):

1// @ts-check
2import { forNuxt } from '@poupe/eslint-config/nuxt';
3import withNuxt from './.nuxt/eslint.config.mjs';
4
5export default withNuxt(...forNuxt({
6  rules: {
7    // custom rule overrides
8  },
9}));

For Nuxt modules (with @nuxt/eslint-config):

1// @ts-check
2import { createConfigForNuxt } from '@nuxt/eslint-config/flat';
3import { forNuxtModules } from '@poupe/eslint-config/nuxt';
4
5export default createConfigForNuxt({
6  features: {
7    tooling: true,    // Enables rules for module authors
8    stylistic: true,  // Enables formatting rules
9  },
10}, ...forNuxtModules());

Custom configuration:

1// @ts-check
2import { defineConfig } from '@poupe/eslint-config';
3
4export default defineConfig({
5  rules: {
6    // rule overrides
7  },
8});

CSS Support

This configuration includes advanced CSS linting with Tailwind CSS v4 syntax support. The CSS configuration uses an intelligent filtering system that:

• Applies CSS-specific rules from @eslint/css
• Supports Tailwind CSS v4 syntax including theme functions and modifiers
• Automatically disables JavaScript-specific rules for CSS files
• Keeps relevant cross-language rules (like filename-case from unicorn)

The filtering system categorizes plugins and rules to ensure only appropriate rules apply to CSS files. See AGENT.md 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 organizes your imports and exports. The sorting happens automatically when you run eslint --fix or save files with ESLint auto-fix enabled in your editor:

1// Before
2import { z } from 'zod';
3import React from 'react';
4import { useState, useEffect } from 'react';
5import { Button } from './components/Button';
6import axios from 'axios';
7import type { User } from '../types';
8import { config } from './config';
9
10// After (automatically fixed by ESLint)
11import type { User } from '../types';
12
13import axios from 'axios';
14import React from 'react';
15import { z } from 'zod';
16
17import { config } from './config';
18import { Button } from './components/Button';
19import { useEffect, useState } from 'react';

Union Type Sorting

The configuration also includes automatic sorting of TypeScript union types with perfectionist/sort-union-types. Union members are sorted in natural order, and you can use comments to create logical groups:

1// Before
2type Status = 'error' | 'loading' | 'success' | 'idle';
3
4// After (automatically fixed by ESLint)
5type Status = 'error' | 'idle' | 'loading' | 'success';
6
7// With comment-based grouping
8type Status =
9  // Active states
10  | 'loading'
11  | 'processing'
12  // Inactive states
13  | 'error'
14  | 'idle'
15  | 'success';

Advanced Configuration

Custom Rule Overrides

1// @ts-check
2import { defineConfig } from '@poupe/eslint-config';
3
4export default defineConfig({
5  rules: {
6    // Disable specific rules
7    'unicorn/filename-case': 'off',
8
9    // Customize rule severity and options
10    '@typescript-eslint/no-unused-vars': ['warn', {
11      argsIgnorePattern: '^_',
12      varsIgnorePattern: '^_',
13    }],
14  },
15});

Selective Configuration Import

1// @ts-check
2import { configs, withConfig } from '@poupe/eslint-config';
3
4// Import only specific configurations
5export default withConfig(
6  configs.javascript,
7  configs.typescript,
8  configs.stylistic,
9  configs.vue,
10  // Add custom overrides
11  {
12    rules: {
13      'vue/multi-word-component-names': 'off',
14    },
15  },
16);

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
• Allows i, j, k as loop counters and array indices
• 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:

   1pnpm remove eslint-config-* eslint-plugin-*
   2pnpm 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

   1{
   2  "scripts": {
   3    "lint": "eslint .",
   4    "lint:fix": "eslint . --fix"
   5  }
   6}

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 this ESLint configuration in different scenarios:

• playground-standard - Basic JavaScript/TypeScript projects
• playground-nuxt - Nuxt.js applications
• playground-nuxt-module - Nuxt module development

Running Examples

This project uses pnpm workspaces. You can run commands on all examples:

1# Install dependencies for all workspaces
2pnpm install
3
4# Lint all examples
5pnpm -r --filter "./examples/*" lint
6
7# Fix lint issues in all examples
8pnpm -r --filter "./examples/*" lint:fix
9
10# Run a specific example
11pnpm --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:

1pnpm 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:

1# Show resolved configuration for a specific file
2eslint --print-config path/to/file.js
3
4# Enable ESLint debug output
5DEBUG=eslint:* eslint .
6
7# Debug specific aspects
8DEBUG=eslint:eslint eslint .

Development

For AI assistants working with this codebase, refer to AGENT.md for detailed guidance and conventions.

Project Structure

1src/
2├── configs/        # Individual ESLint rule configurations
3├── core/           # Core utilities and type definitions
4├── config.ts       # Main configuration builder
5├── configs.ts      # Configuration presets
6├── index.ts        # Main entry point
7└── 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