ESLint Flat-Config Package Authoring (antfu-based)

ESLint Flat-Config Package Authoring (antfu-based)

Overview

Enables building an npm package that wraps @antfu/eslint-config, adds opinionated rule groups (sonarjs/unicorn/jsdoc/custom plugins), and stays a drop-in-compatible extension of antfu's own types/composer — plus authoring and testing custom typed ESLint rules and packaging the result correctly with tsdown.

Key Concepts

• OptionsConfig: antfu's public options interface (typescript, vue, react, stylistic, ignores, …) — extend it, don't reinvent it.
• TypedFlatConfigItem: antfu's flat-config item type (Omit<ConfigWithExtends, 'plugins'|'rules'> & {...}), sourced from eslint-flat-config-utils, re-exported by antfu.
• FlatConfigComposer: the chainable object (.append(), .override(), .renamePlugins()) that antfu() returns — not re-exported by @antfu/eslint-config, lives in eslint-flat-config-utils.
• Type-aware linting: requires parserOptions.projectService (or legacy project) so @typescript-eslint rules and custom rules can query the TS type checker.
• Composition/override ordering: in flat config, later { files, rules } entries win on matching rules (last-match-wins per rule key) — this is how "opinionated defaults, user-overridable" is achieved without a bespoke API.

Documentation & References

Recommended Libraries & Tools

Recommended Stack

Keep the repo's existing choices (tsdown, vitest, TS ^6). Add typescript-eslint, @typescript-eslint/utils, eslint-plugin-{sonarjs,unicorn,jsdoc,validate-filename,promise} as runtime dependencies (matches antfu's own pattern of shipping its rule-plugin deps directly, not as peers); eslint, @typescript-eslint/rule-tester as devDependencies only (needed to run tests/demo, not required transitively by consumers beyond the eslint peer).

Patterns & Best Practices

Thin factory over antfu, with our rules injected before user configs

When to use: building a "preset that's still just antfu underneath." Trade-offs: gives full override power to consumers via native { files, rules } items; requires discipline to put all our rule blocks before ...userConfigs in the call to antfu().

import antfu from '@antfu/eslint-config'
import type { OptionsConfig, TypedFlatConfigItem } from '@antfu/eslint-config'

export interface AgentConfigOptions extends OptionsConfig {
  alias?: false | { prefix?: string, sourceDir?: string }
}

export default function config(options: AgentConfigOptions = {}, ...userConfigs: TypedFlatConfigItem[]) {
  return antfu(options, ...buildOurConfigs(options), ...userConfigs)
}

Avoiding duplicate @typescript-eslint plugin registration

When to use: appending tseslint.configs.strictTypeChecked (or any tseslint preset) on top of a config that already registers the TS plugin (antfu's typescript config does). Trade-offs: skipping the first array element is a documented-safe technique (that element is pure plugin/parser registration, no rules) but is easy to forget on refactor — cover it with a test.

import tseslint from 'typescript-eslint'

const typeAwareConfig = [
  ...tseslint.configs.strictTypeChecked.slice(1), // [0] just re-registers plugin+parser
  { languageOptions: { parserOptions: { projectService: true } } }, // omit tsconfigRootDir -> defaults to process.cwd()
]

Typed custom rule + vitest-integrated RuleTester

When to use: every custom rule in the package (AST-only or type-aware). Trade-offs: ESLintUtils.RuleCreator requires a docs-URL factory function; type-aware rules need a real tsconfig.json fixture for RuleTester.

import { ESLintUtils } from '@typescript-eslint/utils'

const createRule = ESLintUtils.RuleCreator(name => `https://github.com/<org>/<repo>/blob/main/docs/rules/${name}.md`)

export const rule = createRule({
  name: 'my-rule',
  meta: { type: 'problem', docs: { description: '...' }, messages: { bad: '...' }, schema: [] },
  defaultOptions: [],
  create(context) { return { /* AST visitors, or use ESLintUtils.getParserServices(context) for type info */ } },
})

// tests/setup.ts (or top of each rule test file)
import * as vitest from 'vitest'
import { RuleTester } from '@typescript-eslint/rule-tester'
RuleTester.afterAll = vitest.afterAll
RuleTester.it = vitest.it
RuleTester.itOnly = vitest.it.only
RuleTester.describe = vitest.describe

// type-aware rule only:
new RuleTester({
  languageOptions: { parserOptions: { projectService: true, tsconfigRootDir: import.meta.dirname } },
})

Common Pitfalls & Solutions

Recommendations

1. Extend OptionsConfig (imported from @antfu/eslint-config) rather than redefining it — keeps drop-in compatibility with antfu's own consumers/tooling (e.g. antfu's VS Code extension, eslint-config-inspector).
2. Put every internal rule-group config before ...userConfigs in the call to antfu(...) — this is the entire override guarantee; verify it with a factory test asserting object-identity ordering, not just "it doesn't crash."
3. Treat .npmrc's min-release-age as a live constraint, not a one-time check — re-verify package ages right before npm install runs, since the research and implementation steps may be days apart.
4. Rebuild and manually inspect package.json after any tsdown config change — exports: true is not a substitute for reviewing the generated file once.

Implementation Guidance

Configuration

• tsdown.config.ts already has dts: { tsgo: true }, exports: true — keep, but check package.json after each build.
• peerDependencies: { "eslint": "^9.10.0 || ^10.0.0" } (only valid if eslint-plugin-unicorn stays on 65.0.1; otherwise narrow to ^10.4.0).

Integration Points

• Public entry (src/index.ts) default-exports the factory; consumers call config(options?, ...userConfigs) exactly like antfu(...).
• Each configs/*.ts module is (resolvedOptions) => TypedFlatConfigItem[], independently unit-testable without invoking the full factory.

Code Examples

Example 1: Modular rule-group builder

// configs/sonarjs.ts
import sonarjs from 'eslint-plugin-sonarjs'
import type { TypedFlatConfigItem } from '@antfu/eslint-config'

export function sonarjsConfig(): TypedFlatConfigItem[] {
  return [{ plugins: { sonarjs }, rules: { 'sonarjs/cognitive-complexity': ['error', 4] } }]
}

Example 2: Factory test asserting override ordering (no hardcoded rule names)

import { describe, expect, it } from 'vitest'
import config from '../src/index'

it('lets user configs override ours (last-match-wins)', () => {
  const sentinel = { files: ['**/*.ts'], rules: { 'no-console': 'off' } }
  const items = config({}, sentinel)

  expect(items.at(-1)).toBe(sentinel) // appended last per antfu(...) contract
})

Sources & Verification

Changelog