TypeScript 27,423 FILES 8 FINDINGS

HOW NEXT.JS
ACTUALLY WORKS

The React framework for the web. Conventions, patterns, and architecture extracted from the vercel/next.js repository by sourcebook.

VIEW_REPO north_east

QUICK_REF:

Testing: Jest. Test utilities in: turbopack/crates/turbopack-tracing/tests/node-file-trace/integration/ts-paths/fixtures/root.js.

WHAT_MATTERS

→
TypeScript strict mode is OFF — agents shouldn't add strict type annotations
→
This is a monorepo — check workspace dependencies before modifying shared code
→
Generated files detected — editing them directly will break builds
→
packages/next/src/shared/lib/invariant-error.ts is a hub file (imported by 54 files) — changes here ripple everywhere

KEY_FINDINGS

Strict mode is OFF. Don't add strict type annotations that would break existing patterns.

HIGH

Path aliases configured: development-sandbox, next-test-utils, next-webdriver, e2e-utils, test-data-service, test-log, router-act, @next/playwright. Use these instead of relative imports.

HIGH

This is a monorepo. Changes may affect multiple packages. Check workspace dependencies before modifying shared code.

HIGH

Tests use Jest. Test utilities in: turbopack/crates/turbopack-tracing/tests/node-file-trace/integration/ts-paths/fixtures/root.js.

HIGH

4 test files

Generated files detected (test/integration/relay-graphql-swc-single-project/queries/__generated__/pagesQuery.graphql.ts, test/integration/relay-graphql-swc-multi-project/project-b/__generated__/pagesBQuery.graphql.ts, test/integration/relay-graphql-swc-multi-project/project-a/__generated__/pagesAQuery.graphql.ts, examples/with-xata/utils/xata.codegen.ts, examples/with-typescript-graphql/codegen.ts, ...). Do NOT edit these directly — modify the source/schema they are generated from.

HIGH

19 generated files

Hub files (most depended on): packages/next/src/shared/lib/invariant-error.ts (imported by 54 files); packages/next/src/server/config-shared.ts (imported by 49 files); packages/next/src/server/route-modules/app-page/module.compiled.js (imported by 48 files); packages/next/src/server/request/params.ts (imported by 45 files); packages/next/src/shared/lib/app-router-types.ts (imported by 42 files). Changes here have the widest blast radius.

HIGH

Circular import chains detected: describe.ts → compose.ts → index.ts → runner.ts; index.ts → runner.ts; module.js. Avoid adding to these cycles.

HIGH

+ 1 MORE FINDINGS (MEDIUM CONFIDENCE)

UI components live in: turbopack/benchmark-apps/mui/components, test/production/typescript-basic/app/components, test/production/pages-dir/production/fixture/components. Add new components here.

MED

3 component directories

smart_toy USING_AI_TOOLS

→avoid editing generated files — modify the source/schema instead
→check file importance before editing hub files
→follow existing patterns listed in quick reference

CLAUDE.MD expand_more

# CLAUDE.md

