feat: add source map support for production stack trace rewriting by aheissenberger · Pull Request #284 · lazarv/react-server

aheissenberger · 2025-11-14T09:18:13Z

Source Map Support for Production Error Stack Traces

Overview

This implementation adds support for converting production error stack traces back to their original source locations using source maps. When you build with the --sourcemap flag, error messages in production will show the original file locations and line numbers instead of the compiled/bundled locations.

How It Works

1. Source Map Detection

When the server starts in production mode, it checks if source map files (.map) exist alongside the built files in the output directory (default: .react-server/server/). If found, the SOURCEMAP_ENABLED flag is set in the runtime context.

File: lib/start/ssr-handler.mjs

Checks for .map files during initialization
Sets the SOURCEMAP_ENABLED runtime flag

2. Stack Trace Conversion

The source-map-support package is dynamically imported and installed at server startup when source maps are detected. It automatically hooks into Node.js's Error.prepareStackTrace to convert stack traces:

Package: source-map-support (dynamically loaded)

Only imported when .map files are detected
Automatically loads .map files from the file system
Caches parsed source maps for performance
Hooks into Node.js error handling
Transparently converts all stack traces system-wide

3. Error Logging Integration

Once source-map-support is installed, all errors throughout the application automatically have their stack traces converted. No manual conversion is needed at individual error points.

Files Modified:

lib/start/ssr-handler.mjs - Installs source-map-support at startup

Usage

Building with Source Maps

# Build with separate source map files
npx react-server build --sourcemap

# Build with inline source maps
npx react-server build --sourcemap inline

# Build with hidden source maps (not referenced in code)
npx react-server build --sourcemap hidden

Starting the Production Server

npx react-server start

The server will automatically detect if source maps are available and use them for error reporting.

Example

Without Source Maps

Error: Something went wrong
    at /app/.react-server/server/index.mjs:1234:56
    at /app/.react-server/server/render.mjs:789:12

With Source Maps

Error: Something went wrong
    at /app/src/components/MyComponent.jsx:45:23
    at /app/src/pages/index.jsx:12:8

Implementation Details

Modified Files

server/symbols.mjs
- Added SOURCEMAP_ENABLED symbol for runtime flag
lib/start/ssr-handler.mjs
- Detects source map availability on startup (checks for .map files)
- Dynamically imports source-map-support only when source maps are detected
- Sets SOURCEMAP_ENABLED runtime flag
- Installs source-map-support when source maps are available

Dependencies Added

source-map-support - Automatically converts stack traces using source maps (dynamically loaded only when needed)

Performance Considerations

Dynamic Loading: source-map-support is only imported when source maps are detected, reducing memory footprint in development and when source maps aren't available
One-time Check: Source map detection happens once at server startup, not on every request
Efficient Caching: source-map-support caches parsed source maps in memory after first load
Minimal Overhead: Hooks are installed once at startup with negligible performance impact
Graceful Fallback: Falls back to original stack trace if source map lookup fails

Conditional Execution

The source map conversion only happens when:

The build was created with --sourcemap flag
The .map files exist in the output directory
Running in production mode (not dev mode)
An error occurs

Notes

Dev mode already has source map support through Vite's module graph
This implementation is specifically for production builds
Source maps should be kept secure and not deployed to public-facing servers if they contain sensitive information
The --sourcemap hidden option generates source maps but doesn't reference them in the code (useful for error tracking without exposing sources)

Copilot

Pull Request Overview

This pull request adds source map support for production error stack traces by dynamically loading and installing the source-map-support package when .map files are detected at server startup. This allows production errors to display original source locations instead of compiled bundle locations.

Key Changes

Added SOURCEMAP_ENABLED runtime flag to track source map availability
Implemented source map detection by checking for .map files in the build output directory
Dynamically imports and installs source-map-support only when source maps are present

Reviewed Changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
pnpm-lock.yaml	Added `source-map-support@0.5.21` dependency and updated peer dependency resolution for various packages
packages/react-server/server/symbols.mjs	Added new `SOURCEMAP_ENABLED` symbol for runtime flag tracking
packages/react-server/package.json	Added `source-map-support` dependency specification
packages/react-server/lib/start/ssr-handler.mjs	Implemented source map detection logic and dynamic loading of source-map-support at server startup
packages/react-server/lib/start/action.mjs	Added default initialization of `SOURCEMAP_ENABLED` flag in worker function

Files not reviewed (1)

pnpm-lock.yaml: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

packages/react-server/lib/start/ssr-handler.mjs

packages/react-server/lib/start/action.mjs

lazarv · 2025-11-15T21:17:46Z

Hi @aheissenberger!

This is so nice to have finally, and sourcemap handling has been a missing feature for more than 2 years now! I totally forgot to add this to the production server.

I made some suggested changes in review/sourcemap-error.

The most prominent change I would suggest is to use the entry module code and check for the sourceMappingURL line to support inline sourcemaps, and not load the source-map-support module for hidden sourcemaps.

