@payloadcms/eslint-config

@payloadcms/eslint-config provides a comprehensive ESLint configuration package for Payload CMS and related projects, offering opinionated linting rules for TypeScript, React, Jest, and other common development patterns. The package includes configurations for different file types (TypeScript, TSX, test files, and Payload config files) with specific rule sets for code quality, import organization, accessibility, and consistency.

Package Information

• Package Name: @payloadcms/eslint-config
• Package Type: npm
• Language: JavaScript (ES Modules)
• Installation: npm install @payloadcms/eslint-config

Core Imports

import eslintConfig from "@payloadcms/eslint-config";

For named imports:

import { rootEslintConfig } from "@payloadcms/eslint-config";

Basic Usage

// eslint.config.js (ESLint 9.x flat config)
import payloadEslintConfig from "@payloadcms/eslint-config";

export default payloadEslintConfig;

Architecture

@payloadcms/eslint-config is built around several key components:

• Flat Configuration Format: Uses ESLint 9.x flat config system with configuration objects
• Multi-file Support: Provides different rule sets for .ts, .tsx, .spec.ts, and config files
• Plugin Integration: Combines multiple ESLint plugins (TypeScript, React, Jest, accessibility, etc.)
• Rule Inheritance: Uses deep merging to combine base configurations with specific overrides
• Type-aware Linting: Integrates TypeScript parser for advanced type checking rules

Capabilities

Main Configuration Export

The primary export providing a complete ESLint configuration array for Payload CMS projects.

/**
 * Main ESLint configuration array containing 5 distinct configurations
 * for different file types and contexts
 */
declare const rootEslintConfig: Config[];

/**
 * Default export (same as rootEslintConfig)
 */
declare const _default: Config[];
export default _default;
export { rootEslintConfig };

The configuration array includes:

1. Settings - Base language and parser configuration
2. TypeScript - Rules for **/*.ts files
3. TypeScript-React - Rules for **/*.tsx files
4. Unit Tests - Rules for **/*.spec.ts files
5. Payload Config - Rules for *.config.ts and config.ts files

Deep Merge Utility

Utility function for recursively merging configuration objects with array handling.

/**
 * Recursively merges multiple objects, handling arrays and nested objects
 * @param objs - Objects to merge (later objects take priority)
 * @returns Merged object
 */
declare function deepMerge(...objs: any[]): any;

Import:

import { deepMerge } from "@payloadcms/eslint-config/deepMerge.js";

Usage Example:

import { deepMerge } from "@payloadcms/eslint-config/deepMerge.js";

const config1 = { rules: { "no-console": "warn" } };
const config2 = { rules: { "no-unused-vars": "error" } };
const merged = deepMerge(config1, config2);
// Result: { rules: { "no-console": "warn", "no-unused-vars": "error" } }

Types

/**
 * ESLint flat configuration object
 */
interface Config {
  name?: string;
  files?: string[];
  ignores?: string[];
  languageOptions?: {
    ecmaVersion?: string | number;
    sourceType?: "script" | "module";
    globals?: Record<string, boolean>;
    parser?: any;
    parserOptions?: Record<string, any>;
  };
  plugins?: Record<string, any>;
  rules?: Record<string, string | number | Array<string | number | object>>;
  settings?: Record<string, any>;
}

Key Features

Multi-file Type Support

• TypeScript Files (.ts): Core TypeScript linting with type-checking
• React Components (.tsx): React + TypeScript with accessibility rules
• Test Files (.spec.ts): Jest-specific rules for testing
• Config Files (*.config.ts): Relaxed rules for configuration files

Integrated Plugin Ecosystem

• TypeScript ESLint: Type-aware linting and best practices
• React/JSX: Modern React patterns and hooks rules
• Accessibility: Comprehensive a11y checking via jsx-a11y
• Jest: Testing framework rules and DOM utilities
• Import/Export: Module organization and sorting
• Prettier: Code formatting integration
• Perfectionist: Automatic object property sorting
• Regexp: Regular expression linting
• Payload Plugin: Custom rules for Payload CMS patterns

Rule Philosophy

• Type Safety: Emphasis on TypeScript best practices with type checking
• Code Quality: Consistent formatting and modern JavaScript patterns
• Accessibility: Comprehensive WCAG compliance for React components
• Testing: Best practices for Jest and DOM testing utilities
• Payload-specific: Custom rules preventing common CMS configuration mistakes

Configuration Approach

• Flat Config: Uses ESLint 9.x flat configuration format
• Composable: Each configuration can be used independently
• Extensible: Designed to be extended with additional rules
• Type-aware: Leverages TypeScript compiler for advanced linting