0
# Document & Head Management Rules
1

2
ESLint rules for proper Next.js document structure and head element management. These rules ensure correct usage of Next.js Head component and proper document architecture patterns.
3

4
## Capabilities
5

6
### no-head-element
7

8
Prevents HTML head elements in favor of Next.js Head component for better SSR and hydration.
9

10
```typescript { .api }
11
/**
12
 * Rule: no-head-element
13
 * Prevents HTML head elements, promotes Next.js Head component
14
 * Severity: warn (in recommended config)
15
 * Category: Document Structure
16
 */
17
interface NoHeadElementRule extends Rule.RuleModule {
18
  meta: {
19
    docs: {
20
      description: 'Prevent usage of HTML head element';
21
      category: 'Document Structure';
22
      recommended: true;
23
      url: string;
24
    };
25
    type: 'problem';
26
    schema: [];
27
  };
28
}
29
```
30

31
**Validates:** Head content uses Next.js Head component
32
**Prevents:** Direct HTML head manipulation that breaks SSR
33

34
### no-head-import-in-document
35

36
Prevents Head component import in _document.js files where it shouldn't be used.
37

38
```typescript { .api }
39
/**
40
 * Rule: no-head-import-in-document
41
 * Prevents Head import in _document.js files
42
 * Severity: error (in recommended config)
43
 * Category: Document Structure
44
 */
45
interface NoHeadImportInDocumentRule extends Rule.RuleModule {
46
  meta: {
47
    docs: {
48
      description: 'Prevent Head import in _document.js';
49
      category: 'Document Structure';
50
      recommended: true;
51
      url: string;
52
    };
53
    type: 'problem';
54
    schema: [];
55
  };
56
}
57
```
58

59
**Validates:** Head component is not imported in _document.js files
60
**Prevents:** Incorrect Head usage that can cause hydration issues
61

62
### no-document-import-in-page
63

64
Prevents Document component import in page files where it's not appropriate.
65

66
```typescript { .api }
67
/**
68
 * Rule: no-document-import-in-page
69
 * Prevents Document import in page files
70
 * Severity: error (in recommended config)
71
 * Category: Document Structure
72
 */
73
interface NoDocumentImportInPageRule extends Rule.RuleModule {
74
  meta: {
75
    docs: {
76
      description: 'Prevent Document import in page files';
77
      category: 'Document Structure';
78
      recommended: true;
79
      url: string;
80
    };
81
    type: 'problem';
82
    schema: [];
83
  };
84
}
85
```
86

87
**Validates:** Document component is only used in _document.js
88
**Prevents:** Incorrect Document usage that breaks Next.js architecture
89

90
### no-duplicate-head
91

92
Prevents multiple Head components in the same file to avoid conflicts.
93

94
```typescript { .api }
95
/**
96
 * Rule: no-duplicate-head
97
 * Prevents multiple Head components in same file
98
 * Severity: error (in recommended config)
99
 * Category: Document Structure
100
 */
101
interface NoDuplicateHeadRule extends Rule.RuleModule {
102
  meta: {
103
    docs: {
104
      description: 'Prevent duplicate Head components';
105
      category: 'Document Structure';
106
      recommended: true;
107
      url: string;
108
    };
109
    type: 'problem';
110
    schema: [];
111
  };
112
}
113
```
114

115
**Validates:** Only one Head component per file
116
**Prevents:** Conflicting head content and hydration issues
117

118
### no-title-in-document-head
119

120
Prevents title elements in _document.js Head component where they're ineffective.
121

122
```typescript { .api }
123
/**
124
 * Rule: no-title-in-document-head
125
 * Prevents title in _document.js Head component
126
 * Severity: warn (in recommended config)
127
 * Category: Document Structure
128
 */
129
interface NoTitleInDocumentHeadRule extends Rule.RuleModule {
130
  meta: {
131
    docs: {
132
      description: 'Prevent title in _document.js Head';
133
      category: 'Document Structure';
134
      recommended: true;
135
      url: string;
136
    };
137
    type: 'problem';
138
    schema: [];
139
  };
140
}
141
```
142

143
**Validates:** Title elements are not in _document.js Head
144
**Prevents:** Ineffective title tags that don't work in _document
145

146
### no-styled-jsx-in-document
147

148
Prevents styled-jsx usage in _document.js where it can cause issues.
149

150
```typescript { .api }
151
/**
152
 * Rule: no-styled-jsx-in-document
153
 * Prevents styled-jsx in _document.js files
154
 * Severity: warn (in recommended config)
155
 * Category: Document Structure
156
 */
157
interface NoStyledJsxInDocumentRule extends Rule.RuleModule {
158
  meta: {
159
    docs: {
160
      description: 'Prevent styled-jsx in _document.js';
161
      category: 'Document Structure';
162
      recommended: true;
163
      url: string;
164
    };
165
    type: 'problem';
166
    schema: [];
167
  };
168
}
169
```
170

171
**Validates:** styled-jsx is not used in _document.js files
172
**Prevents:** Styling issues and hydration problems in document structure
173

174
## Usage Examples
175

176
### Correct Head Usage
177

178
```jsx
179
// ✅ Correct - Using Next.js Head component in pages
180
import Head from 'next/head';
181

182
export default function MyPage() {
183
  return (
184
    <>
185
      <Head>
186
        <title>My Page Title</title>
187
        <meta name="description" content="Page description" />
188
      </Head>
189
      <div>Page content</div>
190
    </>
191
  );
192
}
193
```
194

195
### Correct Document Structure
196

197
```jsx
198
// ✅ Correct - _document.js structure
199
import { Html, Head, Main, NextScript } from 'next/document';
200

201
export default function Document() {
202
  return (
203
    <Html>
204
      <Head>
205
        {/* Global meta tags, fonts, analytics - NO title tags */}
206
        <link rel="preconnect" href="https://fonts.googleapis.com" />
207
      </Head>
208
      <body>
209
        <Main />
210
        <NextScript />
211
      </body>
212
    </Html>
213
  );
214
}
215
```
216

217
### Document Rules Configuration
218

219
```javascript
220
// Focus on document structure validation
221
module.exports = {
222
  plugins: ['@next/next'],
223
  rules: {
224
    // Critical document structure rules as errors
225
    '@next/next/no-head-import-in-document': 'error',
226
    '@next/next/no-document-import-in-page': 'error',
227
    '@next/next/no-duplicate-head': 'error',
228
    
229
    // Best practice rules as warnings
230
    '@next/next/no-head-element': 'warn',
231
    '@next/next/no-title-in-document-head': 'warn',
232
    '@next/next/no-styled-jsx-in-document': 'warn',
233
  },
234
};
235
```
236

237
## Rule Categories
238

239
- **Component Separation**: no-head-import-in-document, no-document-import-in-page
240
- **Content Management**: no-duplicate-head, no-title-in-document-head
241
- **Best Practices**: no-head-element, no-styled-jsx-in-document
242

243
## Common Patterns
244

245
### Page-Level Head Management
246
- Use Next.js Head component in pages and components
247
- Each page can have its own Head with title and meta tags
248
- Head content merges and overrides appropriately
249

250
### Document-Level Configuration
251
- Use _document.js for global head content only
252
- Include fonts, analytics, and global meta tags
253
- Avoid page-specific content like titles
254

255
### Error Prevention
256
- These rules prevent common mistakes that can break SSR/hydration
257
- Enforce proper separation between document and page-level head content
258
- Maintain Next.js architectural patterns