Also, I would rename SOURCEMAP_ENABLED to SOURCEMAP_SUPPORT as this is the name of the feature, and enabled/disabled is its value.

aheissenberger · 2025-11-17T17:41:40Z

When switching to source map detection by checking for the url, the hidden source maps will break.

Have a look at my latest changes which require less code changes and no runtime detection:

create a build meta file which allows to access build settings like source map options at runtime
packages/react-server/server/render-rsc.jsx - fix missing stack trace in server log from react server components in production. Without this fix the server log logs the same anonymous message as shown on the client An error occurred in the Server Components render. The specific message is omitted in production ...

I tested the rsc component by adding a throw error to function allTodos(), it worked very well in production including mapping to the right source position. But the already existing stack trace in dev mode does not provide the correct line number - see #285

aheissenberger · 2025-11-17T19:22:14Z

maybe using the cli option --enable-source-maps and adding some infos to the docs is the best way to go since this option exists since node 12.12.0

NODE_OPTIONS='--enable-source-maps' react-server start

lazarv · 2025-11-19T07:23:19Z

packages/react-server/server/render-rsc.jsx

 import { ServerFunctionNotFoundError } from "./action-state.mjs";
 import { cwd } from "../lib/sys.mjs";

+/**


This wrapper could be moved to https://github.com/lazarv/react-server/blob/main/packages/react-server/lib/start/create-logger.mjs, so that the logger would use this everywhere by default. Also, the wrapper should only be enabled when using source maps.

lazarv · 2025-11-19T07:28:30Z

packages/react-server/lib/build/server.mjs

+
+  // Write build metadata with sourcemap option
+  await writeFile(
+    join(cwd, options.outDir, "server/build-meta.json"),


As all other manifests have the server/<type>-manifest.json name, I would suggest to have this also named server/build-manifest.json.

lazarv · 2025-11-19T07:29:57Z

packages/react-server/lib/start/ssr-handler.mjs

  const moduleCacheStorage = new ContextManager();
  await module_loader_init$(moduleLoader, moduleCacheStorage);

+  if (buildMetadata.sourcemap && buildMetadata.sourcemap !== false) {


As this is now related to manifests, I would move this into https://github.com/lazarv/react-server/blob/main/packages/react-server/lib/start/manifest.mjs#L52-L56 and also store it in the context.

…v#306) ## 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 lazarv#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: ```sh 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`): ```js 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`

feat: add source map support for production stack trace rewriting

71e5d9f

Copilot AI review requested due to automatic review settings November 14, 2025 09:18

aheissenberger requested a review from lazarv as a code owner November 14, 2025 09:18

Copilot started reviewing on behalf of aheissenberger November 14, 2025 09:18 View session

Copilot finished reviewing on behalf of aheissenberger November 14, 2025 09:22

Copilot AI reviewed Nov 14, 2025

View reviewed changes

packages/react-server/lib/start/ssr-handler.mjs Outdated Show resolved Hide resolved

packages/react-server/lib/start/action.mjs Outdated Show resolved Hide resolved

aheissenberger added 2 commits November 14, 2025 10:33

fix: improve source map logging in SSR handler

6a944a6

fix: use info logger and fix text

8bacc49

aheissenberger added 4 commits November 17, 2025 12:21

feat: switch flag to SOURCEMAP_SUPPORT

bbb4b62

fix: replace runtime sourcemap detection with build meta data

275a497

feat: stack trace for react server components in production

45b9569

fix: remove not required file

0de6b4a

lazarv reviewed Nov 19, 2025

View reviewed changes

lazarv mentioned this pull request Feb 15, 2026

feat: add source map support for production error stack traces #306

Merged

lazarv closed this in #306 Feb 15, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add source map support for production stack trace rewriting#284

feat: add source map support for production stack trace rewriting#284
aheissenberger wants to merge 7 commits intolazarv:mainfrom
aheissenberger:sourcemap-error

aheissenberger commented Nov 14, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

lazarv commented Nov 15, 2025

Uh oh!

aheissenberger commented Nov 17, 2025

Uh oh!

aheissenberger commented Nov 17, 2025 •

edited

Loading

Uh oh!

lazarv Nov 19, 2025

Uh oh!

lazarv Nov 19, 2025

Uh oh!

lazarv Nov 19, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

aheissenberger commented Nov 14, 2025

Source Map Support for Production Error Stack Traces

Overview

How It Works

1. Source Map Detection

2. Stack Trace Conversion

3. Error Logging Integration

Usage

Building with Source Maps

Starting the Production Server

Example

Without Source Maps

With Source Maps

Implementation Details

Modified Files

Dependencies Added

Performance Considerations

Conditional Execution

Notes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Key Changes

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

lazarv commented Nov 15, 2025

Uh oh!

aheissenberger commented Nov 17, 2025

Uh oh!

aheissenberger commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lazarv Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

lazarv Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

lazarv Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

aheissenberger commented Nov 17, 2025 •

edited

Loading