1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338# Next.js Development Guide
## Codebase structure
### Monorepo Overview
This is a pnpm monorepo containing the Next.js framework and related packages.
```
next.js/
├── packages/ # Published npm packages
├── turbopack/ # Turbopack bundler (Rust) - git subtree
├── crates/ # Rust crates for Next.js SWC bindings
├── test/ # All test suites
├── examples/ # Example Next.js applications
├── docs/ # Documentation
└── scripts/ # Build and maintenance scripts
```
### Core Package: `packages/next`
The main Next.js framework lives in `packages/next/`. This is what gets published as the `next` npm package.
**Source code** is in `packages/next/src/`.
**Key entry points:**
- Dev server: `src/cli/next-dev.ts` → `src/server/dev/next-dev-server.ts`
- Production server: `src/cli/next-start.ts` → `src/server/next-server.ts`
- Build: `src/cli/next-build.ts` → `src/build/index.ts`
**Compiled output** goes to `packages/next/dist/` (mirrors src/ structure).
### Other Important Packages
- `packages/create-next-app/` - The `create-next-app` CLI tool
- `packages/next-swc/` - Native Rust bindings (SWC transforms)
- `packages/eslint-plugin-next/` - ESLint rules for Next.js
- `packages/font/` - `next/font` implementation
- `packages/third-parties/` - Third-party script integrations
## Git Workflow
**CRITICAL: Use Graphite (`gt`) instead of git for ALL branch and commit operations.**
NEVER use these git commands directly:
- `git push` → use `gt submit --no-edit`
- `git branch` → use `gt create`
**Graphite commands:**
- `gt create <branch-name> -m "message"` - Create a new branch with commit
- `gt modify -a --no-edit` - Stage all and amend current branch's commit
- `gt checkout <branch>` - Switch branches
- `gt sync` - Sync and restack all branches
- `gt submit --no-edit` - Push and create/update PRs
- `gt log short` - View stack status
**Note**: `gt submit` runs in interactive mode by default and won't push in automated contexts. Always use `gt submit --no-edit` or `gt submit -q` when running from Claude.
**Creating PRs with descriptions**: All PRs created require a description. `gt submit --no-edit` creates PRs in draft mode without a description. To add a PR title and description, use `gh pr edit` immediately after submitting. The PR description needs to follow the mandatory format of .github/pull_request_template.md in the repository:
```bash
gt submit --no-edit
gh pr edit <pr-number> --body "Place description here"
```
**Graphite Stack Safety Rules:**
- Graphite force-pushes everything - old commits only recoverable via reflog
- Never have uncommitted changes when switching branches - they get lost during restack
- Never use `git stash` with Graphite - causes conflicts when `gt modify` restacks
- Never use `git checkout HEAD -- <file>` after editing - silently restores unfixed version
- Always use `gt checkout` (not `git checkout`) to switch branches
- `gt modify --no-edit` with unstaged/untracked files stages ALL changes
- `gt sync` pulls FROM remote, doesn't push TO remote
- `gt modify` restacks children locally but doesn't push them
- Always verify with `git status -sb` after stack operations
- When resuming from summarized conversation, never trust cached IDs - re-fetch from git/GitHub API
**Safe multi-branch fix workflow:**
```bash
gt checkout parent-branch
# make edits
gt modify -a --no-edit # Stage all, amend, restack children
git show HEAD -- <files> # VERIFY fix is in commit
gt submit --no-edit # Push immediately
gt checkout child-branch # Already restacked from gt modify
# make edits
gt modify -a --no-edit
git show HEAD -- <files> # VERIFY
gt submit --no-edit
```
## Build Commands
```bash
# Build the Next.js package
pnpm --filter=next build
# Build everything
pnpm build
# Run specific task
pnpm --filter=next exec taskr <task>
```
## Fast Local Development
For iterative development, use watch mode + fast test execution:
**1. Start watch build in background:**
```bash
# Runs taskr in watch mode - auto-rebuilds on file changes
# Use Bash(run_in_background=true) to keep working while it runs
pnpm --filter=next dev
```
**2. Run tests fast (no isolation, no packing):**
```bash
# NEXT_SKIP_ISOLATE=1 - skip packing Next.js for each test (much faster)
# testonly - runs with --runInBand (no worker isolation overhead)
NEXT_SKIP_ISOLATE=1 NEXT_TEST_MODE=dev pnpm testonly test/path/to/test.ts
```
**3. When done, kill the background watch process.**
Only use full `pnpm --filter=next build` for one-off builds (after branch switch, before CI push).
**Always rebuild after switching branches:**
```bash
gt checkout <branch>
pnpm build # Required before running tests (Turborepo dedupes if unchanged)
```
## Testing
```bash
# Run specific test file (development mode with Turbopack)
pnpm test-dev-turbo test/path/to/test.test.ts
# Run tests matching pattern
pnpm test-dev-turbo -t "pattern"
# Run development tests
pnpm test-dev-turbo test/development/
```
**Test commands by mode:**
- `pnpm test-dev-turbo` - Development mode with Turbopack (default)
- `pnpm test-dev-webpack` - Development mode with Webpack
- `pnpm test-start-turbo` - Production build+start with Turbopack
- `pnpm test-start-webpack` - Production build+start with Webpack
**Other test commands:**
- `pnpm test-unit` - Run unit tests only (fast, no browser)
- `pnpm testonly <path>` - Run tests without rebuilding (faster iteration)
- `pnpm new-test` - Generate a new test file from template (interactive)
**Generate tests non-interactively (for AI agents):**
Generating tests using `pnpm new-test` is mandatory.
```bash
# Use --args for non-interactive mode
# Format: pnpm new-test --args <appDir> <name> <type>
# appDir: true/false (is this for app directory?)
# name: test name (e.g. "my-feature")
# type: e2e | production | development | unit
pnpm new-test --args true my-feature e2e
```
## Writing Tests
**Test writing expectations:**
- **Use `pnpm new-test` to generate new test suites** - it creates proper structure with fixture files
- **Use `retry()` from `next-test-utils` instead of `setTimeout` for waiting**
```typescript
// Good - use retry() for polling/waiting
import { retry } from 'next-test-utils'
await retry(async () => {
const text = await browser.elementByCss('p').text()
expect(text).toBe('expected value')
})
// Bad - don't use setTimeout for waiting
await new Promise((resolve) => setTimeout(resolve, 1000))
```
- **Do NOT use `check()` - it is deprecated. Use `retry()` + `expect()` instead**
```typescript
// Deprecated - don't use check()
await check(() => browser.elementByCss('p').text(), /expected/)
// Good - use retry() with expect()
await retry(async () => {
const text = await browser.elementByCss('p').text()
expect(text).toMatch(/expected/)
})
```
- **Prefer real fixture directories over inline `files` objects**
```typescript
// Good - use a real directory with fixture files
const { next } = nextTestSetup({
files: __dirname, // points to directory containing test fixtures
})
// Avoid - inline file definitions are harder to maintain
const { next } = nextTestSetup({
files: {
'app/page.tsx': `export default function Page() { ... }`,
},
})
```
## Linting and Types
```bash
pnpm lint # Full lint (types, prettier, eslint, ast-grep)
pnpm lint-fix # Auto-fix lint issues
pnpm prettier-fix # Fix formatting only
pnpm types # TypeScript type checking
```
## Investigating CI Test Failures
**Use `/ci-failures` for automated analysis** - analyzes failing jobs in parallel and groups by test file.
**CI Analysis Tips:**
- Don't spawn too many parallel agents hitting GitHub API (causes rate limits)
- Prioritize blocking jobs first: lint, types, then test jobs
- Use `gh api` for logs (works on in-progress runs), not `gh run view --log`
**Quick triage:**
```bash
# List failed jobs for a PR
gh pr checks <pr-number> | grep fail
# Get failed job names
gh run view <run-id> --json jobs --jq '.jobs[] | select(.conclusion == "failure") | .name'
# Search job logs for errors (completed runs only - use gh api for in-progress)
gh run view <run-id> --job <job-id> --log 2>&1 | grep -E "FAIL|Error|error:" | head -30
```
**Common failure patterns:**
- `rust check / build` → Run `cargo fmt -- --check` locally, fix with `cargo fmt`
- `lint / build` → Run `pnpm prettier --write <file>` for prettier errors
- Test failures → Run the specific test locally with `pnpm test-dev-turbo <test-path>`
**Run tests in the right mode:**
```bash
# Dev mode (Turbopack)
pnpm test-dev-turbo test/path/to/test.ts
# Prod mode
pnpm test-start-turbo test/path/to/test.ts
```
## Key Directories (Quick Reference)
See [Codebase structure](#codebase-structure) above for detailed explanations.
- `packages/next/src/` - Main Next.js source code
- `packages/next/src/server/` - Server runtime (most changes happen here)
- `packages/next/src/client/` - Client-side runtime
- `packages/next/src/build/` - Build tooling
- `test/e2e/` - End-to-end tests
- `test/development/` - Dev server tests
- `test/production/` - Production build tests
- `test/unit/` - Unit tests (fast, no browser)
## Development Tips
- The dev server entry point is `packages/next/src/cli/next-dev.ts`
- Router server: `packages/next/src/server/lib/router-server.ts`
- Use `DEBUG=next:*` for debug logging
- Use `NEXT_TELEMETRY_DISABLED=1` when testing locally
## Commit and PR Style
- Do NOT add "Generated with Claude Code" or co-author footers to commits or PRs
- Keep commit messages concise and descriptive
- PR descriptions should focus on what changed and why
- Do NOT mark PRs as "ready for review" (`gh pr ready`) - leave PRs in draft mode and let the user decide when to mark them ready
## Rebuilding Before Running Tests
When running Next.js integration tests, you must rebuild if source files have changed:
- **Edited Next.js code?** → `pnpm build`
- **Edited Turbopack (Rust)?** → `pnpm swc-build-native`
- **Edited both?** → `pnpm turbo build build-native`
## Development Anti-Patterns
### Test Gotchas
- Mode-specific tests need `skipStart: true` + manual `next.start()` in `beforeAll` after mode check
- Don't rely on exact log messages - filter by content patterns, find sequences not positions
### Rust/Cargo
- cargo fmt uses ASCII order (uppercase before lowercase) - just run `cargo fmt`
- **Internal compiler error (ICE)?** Delete incremental compilation artifacts and retry. Remove `*/incremental` directories from your cargo target directory (default `target/`, or check `CARGO_TARGET_DIR` env var)
### Node.js Source Maps
- `findSourceMap()` needs `--enable-source-maps` flag or returns undefined
- Source map paths vary (webpack: `./src/`, tsc: `src/`) - try multiple formats
- `process.cwd()` in stack trace formatting produces different paths in tests vs production
### Documentation Code Blocks
- When adding `highlight={...}` attributes to code blocks, carefully count the actual line numbers within the code block
- Account for empty lines, import statements, and type imports that shift line numbers
- Highlights should point to the actual relevant code, not unrelated lines like `return (` or framework boilerplate
- Double-check highlights by counting lines from 1 within each code block