This file provides guidance to Claude Code when working with this codebase.
Generated by [sourcebook](https://github.com/maroondlabs/sourcebook). Review and edit — the best context comes from human + machine together.

## Quick Reference

- **testing:** Tests use Jest. Test utilities in: turbopack/crates/turbopack-tracing/tests/node-file-trace/integration/ts-paths/fixtures/root.js.

## Commands

- **Dev:** `turbo run dev --parallel --filter="!@next/bundle-analyzer-ui"`
- **Build:** `turbo run build --remote-cache-timeout 60 --summarize true`
- **Test:** `pnpm test-webpack`
- **Lint:** `run-p test-types lint-typescript prettier-check "lint-eslint ." lint-ast-grep lint-language check-unused-turbo-tasks`
- **test-deploy-inner:** `cross-env NEXT_TEST_MODE=deploy pnpm testheadless`
- **test-deploy:** `pnpm run test-deploy-webpack`
- **test-deploy-webpack:** `pnpm run with-webpack pnpm test-deploy-inner`
- **test-deploy-turbo:** `pnpm run with-turbo pnpm test-deploy-inner`
- **testonly-deploy-inner:** `cross-env NEXT_TEST_MODE=deploy pnpm testonly`
- **testonly-deploy:** `pnpm run testonly-deploy-webpack`
- **testonly-deploy-webpack:** `pnpm run with-webpack pnpm run testonly-deploy-inner`
- **testonly-deploy-turbo:** `pnpm run with-turbo pnpm testonly-deploy-inner`

## Critical Constraints

- **TypeScript:** Strict mode is OFF. Don't add strict type annotations that would break existing patterns.
- **Critical constraints:** Generated files detected (test/integration/relay-graphql-swc-single-project/queries/__generated__/pagesQuery.graphql.ts, test/integration/relay-graphql-swc-multi-project/project-b/__generated__/pagesBQuery.graphql.ts, test/integration/relay-graphql-swc-multi-project/project-a/__generated__/pagesAQuery.graphql.ts, examples/with-xata/utils/xata.codegen.ts, examples/with-typescript-graphql/codegen.ts, ...). Do NOT edit these directly — modify the source/schema they are generated from.
- **Core modules:** Hub files (most depended on): packages/next/src/shared/lib/invariant-error.ts (imported by 54 files); packages/next/src/server/config-shared.ts (imported by 49 files); packages/next/src/server/route-modules/app-page/module.compiled.js (imported by 48 files); packages/next/src/server/request/params.ts (imported by 45 files); packages/next/src/shared/lib/app-router-types.ts (imported by 42 files). Changes here have the widest blast radius.
- **Circular dependencies:** Circular import chains detected: describe.ts → compose.ts → index.ts → runner.ts; index.ts → runner.ts; module.js. Avoid adding to these cycles.

## Stack

Next.js, Expo, Supabase, Tailwind CSS, Express, TypeScript

## Project Structure

- `test/` — Tests
- `scripts/` — Build / utility scripts
- `docs/` — Documentation

## Core Modules (by structural importance)

- `turbopack/crates/turbopack-tests/tests/execution/turbopack/chunking/combinations/input/d.js`
- `packages/next/src/shared/lib/invariant-error.ts`
- `packages/next/src/shared/lib/app-router-types.ts`
- `packages/next/src/shared/lib/segment-cache/vary-params-decoding.ts`
- `turbopack/packages/devlow-bench/src/runner.ts`

## Conventions & Patterns

- **TypeScript imports:** Path aliases configured: development-sandbox, next-test-utils, next-webdriver, e2e-utils, test-data-service, test-log, router-act, @next/playwright. Use these instead of relative imports.
- **Project structure:** This is a monorepo. Changes may affect multiple packages. Check workspace dependencies before modifying shared code.
- **Dominant patterns:** Tests use Jest. Test utilities in: turbopack/crates/turbopack-tracing/tests/node-file-trace/integration/ts-paths/fixtures/root.js.

## Additional Context

- **Dominant patterns:** UI components live in: turbopack/benchmark-apps/mui/components, test/production/typescript-basic/app/components, test/production/pages-dir/production/fixture/components. Add new components here.

## Before Making Changes

- **Check file importance** before editing. Hub files (listed in Core Modules) affect many other files — changes here have the widest blast radius.
- **Follow existing patterns.** This project has established conventions (listed above). Match them instead of introducing new approaches.
- **Respect constraints.** Review the Critical Constraints section before making structural changes.

If the sourcebook MCP server is available (`sourcebook serve`), verify before acting:
- `get_blast_radius` — check what breaks if you edit a hub file
- `query_conventions` — confirm the right pattern before adding new code
- `get_pressing_questions` — get a briefing before editing an unfamiliar file

## What to Add Manually

The most valuable context is what only you know. Add:

- Architectural decisions and why they were made
- Past incidents that shaped current conventions
- Deprecated patterns to avoid in new code
- Domain-specific rules or terminology
- Environment setup beyond what .env.example shows

GENERATED IN ~3 SECONDS WITH

npx sourcebook init

VIEW ON GITHUB star

RELATED_REPOS

CAL.COM SUPABASE

HOW NEXT.JSACTUALLY WORKS

WHAT_MATTERS

KEY_FINDINGS

npx sourcebook init

RELATED_REPOS

HOW NEXT.JS
ACTUALLY WORKS