@rescript/vite-plugin

The official ReScript plugin for Vite

The plugin passes source maps generated by the ReScript compiler into Vite, so development tools and production bundles can map generated JavaScript back to the original .res and .resi source files.

Installation

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

Usage

[!NOTE] Source-map support will be released in ReScript 13 but is not published yet. The runnable example uses a compiler preview in the meantime.

Enable source maps in rescript.json:

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

Then add the plugin to vite.config.ts:

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

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

The plugin supports ReScript's linked, inline, and hidden source-map modes. It only applies a source map when at least one mapped source is a .res or .resi file.

Production builds

Use "enabled": "always" when source maps should also be generated by rescript build. Vite must be configured to emit its final bundle source maps separately:

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

Set Vite's build.sourcemap to "hidden" when the maps should be emitted without adding a sourceMappingURL comment to the production bundle.

[!CAUTION] Source maps with sourcesContent enabled contain the original ReScript source. Choose the ReScript and Vite source-map settings appropriate for how the production artifacts will be distributed.

Options

The plugin inspects .js, .mjs, and .cjs modules and skips node_modules by default. Use include and exclude to customize that behavior:

export default defineConfig({
  plugins: [
    sourceMap({
      include: ["src/**/*.res.mjs", "generated/**/*.res.js"],
      exclude: "vendor/**",
    }),
  ],
});

Pass exclude: null to inspect dependencies in node_modules as well.

Example

examples/basic is a minimal ReScript and Vite application that uses this package through its public package exports. From the repository root, run:

yarn example:dev

This compiles ReScript once and starts Vite. For live .res recompilation, run the compiler watcher in a second terminal:

yarn workspace rescript-vite-plugin-example rescript:watch

Use yarn example:build to compile ReScript and create a production bundle. The example is also exercised by yarn test as an end-to-end source-map smoke test. It temporarily uses a ReScript 13 compiler preview and requires Node.js 22.12 or newer.

Development

This repository uses Yarn 4.12.0 through Corepack:

corepack enable
yarn install
yarn check
yarn test
yarn build

Changesets

Changes that affect the published package should include a changeset. Run:

yarn changeset

Commit the generated .changeset/*.md file with the change. Documentation and other changes that do not affect the published package do not need a changeset.

To apply pending changesets and publish a release, maintainers can run:

yarn changeset version
yarn changeset publish

License

MIT