0
# @next/eslint-plugin-next
1

2
A comprehensive ESLint plugin specifically designed for Next.js applications, providing 21 specialized linting rules that enforce Next.js best practices and optimize Core Web Vitals performance. The plugin includes preset configurations for both general Next.js development and performance-focused linting.
3

4
## Package Information
5

6
- **Package Name**: @next/eslint-plugin-next
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install --save-dev @next/eslint-plugin-next`
10

11
## Core Imports
12

13
### ESM Import
14
```typescript
15
import plugin from "@next/eslint-plugin-next";
16
import { rules, configs, flatConfig } from "@next/eslint-plugin-next";
17
```
18

19
### CommonJS Import
20
```javascript
21
const plugin = require("@next/eslint-plugin-next");
22
const { rules, configs, flatConfig } = require("@next/eslint-plugin-next");
23
```
24

25
## Basic Usage
26

27
### Legacy ESLint Configuration
28
```javascript
29
// .eslintrc.js
30
module.exports = {
31
  extends: ["plugin:@next/next/recommended"],
32
  // Or for performance focus:
33
  // extends: ["plugin:@next/next/core-web-vitals"],
34
};
35
```
36

37
### Flat ESLint Configuration
38
```javascript
39
// eslint.config.js
40
import { flatConfig } from "@next/eslint-plugin-next";
41

42
export default [
43
  flatConfig.recommended,
44
  // Or for performance focus:
45
  // flatConfig.coreWebVitals,
46
];
47
```
48

49
## Architecture
50

51
The plugin is organized around several key components:
52

53
- **Rules Engine**: 21 individual ESLint rules targeting specific Next.js patterns and performance optimizations
54
- **Configuration Presets**: Pre-configured rule sets for different use cases (recommended, core-web-vitals)
55
- **Multi-Format Support**: Compatible with both legacy and flat ESLint configuration formats
56

57
## Capabilities
58

59
### Rule Configurations
60

61
Pre-configured ESLint rule sets optimized for different Next.js development scenarios.
62

63
```typescript { .api }
64
interface PluginConfigs {
65
  recommended: {
66
    plugins: string[];
67
    rules: Record<string, 'warn' | 'error'>;
68
  };
69
  'core-web-vitals': {
70
    plugins: string[];
71
    extends: string[];
72
    rules: Record<string, 'error'>;
73
  };
74
}
75

76
interface FlatConfig {
77
  recommended: {
78
    name: string;
79
    plugins: Record<string, any>;
80
    rules: Record<string, 'warn' | 'error'>;
81
  };
82
  coreWebVitals: {
83
    name: string;
84
    plugins: Record<string, any>;
85
    rules: Record<string, 'warn' | 'error'>;
86
  };
87
}
88
```
89

90
[Configurations](./configurations.md)
91

92
### Performance & Core Web Vitals Rules
93

94
Rules focused on optimizing loading performance and Core Web Vitals metrics.
95

96
```typescript { .api }
97
interface PerformanceRules {
98
  'google-font-display': Rule.RuleModule;
99
  'google-font-preconnect': Rule.RuleModule;
100
  'no-html-link-for-pages': Rule.RuleModule;
101
  'no-sync-scripts': Rule.RuleModule;
102
  'no-img-element': Rule.RuleModule;
103
  'no-page-custom-font': Rule.RuleModule;
104
}
105
```
106

107
[Performance Rules](./performance-rules.md)
108

109
### Document & Head Management Rules
110

111
Rules for proper Next.js document structure and head element management.
112

113
```typescript { .api }
114
interface DocumentRules {
115
  'no-head-element': Rule.RuleModule;
116
  'no-head-import-in-document': Rule.RuleModule;
117
  'no-document-import-in-page': Rule.RuleModule;
118
  'no-duplicate-head': Rule.RuleModule;
119
  'no-title-in-document-head': Rule.RuleModule;
120
  'no-styled-jsx-in-document': Rule.RuleModule;
121
}
122
```
123

124
[Document Rules](./document-rules.md)
125

126
### Script & Asset Management Rules
127

128
Rules for proper script loading and asset management in Next.js applications.
129

130
```typescript { .api }
131
interface ScriptRules {
132
  'inline-script-id': Rule.RuleModule;
133
  'next-script-for-ga': Rule.RuleModule;
134
  'no-before-interactive-script-outside-document': Rule.RuleModule;
135
  'no-script-component-in-head': Rule.RuleModule;
136
  'no-unwanted-polyfillio': Rule.RuleModule;
137
  'no-css-tags': Rule.RuleModule;
138
}
139
```
140

141
[Script Rules](./script-rules.md)
142

143
### Code Quality & Convention Rules
144

145
Rules for enforcing Next.js conventions and preventing common mistakes.
146

147
```typescript { .api }
148
interface ConventionRules {
149
  'no-assign-module-variable': Rule.RuleModule;
150
  'no-async-client-component': Rule.RuleModule;
151
  'no-typos': Rule.RuleModule;
152
}
153
```
154

155
[Convention Rules](./convention-rules.md)
156

157
## Types
158

159
```typescript { .api }
160
import type { Rule } from 'eslint';
161

162
interface ESLintPlugin {
163
  rules: Record<string, Rule.RuleModule>;
164
  configs: {
165
    recommended: {
166
      plugins: string[];
167
      rules: Record<string, 'warn' | 'error'>;
168
    };
169
    'core-web-vitals': {
170
      plugins: string[];
171
      extends: string[];
172
      rules: Record<string, 'error'>;
173
    };
174
  };
175
}
176

177
interface ValidationError {
178
  message: string;
179
  line?: number;
180
  column?: number;
181
  severity: 'error' | 'warn';
182
}
183
```