### What?
When profiling is enabled (`--experimental-cpu-prof` /
`--internal-trace`, or the `NEXT_CPU_PROF` / `NEXT_TURBOPACK_TRACING`
env vars), Next.js writes a `.gitignore` containing `*` into
`.next-profiles/` as it creates the directory. This keeps the profiling
output out of git and out of the way of tools that scan the project
tree.
### Why?
`.next-profiles` is a sibling of `.next`, so it's intentionally *not*
covered by the `.gitignore` create-next-app ships. The motivation was
that profiles wouldn't bloat `.next` and wouldn't be silently ignored.
But a sibling dir full of large profile/trace files turns out to be a
liability:
- **Ecosystem tools scan it.** Tailwind v4 aggressively auto-scans files
and has opened a `trace-turbopack.bin` and crashed; Turborepo <2.8.13
hashes the file and OOMs, and >=2.8.13 fails to start `dev` watchers
because reading the large trace is too slow. (workflow watchers are
likely affected too.)
- **Turbopack NFT globbing** can read/hash the file via overly broad
`fs.read` patterns.
- **Accidental commits.** Pushing a multi-GB trace would be miserable
for a customer helping us debug.
These have each gotten point bandaids (#94587, #94570), but the real fix
preserves the original motivation: a nested `.gitignore` with `*` keeps
the files off git **and** makes gitignore-respecting tools (Tailwind,
Turborepo) skip the whole subtree, which resolves the scanning failures.
Reverting to `.next/profiles` was the alternative; the gitignore
approach keeps the existing path.
### How?
- `ensureProfilesDir()` (`packages/next/src/lib/profiles-dir.ts`)
creates `.next-profiles` and writes the `.gitignore` (only if absent, so
user edits survive). Single source of truth.
- `bin/next.ts` calls a `setupProfilesDir()` helper on build/dev/start,
gated on the env vars so both the CLI flags and direct env-var usage are
covered. Skipped when `NEXT_TURBOPACK_TRACING_PATH` redirects trace
output.
- Rust keeps `create_dir_all` as a backstop for the trace dir; the
`.gitignore` is written in JS only.
- Docs switched from `NEXT_TURBOPACK_TRACING=1` to `next dev
--internal-trace`, and the stale `trace-turbopack` filename corrected to
`trace-turbopack.bin`.
<!-- NEXT_JS_LLM_PR -->
Fixed two missing words and inconsistent capitalization in
`contributing/turbopack/tracing.md`:
- "And there different value modes" → "And there `are` different value
modes"
- "more information how to create one" → "more information `on` how to
create one"
- "Persistently `allocated` Memory" → "Persistently `Allocated` Memory"
Luke Sandberg