Turbopack: add on-demand memory reporting for dev server by lukesandberg · Pull Request #90271 · vercel/next.js

lukesandberg · 2026-02-20T23:16:58Z

Summary

Adds an on-demand memory reporting system for Turbopack dev servers, enabling developers to inspect memory usage without restarting or attaching external profilers. This implements the design described in PACK-6917.

Layers

Rust core (turbo-tasks-backend): collect_memory_report() iterates all in-memory tasks and cells, grouping by function name and value type. Size estimation uses bincode encode-and-discard with a reusable scratch buffer. Allocator stats come from TurboMalloc::memory_usage().
NAPI binding: Project.getMemoryReport(topN?) exposes the Rust report as a JSON string to Node.js.
HTTP endpoint: GET /__nextjs_turbopack-memory on the dev server. Supports format=json|markdown and top_n query parameters. The Node.js layer augments the report with process-level stats (RSS, heap, PID, Node version).
CLI command: next internal turbopack-memory [dir] [--format json|markdown] [--server host:por] discovers the running dev server via the .next/dev/lock file and fetches the report.
Documentation: Added a "Turbopack memory reporting" section to the local development guide.

Output formats

JSON (default): Machine-readable, includes version, timestamps, task/cell/allocator stats
Markdown: Human-readable tables

Key design decisions

We estimate memory size via encoding, which is trivial to do but horrifically inaccurate. This means we both overcount and undercount memory (because persistent formats are sometimes often compact than memory, think slack space in hash tables) and overcount because we don't respect reference counted datastructures like RcStr/Rope. A 'correct' approach would be very complex.

Test plan

Integration tests for fetch API (JSON schema, markdown, top_n)
Integration tests for CLI (next internal turbopack-memory with JSON, markdown, top_n)
Manual testing with a real app to verify report accuracy

Fixes PACK-6917

lukesandberg · 2026-02-20T23:17:14Z

Turbopack: add on-demand memory reporting for dev server #90271 👈 (View in Graphite)
canary

This stack of pull requests is managed by Graphite. Learn more about stacking.

codspeed-hq · 2026-02-20T23:27:51Z

Merging this PR will not alter performance

✅ 17 untouched benchmarks
⏩ 3 skipped benchmarks¹

_{Comparing claude/keen-bassi (e077061) with canary (22e46a4)}

3 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

nextjs-bot · 2026-02-20T23:28:27Z

Failing test suites

Commit: 7f47044 | About building and testing Next.js

pnpm test-dev test/development/app-dir/turbopack-memory-report/turbopack-memory-report.test.ts (job)

turbopack-memory-report > CLI > should return valid JSON via next internal turbopack-memory (DD)
turbopack-memory-report > CLI > should return markdown via CLI (DD)
turbopack-memory-report > fetch API > should return valid JSON from /__nextjs_turbopack-memory (DD)
turbopack-memory-report > fetch API > should return markdown format when requested (DD)

Expand output

● turbopack-memory-report › fetch API › should return valid JSON from /__nextjs_turbopack-memory

expect(received).toBe(expected) // Object.is equality

Expected: 200
Received: 404

  13 |
  14 |       const res = await next.fetch('/__nextjs_turbopack-memory')
> 15 |       expect(res.status).toBe(200)
     |                          ^
  16 |       expect(res.headers.get('content-type')).toBe(
  17 |         'application/json; charset=utf-8'
  18 |       )

  at Object.toBe (development/app-dir/turbopack-memory-report/turbopack-memory-report.test.ts:15:26)

● turbopack-memory-report › fetch API › should return markdown format when requested

expect(received).toBe(expected) // Object.is equality

Expected: 200
Received: 404

  68 |
  69 |       const res = await next.fetch('/__nextjs_turbopack-memory?format=markdown')
> 70 |       expect(res.status).toBe(200)
     |                          ^
  71 |       expect(res.headers.get('content-type')).toBe(
  72 |         'text/markdown; charset=utf-8'
  73 |       )

  at Object.toBe (development/app-dir/turbopack-memory-report/turbopack-memory-report.test.ts:70:26)

● turbopack-memory-report › CLI › should return valid JSON via next internal turbopack-memory

expect(received).toBe(expected) // Object.is equality

Expected: 0
Received: 1

  90 |         { stdout: true }
  91 |       )
> 92 |       expect(result.code).toBe(0)
     |                           ^
  93 |
  94 |       const report = JSON.parse(result.stdout)
  95 |       expect(report.version).toBe(1)

  at Object.toBe (development/app-dir/turbopack-memory-report/turbopack-memory-report.test.ts:92:27)

● turbopack-memory-report › CLI › should return markdown via CLI

expect(received).toBe(expected) // Object.is equality

Expected: 0
Received: 1

  109 |         { stdout: true }
  110 |       )
> 111 |       expect(result.code).toBe(0)
      |                           ^
  112 |       expect(result.stdout).toContain('# Turbopack Memory Report')
  113 |       expect(result.stdout).toContain('## Tasks')
  114 |     })

  at Object.toBe (development/app-dir/turbopack-memory-report/turbopack-memory-report.test.ts:111:27)

