Skip to content

Commit a7b0469

Browse files
authored
gitignore .next-profiles (#95256)
### 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 -->
1 parent d6f4cd3 commit a7b0469

11 files changed

Lines changed: 100 additions & 39 deletions

File tree

‎contributing/turbopack/tracing.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,25 +20,25 @@ Alternatively, any directives syntax supported by [`tracing_subscriber::filter::
2020
>
2121
> For the more detailed tracing a custom Next.js build is required. See [Developing] for more information on how to create one.
2222
23-
With this environment variable, Next.js will write a `.next-profiles/trace-turbopack` file with the tracing information in a binary format.
23+
With this environment variable, Next.js will write a `.next-profiles/trace-turbopack.bin` file with the tracing information in a binary format.
2424

2525
[presets]: https://github.com/vercel/next.js/blob/c506c0de1d6f17ad400ad5aa85edaae23b6b44d2/packages/next-swc/crates/napi/src/next_api/project.rs#L218
2626
[directives]: https://tracing.rs/tracing_subscriber/filter/struct.envfilter#directives
2727
[Developing]: ../core/developing.md
2828

2929
## Viewer
3030

31-
To visualize the content of `.next-profiles/trace-turbopack`, use the [turbo-trace-viewer].
31+
To visualize the content of `.next-profiles/trace-turbopack.bin`, use the [turbo-trace-viewer].
3232

3333
A video showing how to use the tool [is available here][youtube-tutorial].
3434

3535
This tool connects a WebSocket on port 57475 on localhost to connect to the trace-server. You can start the trace-server with the following command:
3636

3737
```sh
38-
cargo run --bin turbo-trace-server --release -- /path/to/your/trace-turbopack
38+
cargo run --bin turbo-trace-server --release -- /path/to/your/trace-turbopack.bin
3939

4040
# or
41-
pnpm next internal trace .next-profiles/trace-turbopack
41+
pnpm next internal trace .next-profiles/trace-turbopack.bin
4242
```
4343

4444
Once the server is started, open <https://trace.nextjs.org/> in your browser.

‎crates/next-napi-bindings/src/next_api/project.rs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -510,6 +510,9 @@ pub fn project_new(
510510

511511
let subscriber = subscriber.with(FilterLayer::try_new(&trace).unwrap());
512512

513+
// For the default `.next-profiles` location the JS CLI already created
514+
// this directory (with its `.gitignore`) before invoking the binding; this
515+
// is a safety net and also covers a `NEXT_TURBOPACK_TRACING_PATH` override.
513516
std::fs::create_dir_all(&trace_dir)
514517
.with_context(|| {
515518
format!(

‎docs/01-app/02-guides/local-development.mdx‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -236,34 +236,34 @@ It provides detailed information about the time taken for each module to compile
236236
1. Generate a Turbopack trace file:
237237

238238
```bash package="pnpm"
239-
NEXT_TURBOPACK_TRACING=1 pnpm dev
239+
pnpm dev --internal-trace
240240
```
241241

242242
```bash package="npm"
243-
NEXT_TURBOPACK_TRACING=1 npm run dev
243+
npm run dev -- --internal-trace
244244
```
245245

246246
```bash package="yarn"
247-
NEXT_TURBOPACK_TRACING=1 yarn dev
247+
yarn dev --internal-trace
248248
```
249249

250250
```bash package="bun"
251-
NEXT_TURBOPACK_TRACING=1 bun dev
251+
bun dev --internal-trace
252252
```
253253

254254
1. Navigate around your application or make edits to files to reproduce the problem.
255255
1. Stop the Next.js development server.
256-
1. A file called `trace-turbopack` will be available in the `.next-profiles` folder.
256+
1. A file called `trace-turbopack.bin` will be available in the `.next-profiles` folder.
257257
1. You can interpret the file using `npx next internal trace [path-to-file]`:
258258

259259
```bash
260-
npx next internal trace .next-profiles/trace-turbopack
260+
npx next internal trace .next-profiles/trace-turbopack.bin
261261
```
262262

263263
On versions where `trace` is not available, the command was named `turbo-trace-server`:
264264

265265
```bash
266-
npx next internal turbo-trace-server .next-profiles/trace-turbopack
266+
npx next internal turbo-trace-server .next-profiles/trace-turbopack.bin
267267
```
268268

269269
1. Once the trace server is running you can view the trace at https://trace.nextjs.org/.

‎docs/01-app/02-guides/upgrading/version-16.mdx‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -926,19 +926,19 @@ Additionally, a lockfile mechanism prevents multiple `next dev` or `next build`
926926
The [Turbopack tracing command](/docs/app/guides/local-development#turbopack-tracing) should be:
927927

928928
```bash package="pnpm"
929-
pnpm next internal trace .next-profiles/trace-turbopack
929+
pnpm next internal trace .next-profiles/trace-turbopack.bin
930930
```
931931

932932
```bash package="npm"
933-
npx next internal trace .next-profiles/trace-turbopack
933+
npx next internal trace .next-profiles/trace-turbopack.bin
934934
```
935935

936936
```bash package="yarn"
937-
yarn next internal trace .next-profiles/trace-turbopack
937+
yarn next internal trace .next-profiles/trace-turbopack.bin
938938
```
939939

940940
```bash package="bun"
941-
bunx next internal trace .next-profiles/trace-turbopack
941+
bunx next internal trace .next-profiles/trace-turbopack.bin
942942
```
943943

944944
## Parallel Routes `default.js` requirement

‎docs/01-app/03-api-reference/08-turbopack.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -406,13 +406,13 @@ For more in-depth configuration examples, see the [Turbopack config documentatio
406406

407407
## Generating trace files for performance debugging
408408

409-
If you encounter performance or memory issues and want to help the Next.js team diagnose them, you can generate a trace file by appending `NEXT_TURBOPACK_TRACING=1` to your dev command:
409+
If you encounter performance or memory issues and want to help the Next.js team diagnose them, you can generate a trace file by adding the `--internal-trace` flag to your dev command:
410410

411411
```bash
412-
NEXT_TURBOPACK_TRACING=1 next dev
412+
next dev --internal-trace
413413
```
414414

415-
This will produce a `.next-profiles/trace-turbopack` file. Include that file when creating a GitHub issue on the [Next.js repo](https://github.com/vercel/next.js) to help us investigate.
415+
This will produce a `.next-profiles/trace-turbopack.bin` file. Include that file when creating a GitHub issue on the [Next.js repo](https://github.com/vercel/next.js) to help us investigate.
416416

417417
## Summary
418418

‎packages/next/src/bin/next.ts‎

Lines changed: 24 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,27 @@ import type { NextAnalyzeOptions } from '../cli/next-analyze.js'
3232
import type { NextBuildOptions } from '../cli/next-build.js'
3333
import type { NextTypegenOptions } from '../cli/next-typegen.js'
3434
import type { NextPostBuildOptions } from '../cli/next-post-build.js'
35-
import { mkdirSync } from 'fs'
35+
import { ensureProfilesDir } from '../lib/profiles-dir'
36+
37+
/**
38+
* Create `.next-profiles` (with its `.gitignore`) when profiling/tracing is
39+
* enabled — whether via the CLI flags or the env vars directly — so the
40+
* gitignore logic lives in one place. Also points CPU profiles at the directory.
41+
* Skipped for tracing when `NEXT_TURBOPACK_TRACING_PATH` redirects the output.
42+
*/
43+
function setupProfilesDir(dir: string): void {
44+
const cpuProf = !!process.env.NEXT_CPU_PROF
45+
const turbopackTrace =
46+
!!process.env.NEXT_TURBOPACK_TRACING &&
47+
!process.env.NEXT_TURBOPACK_TRACING_PATH
48+
if (!cpuProf && !turbopackTrace) {
49+
return
50+
}
51+
const profilesDir = ensureProfilesDir(dir)
52+
if (cpuProf) {
53+
process.env.NEXT_CPU_PROF_DIR = profilesDir
54+
}
55+
}
3656

3757
if (process.env.NEXT_RSPACK) {
3858
// silent rspack's schema check
@@ -227,18 +247,14 @@ program
227247
if (options.experimentalCpuProf) {
228248
process.env.NEXT_CPU_PROF = '1'
229249
process.env.__NEXT_PRIVATE_CPU_PROFILE = 'build-main'
230-
const { join } = require('path') as typeof import('path')
231-
const dir = directory || process.cwd()
232-
const cpuProfileDir = join(dir, '.next-profiles')
233-
mkdirSync(cpuProfileDir, { recursive: true })
234-
process.env.NEXT_CPU_PROF_DIR = cpuProfileDir
235250
}
236251
if (options.internalTrace) {
237252
process.env.NEXT_TURBOPACK_TRACING =
238253
options.internalTrace === 'all'
239254
? 'turbo-tasks'
240255
: String(options.internalTrace)
241256
}
257+
setupProfilesDir(directory || process.cwd())
242258

243259
// ensure process exits after build completes so open handles/connections
244260
// don't cause process to hang
@@ -380,18 +396,14 @@ program
380396
if (options.experimentalCpuProf) {
381397
process.env.NEXT_CPU_PROF = '1'
382398
process.env.__NEXT_PRIVATE_CPU_PROFILE = 'dev-main'
383-
const { join } = require('path') as typeof import('path')
384-
const dir = directory || process.cwd()
385-
const cpuProfileDir = join(dir, '.next-profiles')
386-
mkdirSync(cpuProfileDir, { recursive: true })
387-
process.env.NEXT_CPU_PROF_DIR = cpuProfileDir
388399
}
389400
if (options.internalTrace) {
390401
process.env.NEXT_TURBOPACK_TRACING =
391402
options.internalTrace === 'all'
392403
? 'turbo-tasks'
393404
: String(options.internalTrace)
394405
}
406+
setupProfilesDir(directory || process.cwd())
395407
const portSource = _optionValueSources.port
396408
import('../cli/next-dev.js').then((mod) =>
397409
mod.nextDev(options, portSource, directory)
@@ -470,12 +482,8 @@ program
470482
if (options.experimentalCpuProf) {
471483
process.env.NEXT_CPU_PROF = '1'
472484
process.env.__NEXT_PRIVATE_CPU_PROFILE = 'start-main'
473-
const { join } = require('path') as typeof import('path')
474-
const dir = directory || process.cwd()
475-
const cpuProfileDir = join(dir, '.next-profiles')
476-
mkdirSync(cpuProfileDir, { recursive: true })
477-
process.env.NEXT_CPU_PROF_DIR = cpuProfileDir
478485
}
486+
setupProfilesDir(directory || process.cwd())
479487
return import('../cli/next-start.js').then((mod) =>
480488
mod.nextStart(options, directory)
481489
)

‎packages/next/src/cli/next-dev.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ import {
1616
} from '../server/lib/utils'
1717
import * as Log from '../build/output/log'
1818
import { getProjectDir } from '../lib/get-project-dir'
19+
import { ensureProfilesDir } from '../lib/profiles-dir'
1920
import path from 'path'
2021
import { traceGlobals } from '../trace/shared'
2122
import { Telemetry } from '../telemetry/storage'
@@ -416,7 +417,7 @@ const nextDev = async (
416417
...(options.experimentalCpuProf
417418
? {
418419
NEXT_CPU_PROF: '1',
419-
NEXT_CPU_PROF_DIR: path.join(dir, '.next-profiles'),
420+
NEXT_CPU_PROF_DIR: ensureProfilesDir(dir),
420421
__NEXT_PRIVATE_CPU_PROFILE: 'dev-server',
421422
}
422423
: undefined),
Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
import { existsSync, mkdirSync, writeFileSync } from 'fs'
2+
import { join } from 'path'
3+
4+
/**
5+
* Name of the directory at the project root where profiling output (CPU
6+
* profiles and Turbopack traces) is written when profiling is enabled (see the
7+
* `--experimental-cpu-prof` and `--internal-trace` CLI flags). It is a
8+
* fixed-name sibling of `distDir`, not configurable.
9+
*
10+
* Keep this in sync with `DIST_PROFILES_DIR_NAME` in
11+
* `crates/next-core/src/next_config.rs`.
12+
*/
13+
export const PROFILES_DIR_NAME = '.next-profiles'
14+
15+
const GITIGNORE_CONTENTS = `# Created automatically by Next.js. Profiling output should not be committed.
16+
*
17+
`
18+
19+
/**
20+
* Create the `.next-profiles` directory under `dir` and return its absolute
21+
* path. This is the single place that creates the directory — the Rust trace
22+
* writer relies on it already existing.
23+
*
24+
* Also writes a `.gitignore` containing `*` (if one isn't already there) so the
25+
* potentially large profiling output is excluded from git and gitignore-aware
26+
* tools (Tailwind, Turborepo, ...) skip the subtree instead of reading it and
27+
* hanging/OOMing.
28+
*/
29+
export function ensureProfilesDir(dir: string): string {
30+
const profilesDir = join(dir, PROFILES_DIR_NAME)
31+
mkdirSync(profilesDir, { recursive: true })
32+
const gitignorePath = join(profilesDir, '.gitignore')
33+
if (!existsSync(gitignorePath)) {
34+
try {
35+
writeFileSync(gitignorePath, GITIGNORE_CONTENTS)
36+
} catch {
37+
// A missing .gitignore must not abort a profiling run.
38+
}
39+
}
40+
return profilesDir
41+
}

‎packages/next/src/server/lib/cpu-profile.ts‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,9 +50,8 @@ export function saveCpuProfile(): void {
5050

5151
let outputPath: string
5252
if (cpuProfileDir) {
53-
if (!fs.existsSync(cpuProfileDir)) {
54-
fs.mkdirSync(cpuProfileDir, { recursive: true })
55-
}
53+
// The CLI created `cpuProfileDir` (with its `.gitignore`) before setting
54+
// NEXT_CPU_PROF_DIR, so it already exists in these build workers.
5655
outputPath = path.join(cpuProfileDir, filename)
5756
} else {
5857
outputPath = `./${filename}`

‎test/e2e/cpu-profiling/cpu-profiling-build.test.ts‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { nextTestSetup, isNextDeploy } from 'e2e-utils'
2-
import { pathExists, readdir } from 'fs-extra'
2+
import { pathExists, readdir, readFile } from 'fs-extra'
33
import { join } from 'path'
44

55
describe('CPU Profiling - next build', () => {
@@ -23,6 +23,14 @@ describe('CPU Profiling - next build', () => {
2323
await next.build()
2424
})
2525

26+
it('should write a .gitignore into .next-profiles', async () => {
27+
const gitignore = join(next.testDir, '.next-profiles', '.gitignore')
28+
expect(await pathExists(gitignore)).toBe(true)
29+
// `*` keeps the (potentially large) profiling output out of git and away
30+
// from gitignore-respecting tools that would otherwise scan it.
31+
expect(await readFile(gitignore, 'utf8')).toContain('*')
32+
})
33+
2634
it('should create CPU profile files after build', async () => {
2735
const profileDir = join(next.testDir, '.next-profiles')
2836

0 commit comments

Comments
 (0)