Source Maps

Since 13.0

Source maps connect locations in generated JavaScript back to the original .res source files. They make browser breakpoints and stack traces more useful when debugging ReScript code.

ReScript emits Source Map v3 mappings for each generated JavaScript file. The compiler preserves mappings through function bodies, call and pipe expressions, pattern-matching branches, and debugger statements.

Configure Source Maps

Add a sourceMap object to your rescript.json:

JSON
{
  "sourceMap": {
    "enabled": "dev",
    "mode": "linked",
    "sourcesContent": true
  }
}

Both enabled and mode are required.

The shorthand "sourceMap": true is not supported because the generation timing and output mode must be explicit.

Choose When to Generate Source Maps

Use "enabled": "dev" to generate source maps only while running rescript watch (or rescript -w). A one-off rescript build does not generate maps in this mode.

JSON
{
  "sourceMap": {
    "enabled": "dev",
    "mode": "linked"
  }
}

Use "enabled": "always" to generate source maps during both rescript build and rescript watch. This is useful when a production build or error-monitoring upload step needs the map files.

Choose an Output Mode

Linked

"mode": "linked" writes a separate map next to each generated JavaScript file and adds a sourceMappingURL comment to the JavaScript output.

For example, Demo.res.mjs produces:

Demo.res.mjs
Demo.res.mjs.map

The end of Demo.res.mjs references the sibling map:

JS
//# sourceMappingURL=Demo.res.mjs.map

Linked maps are a good default for local browser or Node.js debugging because developer tools can discover them automatically.

Inline

"mode": "inline" embeds the source map as a base64-encoded data URI in the generated JavaScript:

JS
//# sourceMappingURL=data:application/json;base64,...

No sibling .map file is generated. Inline maps keep the JavaScript and its map together, but increase the size of every generated file.

Hidden

"mode": "hidden" writes a separate .map file without adding a sourceMappingURL comment to the generated JavaScript.

This mode is useful for production error-monitoring services: upload the map files to the service without publishing a reference to them in the JavaScript output.

Include Original Source

Set sourcesContent to true to include the original .res text in the map:

JSON
{
  "sourceMap": {
    "enabled": "always",
    "mode": "hidden",
    "sourcesContent": true
  }
}

Embedding source content lets debuggers show the original ReScript file without retrieving it separately. When mode is inline, the original source is embedded directly in the generated JavaScript data URI.

Warning: Source maps can expose your original source code. If maps or generated JavaScript are publicly served, use sourcesContent: true only when that is acceptable for your project.

Set a Source Root

Most projects do not need sourceRoot. Set it when the tool consuming your maps expects source paths under a specific root:

JSON
{
  "sourceMap": {
    "enabled": "always",
    "mode": "hidden",
    "sourceRoot": "webpack://my-app/"
  }
}

ReScript writes a non-empty value unchanged to the sourceRoot field of each generated map. The field is omitted when sourceRoot is absent or empty.

Use Source Maps

Browsers can discover linked and inline maps when they load the generated JavaScript directly. If another build tool transforms or bundles that JavaScript, configure it to consume ReScript's input maps and emit source maps for its final output.

Vite

Vite transforms ReScript's generated JavaScript before serving or bundling it. Install the ReScript Vite plugin so Vite can consume the source maps emitted by the ReScript compiler:

SH
npm install --save-dev @rescript/vite-plugin

Add the plugin to vite.config.js:

JS
import { sourceMap } from "@rescript/vite-plugin";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [sourceMap()],
  build: {
    sourcemap: true,
  },
});

The plugin reads linked, inline, or hidden source maps generated by ReScript and passes them to Vite as input source maps. It does not enable source map generation in the ReScript compiler, so you still need the sourceMap setting in rescript.json.

The build.sourcemap option tells Vite to emit source maps for the final production output. It is not required for Vite's development server.

Node.js

Node.js can use linked or inline maps to report .res locations in stack traces:

SH
node --enable-source-maps ./src/Main.res.mjs

Hidden maps are not discovered automatically because the generated JavaScript does not reference them. Pass them directly to the error-monitoring or deployment tool that consumes them.

Disable Source Maps

Source maps are disabled when the sourceMap field is omitted. You can also disable them explicitly:

JSON
{
  "sourceMap": false
}

This produces the same JavaScript as a configuration without sourceMap and removes stale sibling map files on the next build.