packages/next/src/bin/next.ts

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

turbopack/crates/turbo-tasks-backend/src/backend/memory_report.rs

test/development/app-dir/turbopack-memory-report/turbopack-memory-report.test.ts

turbopack/crates/turbo-tasks-backend/src/backend/memory_report.rs

turbopack/crates/turbo-tasks-backend/src/backend/mod.rs

turbopack/crates/turbo-tasks-backend/src/backend/storage_schema.rs

nextjs-bot · 2026-02-21T01:09:09Z

Stats from current PR

🔴 1 regression

Metric	Canary	PR	Change	Trend
node_modules Size	474 MB	474 MB	🔴 +74.1 kB (+0%)	▁▁▁▁▁

📊 All Metrics

📖 Metrics Glossary

Dev Server Metrics:

Listen = TCP port starts accepting connections
First Request = HTTP server returns successful response
Cold = Fresh build (no cache)
Warm = With cached build artifacts

Build Metrics:

Fresh = Clean build (no .next directory)
Cached = With existing .next directory

Change Thresholds:

Time: Changes < 50ms AND < 10%, OR < 2% are insignificant
Size: Changes < 1KB AND < 1% are insignificant
All other changes are flagged to catch regressions

⚡ Dev Server

Metric	Canary	PR	Change	Trend
Cold (Listen)	455ms	455ms	✓	█▁▁▁▅
Cold (Ready in log)	438ms	438ms	✓	█▆▁▅▅
Cold (First Request)	1.260s	1.282s	✓	▅▇▁▇▄
Warm (Listen)	457ms	456ms	✓	█▁▁▁█
Warm (Ready in log)	442ms	443ms	✓	█▁▁▁▆
Warm (First Request)	345ms	346ms	✓	█▂▄▃▇

📦 Dev Server (Webpack) (Legacy)

📦 Dev Server (Webpack)

Metric	Canary	PR	Change	Trend
Cold (Listen)	456ms	455ms	✓	▁▃▃▁▁
Cold (Ready in log)	437ms	436ms	✓	▃▄▃▁▂
Cold (First Request)	1.830s	1.838s	✓	▂▄▂▁▁
Warm (Listen)	456ms	456ms	✓	▁▃▁▁▁
Warm (Ready in log)	435ms	436ms	✓	▂▄▃▂▂
Warm (First Request)	1.862s	1.865s	✓	▁▄▂▁▁

⚡ Production Builds

Metric	Canary	PR	Change	Trend
Fresh Build	4.008s	3.977s	✓	█▁▂▁▇
Cached Build	3.962s	3.999s	✓	█▁▂▁▇

📦 Production Builds (Webpack) (Legacy)

📦 Production Builds (Webpack)

Metric	Canary	PR	Change	Trend
Fresh Build	13.831s	13.955s	✓	▁▄▁▁▁
Cached Build	14.115s	14.057s	✓	▁▄▁▁▁
node_modules Size	474 MB	474 MB	🔴 +74.1 kB (+0%)	▁▁▁▁▁

📦 Bundle Sizes

Bundle Sizes

⚡ Turbopack

Client

Main Bundles: **399 kB** → **399 kB** ✅ -5 B

80 files with content-based hashes (individual files not comparable between builds)

Server

Middleware

	Canary	PR	Change
middleware-b..fest.js gzip	767 B	765 B	✓
Total	767 B	765 B	✅ -2 B

Build Details

Build Manifests

	Canary	PR	Change
_buildManifest.js gzip	451 B	451 B	✓
Total	451 B	451 B	✓

📦 Webpack

Client

Main Bundles

	Canary	PR	Change
5528-HASH.js gzip	5.48 kB	N/A	-
6280-HASH.js gzip	57.5 kB	N/A	-
6335.HASH.js gzip	169 B	N/A	-
912-HASH.js gzip	4.53 kB	N/A	-
e8aec2e4-HASH.js gzip	62.6 kB	N/A	-
framework-HASH.js gzip	59.7 kB	59.7 kB	✓
main-app-HASH.js gzip	256 B	254 B	✓
main-HASH.js gzip	39.1 kB	39.1 kB	✓
webpack-HASH.js gzip	1.68 kB	1.68 kB	✓
262-HASH.js gzip	N/A	4.53 kB	-
2889.HASH.js gzip	N/A	169 B	-
5602-HASH.js gzip	N/A	5.49 kB	-
6948ada0-HASH.js gzip	N/A	62.6 kB	-
9544-HASH.js gzip	N/A	58.3 kB	-
Total	231 kB	232 kB	⚠️ +742 B

Polyfills

	Canary	PR	Change
polyfills-HASH.js gzip	39.4 kB	39.4 kB	✓
Total	39.4 kB	39.4 kB	✓

Pages

	Canary	PR	Change
