Debug ReScript

Native

Goal

Debug ReScript code by setting breakpoints in the compiled JavaScript output and stepping through execution.

Prerequisites

  • JavaScript Debugger plugin — Bundled with WebStorm; available as a separate install for IntelliJ IDEA Ultimate. Not available in Community Edition.

  • Node.js — Required for running the compiled JavaScript

Steps

1. Ensure the build is running

Start a ReScript build in watch mode so that compiled JS files stay up to date:

  • Use the Run Configuration for ReScript Build, or

  • Run rescript build -w from the terminal

The status bar widget at the bottom shows the current build status (success/error/warning).

2. Open the compiled JavaScript

With a .res file open, press Alt+Shift+J (or use Tools > ReScript > Open Compiled JS) to open the corresponding compiled JavaScript file in a split editor.

This lets you see exactly what code will execute at runtime.

3. Create a JavaScript Debug configuration

  1. Go to Run > Edit Configurations

  2. Click + and select JavaScript Debug (for browser apps) or Node.js (for server apps)

  3. Configure the entry point:

    • For Node.js: Set the JavaScript file path (e.g., src/Main.res.js)

    • For browser: Set the URL of your dev server (e.g., http://localhost:5173)

4. Set breakpoints in the compiled JS

Open the compiled .res.js file and click in the gutter to set breakpoints. The compiled JS closely mirrors the ReScript source structure, making it straightforward to find the corresponding code.

// src/App.res.js
function make(props) {
  var count = React.useState(function () {  // <-- set breakpoint here
    return 0;
  });
  // ...
}

5. Run the debug configuration

Press Shift+F9 (or click the Debug button) to start debugging. The debugger will pause at your breakpoints, and you can:

  • Step Over (F8) — Execute the current line

  • Step Into (F7) — Enter a function call

  • Evaluate Expression (Alt+F8) — Inspect values at runtime

  • View Variables — See local and closure variables in the Debug panel

Expected Result

You can pause execution at breakpoints in the compiled JavaScript, inspect variable values, and step through the code to diagnose issues.

Tips

  • The compiled JS preserves ReScript function and variable names, so the mapping is intuitive

  • Use the JS Preview tool window (View > Tool Windows > ReScript JS Preview) for a live side-by-side view without opening a separate file

  • Source maps are not currently generated by the ReScript compiler, so breakpoints must be set in the compiled JS rather than the .res source