ESLint Config Fans

Opinionated and flexible ESLint config with TypeScript, Vue, Nuxt, Next.js, Astro support and oxlint / oxfmt integration.

• Modern: ESLint flat config with pregenerated TypeScript definitions
• Strict: Opinionated and rigorous linting rules for better code quality
• Flexible: Framework-agnostic with optional plugins
• Zero-config: Works out of the box, customize as needed
• Fast: Optional oxlint / oxfmt integration (50-100x faster linting and formatting)
• Actively maintained and production-tested across diverse client projects at FANS — both new and existing

Default plugins: @eslint/js, import-x, promise, n, de-morgan, unicorn, e18e

Optional plugins: @typescript-eslint, vue, astro, vitest, prettier, @stylistic, perfectionist, vuejs-accessibility, eslint-plugin-query

Inspect rules · View oxlint unsupported rules

Table of Contents

• Usage
• Customization
  • Available Options
  • Ignores
  • Opinionated Mode
  • TypeScript Type-Aware Linting
  • Formatting (Prettier, Stylistic or disable)
  • E18e Rules
  • Custom Configurations and Overrides
• Framework Support
  • Vue
  • Nuxt
  • Next.js
  • Astro
• Oxlint and Oxfmt Support
• Inspect
• Inspired By
• Contributing

Usage

Install the package:

pnpm add -D eslint-config-fans eslint

Create eslint.config.js in your project root:

import { defineConfig } from 'eslint-config-fans'

export default defineConfig({
  // Enable features based on your project
  typescript: true,
  vue: true,
})

Customization

Available Options

interface DefineConfigOptions {
  // Custom ignore patterns
  ignores?: string[]

  // Enable opinionated style rules (filename conventions, forEach ban, etc.)
  opinionated?: boolean // default: true

  // Enable TypeScript support
  typescript?: boolean | TypescriptOptions // default: false

  // Enable Vue.js support
  vue?: boolean | VueOptions // default: false

  // Enable Astro support
  astro?: boolean // default: false

  // Enable test files support (Vitest)
  test?: boolean // default: false

  // Configure code formatting integration
  formatter?: FormatterOptions | 'prettier' | 'stylistic' | false // default: false

  // Enable unicorn rules (opinionated best practices)
  unicorn?: boolean // default: true

  // Enable e18e rules (modernization and performance)
  e18e?: boolean | E18eOptions // default: true

  // Enable import/export sorting
  perfectionist?: boolean // default: false

  // Enable oxlint support for better performance
  oxlint?: boolean | OxlintOptions // default: false

  // Enable TanStack Query support
  query?: boolean // default: false
}

interface TypescriptOptions {
  // Enable type-aware linting rules
  // true — enables stylistic-type-checked and recommended-type-checked
  // 'strict' — experimental: also enables strict-type-checked
  typeAware?: boolean | 'strict' // default: true
}

interface VueOptions {
  // Enable vuejs-accessibility rules
  a11y?: boolean // default: false

  // Additional component names to ignore in the `vue/no-undef-components` rule
  extendUndefComponents?: string[]
}

Ignores

By default, the config ignores common directories and files, and automatically respects your .gitignore patterns. You can extend the ignore patterns:

export default defineConfig({
  ignores: ['custom-dist/**', 'legacy-code/**'],
})

Opinionated Mode

By default, the config enables opinionated rules. You can disable them:

export default defineConfig({
  opinionated: false,
})

TypeScript Type-Aware Linting

When TypeScript is enabled, type-aware linting rules are active by default (stylistic-type-checked and recommended-type-checked). You can configure this behavior:

export default defineConfig({
  typescript: {
    // Disable type-aware rules
    typeAware: false,
  },
})

For new projects, we recommend keeping type-aware mode enabled. For legacy codebases or gradual adoption, you may want to start with typeAware: false and enable it later.

For advanced users, there is an experimental strict mode that additionally enables strict-type-checked rules:

export default defineConfig({
  typescript: {
    typeAware: 'strict',
  },
})

Formatting

Prettier, Stylistic or disable

You can choose between Prettier and ESLint Stylistic for code formatting:

• Prettier (formatter: 'prettier'): Uses Prettier for formatting, disables conflicting rules
• Stylistic (formatter: 'stylistic'): Uses ESLint Stylistic rules for formatting
• Disable (formatter: false): Disables formatting if you prefer to use external formatter like oxfmt, biome, etc.

Stylistic Options

When using formatter: 'stylistic', you can customize formatting rules. See StylisticOptions for all available options:

export default defineConfig({
  formatter: {
    type: 'stylistic',
    options: {
      indent: 2,
      quotes: 'single',
      semi: false,
    },
  },
})

Prettier Configuration

Prettier can be configured through standard .prettierrc files or prettier.config.js. The ESLint config will automatically detect and respect your Prettier settings.

E18e Rules

The e18e plugin enforces modernization, module replacement, and performance improvement rules. All three rule sets are enabled by default and can be toggled independently:

export default defineConfig({
  e18e: {
    // Prefer newer JS APIs (e.g. Array.at, Object.hasOwn)
    modernization: true,

    // Replace heavy modules with lighter alternatives
    moduleReplacements: true,

    // Enforce performance-oriented patterns
    performanceImprovements: true,
  },
})

Custom Configurations and Overrides

You can extend the configuration with additional ESLint configs and use exported globs for precise file targeting:

import { defineConfig, GLOB_TS } from 'eslint-config-fans'

export default defineConfig(
  {
    typescript: true,
  },
  {
    files: [GLOB_TS],
    rules: {
      '@typescript-eslint/no-misused-promises': 'off',
    },
  },
)

Available globs

Framework Support

Vue

Full support for Vue projects with vue-accessibility and TypeScript integration:

export default defineConfig({
  typescript: true,
  vue: {
    // Enable vuejs-accessibility rules
    a11y: true,

    // Ignore undefined components for the `vue/no-undef-components` rule
    extendUndefComponents: ['CustomComponent'],
  },
})

This enables linting for .vue files with proper TypeScript support and Vue-specific rules.

Nuxt

Full compatibility with Nuxt ESLint:

import { defineConfig } from 'eslint-config-fans'
import withNuxt from './.nuxt/eslint.config.mjs'

export default withNuxt(
  defineConfig({
    typescript: true,
    vue: {
      a11y: true,
    },
  }),
)

Next.js

Full compatibility with Next.js ESLint:

import { defineConfig } from 'eslint-config-fans'
import configNextCoreWebVitals from 'eslint-config-next/core-web-vitals'
import configNextTypescript from 'eslint-config-next/typescript'

export default defineConfig(
  {
    typescript: true,
  },
  ...configNextCoreWebVitals,
  ...configNextTypescript,
)

Astro

Full support for Astro projects with TypeScript integration:

export default defineConfig({
  typescript: true,
  astro: true,
})

This enables linting for .astro files with proper TypeScript support and Astro-specific rules.

Oxlint and Oxfmt Support

This config includes built-in support for oxlint — a blazing-fast JavaScript linter written in Rust by void(0). Oxlint is 50-100 times faster than ESLint and designed for performance-critical workflows, making it perfect for large codebases and CI environments.

Note: Oxlint doesn't support all ESLint rules yet. Check the generated list of unsupported rules to see which rules from this config are not available in oxlint.

Enabling Oxlint

We recommend following the official migration guide for the most up-to-date instructions.

1. Create your ESLint config as described above

2. Install oxlint:

   pnpm add -D oxlint

3. Generate oxlint configuration from your ESLint config:

   pnpx @oxlint/migrate ./eslint.config.js --type-aware --js-plugins

   This command migrates your ESLint configuration to oxlint format:

   • --type-aware: Generates configuration for TypeScript type-aware rules
   • --js-plugins: Migrates JavaScript plugin rules to their oxlint equivalents

   Note: After migration, you may need to manually install some JavaScript plugins to your dev dependencies that oxlint requires but doesn’t install automatically.

4. Enable oxlint in your configuration:

   export default defineConfig({
     typescript: true,
     oxlint: true, // Enable oxlint support
   })

   For TypeScript projects, you might want to enable DTS checking:

   export default defineConfig({
     typescript: true,
     oxlint: {
       dts: true, // Check .d.ts files with TypeScript rules
     },
   })

Important: We still recommend running oxlint and ESLint together, as oxlint doesn’t support all ESLint rules yet. Use oxlint for fast feedback during development and ESLint for comprehensive checks in CI.

Using Oxfmt for Formatting

If you want to use oxfmt for formatting instead of Prettier or Stylistic:

1. Disable formatting in your ESLint config (see Formatting for details):

   export default defineConfig({
     typescript: true,
     formatter: false, // Disable ESLint formatting rules
   })

2. Install oxfmt:

   pnpm add -D oxfmt

3. Initialize oxfmt configuration:

   pnpx oxfmt --init

   This creates an oxc.json file with formatter configuration.

4. Add format scripts to your package.json:

   {
     "scripts": {
       "format": "oxfmt",
       "format:check": "oxfmt --check"
     }
   }

For more details, see the oxfmt quickstart guide.

Inspect

You can inspect your ESLint configuration using the interactive configuration inspector:

pnpx @eslint/config-inspector --config eslint.config.js

Or add it as a script to your package.json:

{
  "scripts": {
    "lint:inspect": "pnpx @eslint/config-inspector --config eslint.config.js"
  }
}

Inspired By

This configuration is inspired by and builds upon the excellent work of:

• @logux/eslint-config
• @sxzz/eslint-config
• @antfu/eslint-config

Contributing

This package can be installed directly from the repository, thanks to our pure JavaScript implementation with TypeScript definitions provided via .d.ts files — no compilation step required.

pnpm add -D github:fandsdev/eslint-config-fans

All versions follow Semantic Versioning.