_app-HASH.js gzip	194 B	194 B	✓
_error-HASH.js gzip	183 B	180 B	🟢 3 B (-2%)
css-HASH.js gzip	331 B	330 B	✓
dynamic-HASH.js gzip	1.81 kB	1.81 kB	✓
edge-ssr-HASH.js gzip	256 B	256 B	✓
head-HASH.js gzip	351 B	352 B	✓
hooks-HASH.js gzip	384 B	383 B	✓
image-HASH.js gzip	580 B	581 B	✓
index-HASH.js gzip	260 B	260 B	✓
link-HASH.js gzip	2.5 kB	2.5 kB	✓
routerDirect..HASH.js gzip	320 B	319 B	✓
script-HASH.js gzip	386 B	386 B	✓
withRouter-HASH.js gzip	315 B	315 B	✓
1afbb74e6ecf..834.css gzip	106 B	106 B	✓
Total	7.97 kB	7.97 kB	✅ -2 B

Server

Edge SSR

	Canary	PR	Change
edge-ssr.js gzip	125 kB	125 kB	✓
page.js gzip	253 kB	253 kB	✓
Total	377 kB	377 kB	⚠️ +268 B

Middleware

	Canary	PR	Change
middleware-b..fest.js gzip	615 B	612 B	✓
middleware-r..fest.js gzip	156 B	155 B	✓
middleware.js gzip	43.8 kB	43.9 kB	✓
edge-runtime..pack.js gzip	842 B	842 B	✓
Total	45.4 kB	45.5 kB	⚠️ +77 B

Build Details

Build Manifests

	Canary	PR	Change
_buildManifest.js gzip	715 B	718 B	✓
Total	715 B	718 B	⚠️ +3 B

Build Cache

	Canary	PR	Change
0.pack gzip	3.95 MB	3.96 MB	🔴 +10.8 kB (+0%)
index.pack gzip	103 kB	103 kB	✓
index.pack.old gzip	102 kB	101 kB	✓
Total	4.15 MB	4.16 MB	⚠️ +9.66 kB

🔄 Shared (bundler-independent)

Runtimes

	Canary	PR	Change
app-page-exp...dev.js gzip	318 kB	318 kB	✓
app-page-exp..prod.js gzip	168 kB	168 kB	✓
app-page-tur...dev.js gzip	317 kB	317 kB	✓
app-page-tur..prod.js gzip	168 kB	168 kB	✓
app-page-tur...dev.js gzip	314 kB	314 kB	✓
app-page-tur..prod.js gzip	166 kB	166 kB	✓
app-page.run...dev.js gzip	314 kB	314 kB	✓
app-page.run..prod.js gzip	166 kB	166 kB	✓
app-route-ex...dev.js gzip	70.7 kB	70.7 kB	✓
app-route-ex..prod.js gzip	49.1 kB	49.1 kB	✓
app-route-tu...dev.js gzip	70.7 kB	70.7 kB	✓
app-route-tu..prod.js gzip	49.2 kB	49.2 kB	✓
app-route-tu...dev.js gzip	70.3 kB	70.3 kB	✓
app-route-tu..prod.js gzip	48.9 kB	48.9 kB	✓
app-route.ru...dev.js gzip	70.2 kB	70.2 kB	✓
app-route.ru..prod.js gzip	48.9 kB	48.9 kB	✓
dist_client_...dev.js gzip	324 B	324 B	✓
dist_client_...dev.js gzip	326 B	326 B	✓
dist_client_...dev.js gzip	318 B	318 B	✓
dist_client_...dev.js gzip	317 B	317 B	✓
pages-api-tu...dev.js gzip	43.2 kB	43.2 kB	✓
pages-api-tu..prod.js gzip	32.9 kB	32.9 kB	✓
pages-api.ru...dev.js gzip	43.2 kB	43.2 kB	✓
pages-api.ru..prod.js gzip	32.8 kB	32.8 kB	✓
pages-turbo....dev.js gzip	52.5 kB	52.5 kB	✓
pages-turbo...prod.js gzip	38.5 kB	38.5 kB	✓
pages.runtim...dev.js gzip	52.5 kB	52.5 kB	✓
pages.runtim..prod.js gzip	38.4 kB	38.4 kB	✓
server.runti..prod.js gzip	62 kB	62 kB	✓
Total	2.81 MB	2.81 MB	✅ -1 B

bgw

Thanks for doing this!

bgw · 2026-03-05T22:37:31Z

packages/next/src/server/dev/middleware-turbopack.ts

+      return next()
+    }
+
+    const format = searchParams.get('format') ?? 'json'


Alternative options:

This could be done with an Accept header. It doesn't really matter because we're not asking the agent to call this endpoint directly, but agents usually have a WebFetch tool that uses the Accept header to request markdown.

We could have a .json path and a .md path

nextjs-bot added created-by: Turbopack team PRs by the Turbopack team. Documentation Related to Next.js' official documentation. tests Turbopack Related to Turbopack with Next.js. type: next labels Feb 20, 2026

implement some basic memory reporting

f0f0230

lukesandberg force-pushed the claude/keen-bassi branch from c488246 to f0f0230 Compare February 20, 2026 23:21

lukesandberg changed the title ~~bump the webpack version bundled in next~~ Turbopack: add on-demand memory reporting for dev server Feb 20, 2026