Skip to content

installation.mdx

Latest commit

 

History

History
183 lines (135 loc) · 4.99 KB

installation.mdx

File metadata and controls

183 lines (135 loc) · 4.99 KB
Raw
title Installation
description ReScript installation and setup instructions
canonical /docs/manual/installation
section Overview
order 2

Installation

Prerequisites

- [Node.js](https://nodejs.org/) version >= 22 - One of the following package managers: - [npm](https://docs.npmjs.com/cli/) (comes with Node.js) - [yarn](https://yarnpkg.com/) - yarn versions >1 need to set `nodeLinker: node-modules` in `.yarnrc.yml` - [pnpm](https://pnpm.io/) - [bun](https://bun.sh/) - [deno](http://deno.com/) - Configure `"nodeModulesDir": "auto"` in `deno.json`

New Project

The fastest and easiest way to spin up a new ReScript project is with the create-rescript-app project generator. This will get you started with a fresh Next.js or Vite app with React and Tailwind CSS.

You can start it with any of the aforementioned package managers or npx.

<CodeTab labels={["npm", "npx", "yarn", "pnpm", "bun"]}>

npm create rescript-app@latest
npx create-rescript-app
yarn create rescript-app
pnpm create rescript-app
bun create rescript-app

  • Follow the steps of the setup.

  • Trigger a ReScript build:

    npm run res:build

  • If you selected the "basic" template, simply run it with:

    node src/Demo.res.mjs

That compiles your ReScript into JavaScript, then uses Node.js to run said JavaScript.

When taking your first steps with ReScript, we recommend you use our unique workflow of keeping a tab open for the generated JS file (.res.js/.res.mjs), so that you can learn how ReScript transforms into JavaScript. Not many languages output clean JavaScript code you can inspect and learn from! With our VS Code extension, use the command "ReScript: Open the compiled JS file for this implementation file" to open the generated JS file for the currently active ReScript source file. For developers using agents, that same workflow keeps both the source and generated JS easy to inspect.

During development, instead of running npm run res:build each time to compile, use npm run res:dev to start a watcher that recompiles automatically after file changes.

Integrate Into an Existing JS Project

If you already have a JavaScript project into which you'd like to add ReScript you can do that in the following ways:

Quick Setup

In the root directory of your project, execute:

<CodeTab labels={["npm", "npx", "yarn", "pnpm", "bun"]}>

npm create rescript-app@latest
npx create-rescript-app
yarn create rescript-app
pnpm create rescript-app
bun create rescript-app

create-rescript-app will tell you that a package.json file has been detected and ask you if it should install ReScript into your project. Just follow the steps accordingly.

Manual Setup

  • Install ReScript locally:

    <CodeTab labels={["npm", "yarn", "pnpm", "bun", "deno"]}>

    npm install rescript
    yarn add rescript
    pnpm install rescript
    bun install rescript
    // you will need deno configured to have a node_modules folder
deno install npm:rescript --allow-scripts
    **pnpm users:** ReScript-compiled JS imports from `@rescript/runtime` directly, but pnpm's strict isolation does not expose transitive dependencies at the app root. Either install the runtime as a direct dependency (`pnpm add @rescript/runtime`), or hoist it by adding the following to `pnpm-workspace.yaml`: 
    publicHoistPattern:
  - "*@rescript/runtime*"

  • Create a ReScript build configuration file (called rescript.json) at the root:

    {
  "name": "your-project-name",
  "sources": [
    {
      "dir": "src", // update this to wherever you're putting ReScript files
      "subdirs": true
    }
  ],
  "package-specs": [
    {
      "module": "esmodule",
      "in-source": true
    }
  ],
  "suffix": ".res.js"
}

    See Build Configuration for more details on rescript.json.

  • Add convenience npm scripts to package.json:

    "scripts": {
  "build:res": "rescript",
  "dev:res": "rescript watch"
}

Since ReScript compiles to clean readable JS files, the rest of your existing toolchain (e.g. Vite, Rspack, Rollup) should just work, which keeps setup overhead low for fast-moving teams using AI or coding agents.

Helpful guides:

Integrate with a ReactJS Project

To start a rescript-react app, or to integrate ReScript into an existing ReactJS app, follow the instructions here.