0
# @payloadcms/eslint-config
1

2
@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.
3

4
## Package Information
5

6
- **Package Name**: @payloadcms/eslint-config
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES Modules)
9
- **Installation**: `npm install @payloadcms/eslint-config`
10

11
## Core Imports
12

13
```javascript
14
import eslintConfig from "@payloadcms/eslint-config";
15
```
16

17
For named imports:
18

19
```javascript
20
import { rootEslintConfig } from "@payloadcms/eslint-config";
21
```
22

23
## Basic Usage
24

25
```javascript
26
// eslint.config.js (ESLint 9.x flat config)
27
import payloadEslintConfig from "@payloadcms/eslint-config";
28

29
export default payloadEslintConfig;
30
```
31

32
## Architecture
33

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

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

42
## Capabilities
43

44
### Main Configuration Export
45

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

48
```javascript { .api }
49
/**
50
 * Main ESLint configuration array containing 5 distinct configurations
51
 * for different file types and contexts
52
 */
53
declare const rootEslintConfig: Config[];
54

55
/**
56
 * Default export (same as rootEslintConfig)
57
 */
58
declare const _default: Config[];
59
export default _default;
60
export { rootEslintConfig };
61
```
62

63
The configuration array includes:
64

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

71
### Deep Merge Utility
72

73
Utility function for recursively merging configuration objects with array handling.
74

75
```javascript { .api }
76
/**
77
 * Recursively merges multiple objects, handling arrays and nested objects
78
 * @param objs - Objects to merge (later objects take priority)
79
 * @returns Merged object
80
 */
81
declare function deepMerge(...objs: any[]): any;
82
```
83

84
**Import:**
85

86
```javascript
87
import { deepMerge } from "@payloadcms/eslint-config/deepMerge.js";
88
```
89

90
**Usage Example:**
91

92
```javascript
93
import { deepMerge } from "@payloadcms/eslint-config/deepMerge.js";
94

95
const config1 = { rules: { "no-console": "warn" } };
96
const config2 = { rules: { "no-unused-vars": "error" } };
97
const merged = deepMerge(config1, config2);
98
// Result: { rules: { "no-console": "warn", "no-unused-vars": "error" } }
99
```
100

101

102
## Types
103

104
```javascript { .api }
105
/**
106
 * ESLint flat configuration object
107
 */
108
interface Config {
109
  name?: string;
110
  files?: string[];
111
  ignores?: string[];
112
  languageOptions?: {
113
    ecmaVersion?: string | number;
114
    sourceType?: "script" | "module";
115
    globals?: Record<string, boolean>;
116
    parser?: any;
117
    parserOptions?: Record<string, any>;
118
  };
119
  plugins?: Record<string, any>;
120
  rules?: Record<string, string | number | Array<string | number | object>>;
121
  settings?: Record<string, any>;
122
}
123
```
124

125
## Key Features
126

127
### Multi-file Type Support
128
- **TypeScript Files** (`.ts`): Core TypeScript linting with type-checking
129
- **React Components** (`.tsx`): React + TypeScript with accessibility rules  
130
- **Test Files** (`.spec.ts`): Jest-specific rules for testing
131
- **Config Files** (`*.config.ts`): Relaxed rules for configuration files
132

133
### Integrated Plugin Ecosystem
134
- **TypeScript ESLint**: Type-aware linting and best practices
135
- **React/JSX**: Modern React patterns and hooks rules
136
- **Accessibility**: Comprehensive a11y checking via jsx-a11y
137
- **Jest**: Testing framework rules and DOM utilities
138
- **Import/Export**: Module organization and sorting
139
- **Prettier**: Code formatting integration
140
- **Perfectionist**: Automatic object property sorting
141
- **Regexp**: Regular expression linting
142
- **Payload Plugin**: Custom rules for Payload CMS patterns
143

144
### Rule Philosophy
145
- **Type Safety**: Emphasis on TypeScript best practices with type checking
146
- **Code Quality**: Consistent formatting and modern JavaScript patterns  
147
- **Accessibility**: Comprehensive WCAG compliance for React components
148
- **Testing**: Best practices for Jest and DOM testing utilities
149
- **Payload-specific**: Custom rules preventing common CMS configuration mistakes
150

151
### Configuration Approach
152
- **Flat Config**: Uses ESLint 9.x flat configuration format
153
- **Composable**: Each configuration can be used independently
154
- **Extensible**: Designed to be extended with additional rules
155
- **Type-aware**: Leverages TypeScript compiler for advanced linting