0
# Performance & Core Web Vitals Rules
1
2
ESLint rules focused on optimizing loading performance and Core Web Vitals metrics in Next.js applications. These rules help prevent common performance pitfalls and encourage best practices for web performance.
3
4
## Capabilities
5
6
### google-font-display
7
8
Enforces the `font-display` CSS property for Google Fonts to improve loading performance.
9
10
```typescript { .api }
11
/**
12
* Rule: google-font-display
13
* Enforces font-display CSS property for Google Fonts
14
* Severity: warn (in recommended config)
15
* Category: Performance
16
*/
17
interface GoogleFontDisplayRule extends Rule.RuleModule {
18
meta: {
19
docs: {
20
description: 'Enforce font-display CSS property for Google Fonts';
21
category: 'Performance';
22
recommended: true;
23
url: string;
24
};
25
type: 'problem';
26
schema: [];
27
};
28
}
29
```
30
31
**Validates:** Google Font link elements have proper `font-display` parameter
32
**Prevents:** Fonts blocking page render during load
33
34
### google-font-preconnect
35
36
Enforces preconnect resource hints for Google Fonts domains to improve loading performance.
37
38
```typescript { .api }
39
/**
40
* Rule: google-font-preconnect
41
* Enforces preconnect for Google Fonts domains
42
* Severity: warn (in recommended config)
43
* Category: Performance
44
*/
45
interface GoogleFontPreconnectRule extends Rule.RuleModule {
46
meta: {
47
docs: {
48
description: 'Enforce preconnect resource hint for Google Fonts';
49
category: 'Performance';
50
recommended: true;
51
url: string;
52
};
53
type: 'problem';
54
schema: [];
55
};
56
}
57
```
58
59
**Validates:** Preconnect hints are present for Google Font domains
60
**Prevents:** DNS lookup delays for font loading
61
62
### no-html-link-for-pages
63
64
Prevents HTML link elements for internal Next.js pages, promoting client-side navigation.
65
66
```typescript { .api }
67
/**
68
* Rule: no-html-link-for-pages
69
* Prevents HTML link elements for internal Next.js pages
70
* Severity: warn (recommended), error (core-web-vitals)
71
* Category: Performance
72
*/
73
interface NoHtmlLinkForPagesRule extends Rule.RuleModule {
74
meta: {
75
docs: {
76
description: 'Prevent HTML anchor links for Next.js pages';
77
category: 'Performance';
78
recommended: true;
79
url: string;
80
};
81
type: 'suggestion';
82
schema: [];
83
};
84
}
85
```
86
87
**Validates:** Internal navigation uses Next.js Link component
88
**Prevents:** Page refreshes that break SPA navigation benefits
89
90
### no-sync-scripts
91
92
Prevents synchronous scripts that can block page rendering and hurt performance.
93
94
```typescript { .api }
95
/**
96
* Rule: no-sync-scripts
97
* Prevents synchronous scripts that block rendering
98
* Severity: warn (recommended), error (core-web-vitals)
99
* Category: Performance
100
*/
101
interface NoSyncScriptsRule extends Rule.RuleModule {
102
meta: {
103
docs: {
104
description: 'Prevent synchronous scripts';
105
category: 'Performance';
106
recommended: true;
107
url: string;
108
};
109
type: 'problem';
110
schema: [];
111
};
112
}
113
```
114
115
**Validates:** Scripts use async, defer, or Next.js Script component
116
**Prevents:** Render-blocking JavaScript that hurts Core Web Vitals
117
118
### no-img-element
119
120
Prevents HTML img elements in favor of Next.js optimized Image component.
121
122
```typescript { .api }
123
/**
124
* Rule: no-img-element
125
* Prevents HTML img elements, promotes Next.js Image component
126
* Severity: warn (in recommended config)
127
* Category: Performance
128
*/
129
interface NoImgElementRule extends Rule.RuleModule {
130
meta: {
131
docs: {
132
description: 'Prevent usage of HTML img element';
133
category: 'Performance';
134
recommended: true;
135
url: string;
136
};
137
type: 'problem';
138
schema: [];
139
};
140
}
141
```
142
143
**Validates:** Images use Next.js Image component instead of HTML img
144
**Prevents:** Unoptimized images that hurt LCP and bandwidth usage
145
**Exceptions:** Allows img elements within picture elements, and in app directory metadata route files
146
147
### no-page-custom-font
148
149
Prevents custom font usage in pages directory files to improve loading performance.
150
151
```typescript { .api }
152
/**
153
* Rule: no-page-custom-font
154
* Prevents custom font usage in pages directory
155
* Severity: warn (in recommended config)
156
* Category: Performance
157
*/
158
interface NoPageCustomFontRule extends Rule.RuleModule {
159
meta: {
160
docs: {
161
description: 'Prevent page-only custom fonts';
162
category: 'Performance';
163
recommended: true;
164
url: string;
165
};
166
type: 'problem';
167
schema: [];
168
};
169
}
170
```
171
172
**Validates:** Custom fonts are loaded globally, not per-page
173
**Prevents:** Font loading performance issues and layout shifts
174
175
## Usage Examples
176
177
### Configuring Performance Rules
178
179
```javascript
180
// Focus on Core Web Vitals optimization
181
module.exports = {
182
extends: ['plugin:@next/next/core-web-vitals'],
183
rules: {
184
// Promote font optimization to error level
185
'@next/next/google-font-display': 'error',
186
'@next/next/google-font-preconnect': 'error',
187
},
188
};
189
```
190
191
### Custom Performance Configuration
192
193
```javascript
194
// eslint.config.js - Custom performance-focused config
195
import { rules } from "@next/eslint-plugin-next";
196
197
export default [
198
{
199
plugins: {
200
'@next/next': { rules },
201
},
202
rules: {
203
// Critical performance rules as errors
204
'@next/next/no-sync-scripts': 'error',
205
'@next/next/no-html-link-for-pages': 'error',
206
'@next/next/no-img-element': 'error',
207
208
// Font optimization as warnings
209
'@next/next/google-font-display': 'warn',
210
'@next/next/google-font-preconnect': 'warn',
211
},
212
},
213
];
214
```
215
216
## Rule Categories
217
218
- **Font Optimization**: google-font-display, google-font-preconnect, no-page-custom-font
219
- **Navigation Performance**: no-html-link-for-pages
220
- **Script Performance**: no-sync-scripts
221
- **Image Optimization**: no-img-element