feat: add source map support for production error stack traces

[lazarv]

Summary

Adds source map support for production error stack traces, enabling developers to see original source file locations in server-side errors instead of bundled code references.

Closes #284

Features

Source map modes

All Vite sourcemap modes are supported via --sourcemap:

Mode	Server	Client	Description
true	.map files	.map files	Full source maps for both bundles
inline	Inline	Inline	Embedded in output files
hidden	.map files (no URL comment)	.map files (no URL comment)	Maps without sourceMappingURL
server	.map files	None	Server-only, keeps client source private
server-inline	Inline	None	Server-only inline, ideal for edge deployments

Runtime stack trace rewriting

• Uses source-map-support package to automatically rewrite production error stack traces
• Skips installation on edge runtimes (Vercel Edge, Cloudflare Workers, Netlify Edge) where the platform handles source maps natively
• Skips installation when NODE_OPTIONS='--enable-source-maps' is already set to avoid conflicts
• Mode-specific configuration: hookRequire for inline, custom retrieveSourceMap for hidden

Configuration

Via CLI:

pnpm react-server build --sourcemap         # true (file-based)
pnpm react-server build --sourcemap=server  # server bundles only
pnpm react-server build --sourcemap=server-inline  # server inline only

Via config file (react-server.config.mjs):

export default {
  sourcemap: true, // or "inline", "hidden", "server", "server-inline"
};

Adapter support

• Vercel — Adds NODE_OPTIONS: "--enable-source-maps" to .vc-config.json environment
• Cloudflare — Enables upload_source_maps: true in generated wrangler.toml
• Netlify — Copies .map files alongside edge/serverless functions
• Core adapter — Conditionally includes server/**/*.map in server file globs

Implementation details

Build-time

• Emits build-manifest.mjs as an ES module (export default { sourcemap: ... }) for edge compatibility
• Registers virtual module .react-server/server/build-manifest in all 3 resolution paths (RSC loader, SSR loader, edge bundler)
• Server-only modes normalize the value for server/edge builds while passing false to client builds

Runtime

• manifest.mjs loads the build manifest and sets the SOURCEMAP_SUPPORT runtime symbol
• ssr-handler.mjs reads the symbol and installs source-map-support with appropriate options
• RSC onError handlers log errors with logger?.error(e) in production for visibility

Files changed

Core

• packages/react-server/server/symbols.mjs — New SOURCEMAP_SUPPORT symbol
• packages/react-server/lib/build/action.mjs — Build manifest emission, config file support
• packages/react-server/lib/build/server.mjs — Server sourcemap normalization
• packages/react-server/lib/build/client.mjs — Client sourcemap suppression for server-only modes
• packages/react-server/lib/build/edge.mjs — Edge sourcemap normalization
• packages/react-server/lib/start/manifest.mjs — Build manifest loading
• packages/react-server/lib/start/ssr-handler.mjs — Source map support installation
• packages/react-server/lib/loader/node-loader.mjs — Virtual module resolution
• packages/react-server/lib/loader/node-loader.react-server.mjs — Virtual module resolution
• packages/react-server/server/render-rsc.jsx — Production error logging
• packages/react-server/bin/commands/build.mjs — CLI help text
• packages/react-server/package.json — source-map-support dependency

Adapters

• packages/react-server/adapters/core.mjs — Conditional .map file inclusion
• packages/react-server/adapters/vercel/index.mjs — NODE_OPTIONS in .vc-config.json
• packages/react-server/adapters/cloudflare/index.mjs — upload_source_maps in wrangler config
• packages/react-server/adapters/netlify/index.mjs — Edge function .map file copy

Docs

• docs/src/pages/en/(pages)/framework/cli.mdx — Restructured with per-option headings + sourcemap docs
• docs/src/pages/ja/(pages)/framework/cli.mdx — Same restructuring in Japanese

Tests

• test/__test__/sourcemap.spec.mjs — Build output tests (manifest content, .map file presence, server-inline mode)
• test/fixtures/sourcemap.jsx — Test fixture component

VS Code

• .vscode/launch.json — Debug configuration for production + sourcemap
• .vscode/tasks.json — Build task with --sourcemap

[github-actions]

✅ Documentation preview deployed to: https://react-server-docs-ixpovnu4a-lazarv-team.vercel.app