Production Source Maps

Context

1. Node.js does not consume sourcemaps by default and should be enabled:

   • CLI: node --enable-source-maps (Node.js >= v12.12)
   • Environment variable: NODE_OPTIONS="--enable-source-maps" (Node.js >=v12.12)
   • Runtime: module.setSourceMapsSupport(Node.js >= 22.14) or require("sourcem-map-support").install (Node.js < 22.14) (catch: should be as early as possible before loading any other modules)

2. Nitro (v2) uses rollup and esbuild to generate production sourcemaps, which are:

• External by default (// # sourceMappingURL=[mod].mjs.map),
• Could be inlined using sourcemap: "inline" nitro config (or completely disabled using false)
• Do not bundle sources (regardless of inline or external), but reference to ../src, which means src needs to be deployed for them to work.

What can we do?

1. While ideally, runtimes and providers should consume source maps by default, they don't.

   • We could follow up with runtimes and deployment providers to enable sourcemap support.
   • We could enable a default polyfill for modern Node.js to consume maps (>= 22.14) (https://github.com/unjs/unenv/pull/511).

2. (not necessary) The fact that source maps point to ../src makes them harder for production consumption, as .output is supposed to be the only deployed directory. However, at the cost of bundling sourcemap contents into the output bundle, consumption would be much easier without needing to bundle the whole project (however, it is only necessary to log the contents of source normal tracing works, regardless)

POC

Before moving forward to enable support by default or with a flag, the effect of this idea can be replicated via Nitro config and unenv polyfill.

export default defineNitroConfig({
  // Enable source map consumption by default in Node.js >= 22.14
  unenv: {
    // Note: currently requires unenv-nightly
    polyfill: ["unenv/polyfill/source-maps"], 
  },
  // Enable full source bundling (not required)
  esbuild: {
    options: {
      sourcesContent: true,
    },
  },
  rollupConfig: {
    output: {
      sourcemapExcludeSources: false,
    },
  },
});

Results

POC available on nitro-deploys

✅ Works out of the box

• Node.js
• Firebase App hosting (deploy)
• Koyeb (deploy)
• Netlify functions (deploy)
• Vercel (deploy)
  • Improvement: we can enable shouldAddSourcemapSupport for Node.js 20 support.

❌ Not passing

• Bun
• Deno / Deno deploy (deploy)
• Netlify edge (deploy)
• Zero ops (deploy)
• Cloudflare (pages and workers)
  • Trying with upload_source_maps: true seems not effective

Start with the POC in nitro-deploys and the Nitro configuration shown in the issue, then inspect unenv/polyfill/source-maps and the runtime/provider results. Define whether the project should enable support by default, add a flag, or change source bundling; done means a chosen scope is implemented and the listed passing and failing deployments are rechecked.