|
| 1 | +# Next.js Development Guide |
| 2 | + |
| 3 | +## Git Workflow |
| 4 | + |
| 5 | +**Use Graphite for all git operations** instead of raw git commands: |
| 6 | + |
| 7 | +- `gt create <branch-name> -m "message"` - Create a new branch with commit |
| 8 | +- `gt modify -a --no-edit` - Stage all and amend current branch's commit |
| 9 | +- `gt checkout <branch>` - Switch branches (use instead of `git checkout`) |
| 10 | +- `gt sync` - Sync and restack all branches |
| 11 | +- `gt submit --no-edit` - Push and create/update PRs (use `--no-edit` to avoid interactive prompts) |
| 12 | +- `gt log short` - View stack status |
| 13 | + |
| 14 | +**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. |
| 15 | + |
| 16 | +**Graphite Stack Safety Rules:** |
| 17 | + |
| 18 | +- Graphite force-pushes everything - old commits only recoverable via reflog |
| 19 | +- Never have uncommitted changes when switching branches - they get lost during restack |
| 20 | +- Never use `git stash` with Graphite - causes conflicts when `gt modify` restacks |
| 21 | +- Never use `git checkout HEAD -- <file>` after editing - silently restores unfixed version |
| 22 | +- Always use `gt checkout` (not `git checkout`) to switch branches |
| 23 | +- `gt modify --no-edit` with unstaged/untracked files stages ALL changes |
| 24 | +- `gt sync` pulls FROM remote, doesn't push TO remote |
| 25 | +- `gt modify` restacks children locally but doesn't push them |
| 26 | +- Always verify with `git status -sb` after stack operations |
| 27 | +- When resuming from summarized conversation, never trust cached IDs - re-fetch from git/GitHub API |
| 28 | + |
| 29 | +**Safe multi-branch fix workflow:** |
| 30 | + |
| 31 | +```bash |
| 32 | +gt checkout parent-branch |
| 33 | +# make edits |
| 34 | +gt modify -a --no-edit # Stage all, amend, restack children |
| 35 | +git show HEAD -- <files> # VERIFY fix is in commit |
| 36 | +gt submit --no-edit # Push immediately |
| 37 | + |
| 38 | +gt checkout child-branch # Already restacked from gt modify |
| 39 | +# make edits |
| 40 | +gt modify -a --no-edit |
| 41 | +git show HEAD -- <files> # VERIFY |
| 42 | +gt submit --no-edit |
| 43 | +``` |
| 44 | + |
| 45 | +## Build Commands |
| 46 | + |
| 47 | +```bash |
| 48 | +# Build the Next.js package (dev server only - faster) |
| 49 | +pnpm --filter=next build:dev-server |
| 50 | + |
| 51 | +# Build everything |
| 52 | +pnpm build |
| 53 | + |
| 54 | +# Run specific task |
| 55 | +pnpm --filter=next taskfile <task> |
| 56 | +``` |
| 57 | + |
| 58 | +## Fast Local Development |
| 59 | + |
| 60 | +For iterative development, use watch mode + fast test execution: |
| 61 | + |
| 62 | +**1. Start watch build in background:** |
| 63 | + |
| 64 | +```bash |
| 65 | +# Runs taskr in watch mode - auto-rebuilds on file changes |
| 66 | +# Use Bash(run_in_background=true) to keep working while it runs |
| 67 | +pnpm --filter=next dev |
| 68 | +``` |
| 69 | + |
| 70 | +**2. Run tests fast (no isolation, no packing):** |
| 71 | + |
| 72 | +```bash |
| 73 | +# NEXT_SKIP_ISOLATE=1 - skip packing Next.js for each test (much faster) |
| 74 | +# testonly - runs with --runInBand (no worker isolation overhead) |
| 75 | +NEXT_SKIP_ISOLATE=1 NEXT_TEST_MODE=dev pnpm testonly test/path/to/test.ts |
| 76 | +``` |
| 77 | + |
| 78 | +**3. When done, kill the background watch process.** |
| 79 | + |
| 80 | +Only use full `pnpm --filter=next build` for one-off builds (after branch switch, before CI push). |
| 81 | + |
| 82 | +**Always rebuild after switching branches:** |
| 83 | + |
| 84 | +```bash |
| 85 | +gt checkout <branch> |
| 86 | +pnpm --filter=next build # Required before running tests |
| 87 | +``` |
| 88 | + |
| 89 | +## Testing |
| 90 | + |
| 91 | +```bash |
| 92 | +# Run specific test file |
| 93 | +pnpm jest test/path/to/test.test.ts |
| 94 | + |
| 95 | +# Run tests matching pattern |
| 96 | +pnpm jest -t "pattern" |
| 97 | + |
| 98 | +# Run development tests |
| 99 | +pnpm testheadless test/development/ |
| 100 | +``` |
| 101 | + |
| 102 | +## Investigating CI Test Failures |
| 103 | + |
| 104 | +**Use `/ci-failures` for automated analysis** - analyzes failing jobs in parallel and groups by test file. |
| 105 | + |
| 106 | +**CI Analysis Tips:** |
| 107 | + |
| 108 | +- Don't spawn too many parallel agents hitting GitHub API (causes rate limits) |
| 109 | +- Prioritize blocking jobs first: lint, types, then test jobs |
| 110 | +- Use `gh api` for logs (works on in-progress runs), not `gh run view --log` |
| 111 | + |
| 112 | +**Quick triage:** |
| 113 | + |
| 114 | +```bash |
| 115 | +# List failed jobs for a PR |
| 116 | +gh pr checks <pr-number> | grep fail |
| 117 | + |
| 118 | +# Get failed job names |
| 119 | +gh run view <run-id> --json jobs --jq '.jobs[] | select(.conclusion == "failure") | .name' |
| 120 | + |
| 121 | +# Search job logs for errors |
| 122 | +gh run view <run-id> --job <job-id> --log 2>&1 | grep -E "FAIL|Error|error:" | head -30 |
| 123 | +``` |
| 124 | + |
| 125 | +**Common failure patterns:** |
| 126 | + |
| 127 | +- `rust check / build` → Run `cargo fmt -- --check` locally, fix with `cargo fmt` |
| 128 | +- `lint / build` → Run `pnpm prettier --write <file>` for prettier errors |
| 129 | +- Test failures → Run the specific test locally with `NEXT_TEST_MODE=dev pnpm jest <test-path>` |
| 130 | + |
| 131 | +**Run tests in the right mode:** |
| 132 | + |
| 133 | +```bash |
| 134 | +# Dev mode (Turbopack) |
| 135 | +NEXT_TEST_MODE=dev pnpm jest test/path/to/test.ts |
| 136 | + |
| 137 | +# Prod mode |
| 138 | +NEXT_TEST_MODE=start pnpm jest test/path/to/test.ts |
| 139 | +``` |
| 140 | + |
| 141 | +## Key Directories |
| 142 | + |
| 143 | +- `packages/next/src/` - Main Next.js source code |
| 144 | + - `server/` - Server runtime (dev server, router, rendering) |
| 145 | + - `client/` - Client-side code |
| 146 | + - `build/` - Build tooling (webpack, turbopack configs) |
| 147 | + - `cli/` - CLI entry points |
| 148 | +- `packages/next/dist/` - Compiled output |
| 149 | +- `turbopack/` - Turbopack bundler (Rust) |
| 150 | +- `test/` - Test suites |
| 151 | + - `development/` - Dev server tests |
| 152 | + - `production/` - Production build tests |
| 153 | + - `e2e/` - End-to-end tests |
| 154 | + |
| 155 | +## Development Tips |
| 156 | + |
| 157 | +- The dev server entry point is `packages/next/src/cli/next-dev.ts` |
| 158 | +- Router server: `packages/next/src/server/lib/router-server.ts` |
| 159 | +- Use `DEBUG=next:*` for debug logging |
| 160 | +- Use `NEXT_TELEMETRY_DISABLED=1` when testing locally |
| 161 | + |
| 162 | +## Commit and PR Style |
| 163 | + |
| 164 | +- Do NOT add "Generated with Claude Code" or co-author footers to commits or PRs |
| 165 | +- Keep commit messages concise and descriptive |
| 166 | +- PR descriptions should focus on what changed and why |
| 167 | + |
| 168 | +## Development Anti-Patterns |
| 169 | + |
| 170 | +### Testing |
| 171 | + |
| 172 | +- Mode-specific tests need `skipStart: true` + manual `next.start()` in `beforeAll` after mode check |
| 173 | +- Don't rely on exact log messages - filter by content patterns, find sequences not positions |
| 174 | + |
| 175 | +### Rust/Cargo |
| 176 | + |
| 177 | +- cargo fmt uses ASCII order (uppercase before lowercase) - just run `cargo fmt` |
| 178 | + |
| 179 | +### Node.js Source Maps |
| 180 | + |
| 181 | +- `findSourceMap()` needs `--enable-source-maps` flag or returns undefined |
| 182 | +- Source map paths vary (webpack: `./src/`, tsc: `src/`) - try multiple formats |
| 183 | +- `process.cwd()` in stack trace formatting produces different paths in tests vs production |
0 commit comments