Add source maps documentation

apps/docs/markdown-pages/docs/manual/source-maps.mdx

@@ -0,0 +1,179 @@
+---
+title: "Source Maps"
+metaTitle: "ReScript Source Maps"
+description: "Configure source maps for JavaScript generated by ReScript"
+canonical: "/docs/manual/source-maps"
+section: "Build System"
+order: 4
+---
+
+# 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.
+
+| Field            | Values                             | Description                                                               |
+| ---------------- | ---------------------------------- | ------------------------------------------------------------------------- |
+| `enabled`        | `"dev"`, `"always"`                | Controls whether source maps are generated for watch mode only or always. |
+| `mode`           | `"linked"`, `"inline"`, `"hidden"` | Controls how the source map is emitted and referenced.                    |
+| `sourcesContent` | `true`, `false`                    | Embeds the original `.res` source in the map. Defaults to `false`.        |
+| `sourceRoot`     | A string                           | Sets the optional `sourceRoot` field in the generated source map.         |
+
+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:
+
+```text
+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.