development workflow

9 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Watch mode for fast iterative development

For iterative development, start pnpm --filter=next dev in a separate terminal session before making edits (unless already running). This auto-rebuilds on file changes in approximately 1-2 seconds per change, versus approximately 60 seconds for a full build. Keep this running while iterating on code.

Linting and type checking commands

Linting and type checking commands: pnpm lint (full lint including types, prettier, eslint, ast-grep), pnpm lint-fix (auto-fix lint issues), pnpm prettier-fix (fix formatting only), pnpm types (TypeScript type checking). Use pnpm types (~10s) instead of pnpm --filter=next build (~60s) for checking type errors only.

Type checking must use repo's own commands

Type-check with the repo's commands like pnpm typescript which runs tsc --noEmit against the root tsconfig.json. This includes scripts/**/*.js and loads the repo's type augmentations. A hand-rolled tsconfig pointed at a single file misses those augmentations and will report clean while CI fails. For example, NodeJS.ProcessEnv is declared in packages/next/types/global.d.ts with NODE_ENV required.

PR status analysis with pr-status script

When analyzing CI failures or PR reviews, run: node scripts/pr-status.js (auto-detects PR from current branch) or node scripts/pr-status.js <number> (specific PR by number). This generates analysis files in scripts/pr-status/.

General CI triage rules

When triaging CI failures: prioritize blocking failures first (build, lint, types, then tests), assume failures are real until disproven, reproduce with the same CI mode/env vars (especially IS_WEBPACK_TEST=1 when present), and for module-resolution/build-graph fixes use the normal mode-specific test command so package resolution is exercised.

Branch PRs vs Fork PRs for GitHub

Branch PRs are where the branch is part of vercel/next.js repository (created by Vercel employees). Fork PRs are external contributions from forks not owned by vercel. Cannot write full descriptions for fork PRs targeting vercel/next.js. Can write descriptions for branch PRs and local commits. Can write titles and messages for local commits and assist with translation to English.

Task decomposition and verification workflow

Split work into smaller, individually verifiable tasks before starting. Break the overall goal into incremental steps where each step produces a result that can be checked independently. Verify each task before moving on to the next using appropriate methods (unit tests, integration tests, type checking, linting, building, or manual inspection). When unclear how to verify a change, ask the user before moving on.

Rust/Cargo formatting and conventions

cargo fmt uses ASCII order (uppercase before lowercase) - just run cargo fmt. Avoid adding new super:: imports except in inline mod blocks (e.g. mod tests { ... }) - prefer crate:: rooted paths to make imports consistent and easier to grep for.

Internal compiler error (ICE) recovery in Cargo

If Turbopack produces unexpected errors after switching branches or pulling, check if packages/next-swc/native/*.node is stale. Delete it and run pnpm install to get the npm-published binary instead of a locally-built one. If experiencing internal compiler error (ICE), delete incremental compilation artifacts - remove */incremental directories from cargo target directory (default target/, or check CARGO_TARGET_DIR env var) and retry.

Give your agent this brain