|
| 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 |
| 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 | + |
| 24 | +**Safe multi-branch fix workflow:** |
| 25 | + |
| 26 | +```bash |
| 27 | +gt checkout parent-branch |
| 28 | +# make edits |
| 29 | +gt modify -a --no-edit # Stage all, amend, restack children |
| 30 | +git show HEAD -- <files> # VERIFY fix is in commit |
| 31 | +gt submit --no-edit # Push immediately |
| 32 | + |
| 33 | +gt checkout child-branch # Already restacked from gt modify |
| 34 | +# make edits |
| 35 | +gt modify -a --no-edit |
| 36 | +git show HEAD -- <files> # VERIFY |
| 37 | +gt submit --no-edit |
| 38 | +``` |
| 39 | + |
| 40 | +## Build Commands |
| 41 | + |
| 42 | +```bash |
| 43 | +# Build the Next.js package (dev server only - faster) |
| 44 | +pnpm --filter=next build:dev-server |
| 45 | + |
| 46 | +# Build everything |
| 47 | +pnpm build |
| 48 | + |
| 49 | +# Run specific task |
| 50 | +pnpm --filter=next taskfile <task> |
| 51 | +``` |
| 52 | + |
| 53 | +## Fast Local Development |
| 54 | + |
| 55 | +For iterative development, use watch mode + fast test execution: |
| 56 | + |
| 57 | +**1. Start watch build in background:** |
| 58 | + |
| 59 | +```bash |
| 60 | +# Runs taskr in watch mode - auto-rebuilds on file changes |
| 61 | +# Use Bash(run_in_background=true) to keep working while it runs |
| 62 | +pnpm --filter=next dev |
| 63 | +``` |
| 64 | + |
| 65 | +**2. Run tests fast (no isolation, no packing):** |
| 66 | + |
| 67 | +```bash |
| 68 | +# NEXT_SKIP_ISOLATE=1 - skip packing Next.js for each test (much faster) |
| 69 | +# testonly - runs with --runInBand (no worker isolation overhead) |
| 70 | +NEXT_SKIP_ISOLATE=1 NEXT_TEST_MODE=dev pnpm testonly test/path/to/test.ts |
| 71 | +``` |
| 72 | + |
| 73 | +**3. When done, kill the background watch process.** |
| 74 | + |
| 75 | +Only use full `pnpm --filter=next build` for one-off builds (after branch switch, before CI push). |
| 76 | + |
| 77 | +## Testing |
| 78 | + |
| 79 | +```bash |
| 80 | +# Run specific test file |
| 81 | +pnpm jest test/path/to/test.test.ts |
| 82 | + |
| 83 | +# Run tests matching pattern |
| 84 | +pnpm jest -t "pattern" |
| 85 | + |
| 86 | +# Run development tests |
| 87 | +pnpm testheadless test/development/ |
| 88 | +``` |
| 89 | + |
| 90 | +## Investigating CI Test Failures |
| 91 | + |
| 92 | +**Quick triage:** |
| 93 | + |
| 94 | +```bash |
| 95 | +# List failed jobs for a PR |
| 96 | +gh pr checks <pr-number> | grep fail |
| 97 | + |
| 98 | +# Get failed job names |
| 99 | +gh run view <run-id> --json jobs --jq '.jobs[] | select(.conclusion == "failure") | .name' |
| 100 | + |
| 101 | +# Search job logs for errors |
| 102 | +gh run view <run-id> --job <job-id> --log 2>&1 | grep -E "FAIL|Error|error:" | head -30 |
| 103 | +``` |
| 104 | + |
| 105 | +**Common failure patterns:** |
| 106 | + |
| 107 | +- `rust check / build` → Run `cargo fmt -- --check` locally, fix with `cargo fmt` |
| 108 | +- `lint / build` → Run `pnpm prettier --write <file>` for prettier errors |
| 109 | +- Test failures → Run the specific test locally with `NEXT_TEST_MODE=dev pnpm jest <test-path>` |
| 110 | + |
| 111 | +**Run tests in the right mode:** |
| 112 | + |
| 113 | +```bash |
| 114 | +# Dev mode (Turbopack) |
| 115 | +NEXT_TEST_MODE=dev pnpm jest test/path/to/test.ts |
| 116 | + |
| 117 | +# Prod mode |
| 118 | +NEXT_TEST_MODE=start pnpm jest test/path/to/test.ts |
| 119 | +``` |
| 120 | + |
| 121 | +## Key Directories |
| 122 | + |
| 123 | +- `packages/next/src/` - Main Next.js source code |
| 124 | + - `server/` - Server runtime (dev server, router, rendering) |
| 125 | + - `client/` - Client-side code |
| 126 | + - `build/` - Build tooling (webpack, turbopack configs) |
| 127 | + - `cli/` - CLI entry points |
| 128 | +- `packages/next/dist/` - Compiled output |
| 129 | +- `turbopack/` - Turbopack bundler (Rust) |
| 130 | +- `test/` - Test suites |
| 131 | + - `development/` - Dev server tests |
| 132 | + - `production/` - Production build tests |
| 133 | + - `e2e/` - End-to-end tests |
| 134 | + |
| 135 | +## Development Tips |
| 136 | + |
| 137 | +- The dev server entry point is `packages/next/src/cli/next-dev.ts` |
| 138 | +- Router server: `packages/next/src/server/lib/router-server.ts` |
| 139 | +- Use `DEBUG=next:*` for debug logging |
| 140 | +- Use `NEXT_TELEMETRY_DISABLED=1` when testing locally |
| 141 | + |
| 142 | +## Commit and PR Style |
| 143 | + |
| 144 | +- Do NOT add "Generated with Claude Code" or co-author footers to commits or PRs |
| 145 | +- Keep commit messages concise and descriptive |
| 146 | +- PR descriptions should focus on what changed and why |
0 commit comments