Guide on how to create a ReScript lib for JS usage

[ryyppy]

It would be great if we'd document how to set up a ReScript project, so that it is publishable on npm without any dependency to the ReScript compiler toolchain.

I know that some workflows are blocked by the fact that ReScript doesn't ship an independent precompiled stdlib / belt package, but others have reported that a rollup based workflow is also viable as well.

Would be interesting to create a dedicated page for a rollup based setup, just to bridge the gap until we see how ppl are getting along with shipping ReScript based JS libs.

[johnridesabike]

I was recently updating a ReScript package to use export maps and encountered an issue.

Here’s what part of my package.json looked like at first:

{
  "exports": {
    ".": {
      "import": "./dist/main.mjs",
      "require": "./dist/main.js"
    },
    "./package.json": "./package.json"
  }
}

(The contents of /dist/ are generated with Rollup, but that’s not directly relevant here.)

This works great for JS users, but I realized that ReScript users can’t import any of the code generated from ReScript source. I updated the export map to look like this instead:

{
  "exports": {
    ".": {
      "import": "./dist/main.mjs",
      "require": "./dist/main.js"
    },
    "./lib/*": "./lib/*",
    "./src/*": "./src/*",
    "./package.json": "./package.json"
  }
}

I assume that adding ./lib/* and ./src/* should be considered “best practice?” (Assuming that you keep your .res files in /src/.) If so, it’s probably worth including in the docs.

[jthegedus]

I would suggest a tool like microbundle, a Rollup-powered zero/low config bundler.

For a simple tool used in just the JS world I use these npm scripts:

# esm
microbundle -i src/<entrypoint>.bs.js -o dist/bundle.js --no-pkg-main -f es
# cjs
microbundle -i src/<entrypoint>.bs.js -o dist/bundle.js --no-pkg-main -f cjs

independent precompiled stdlib / belt package

is still preferred though. Or even having Rescript inline these packages itself.

[ryyppy]

this is not needed anymore with ReScript v9. We introduced a flag for consuming an external stdlib package which is just another plain JS dependency with precompiled JS lib files.

[jthegedus]

Is that

#4920 #4925 support external-stdlib config

"external-stdlib" : "@rescript/std"

from this release https://github.com/rescript-lang/rescript-compiler/blob/HEAD/Changes.md#90 ?

[ryyppy]

Yes. More context can be found in our v9 blog post: https://rescript-lang.org/blog/release-9-0

[jthegedus]

Ah okay, I didn't know this was out since the docs site just shows docs for v8.2.0 and < v8.2.0. Thanks for the link!