package melange

  1. Overview
  2. Docs
package melange
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Melange

Toolchain to produce JS from Reason/OCaml.

Melange is a compiler for producing performant JavaScript from Reason and OCaml. Powered by a strong static type system with best-in-class type inference based on the OCaml compiler, Melange facilitates producing robust JavaScript code.

Positioning in the broader OCaml ecosystem

This project is forked from the ReScript compiler shifting focus to integrating with the OCaml ecosystem. This enables code sharing between backend and frontend using Dune's virtual libraries.

Melange also introduces a ReScript compatibility layer to maintain compatibility with ReScript's Syntax - preserving access to ReScripts ecosystem of packages.

Write in Reason/OCaml, use OCaml libraries or ReScript packages to kickstart your project!

A small write-up with more details on the motivation behind this project can be found in this blog post.

Installation

This project is currently unreleased. There are, however, a few ways to try it out.

Esy

The easiest way to get started is to clone the basic template and run esy in the project root. To install Esy, npm install -g esy should cover most workflows. If you have NodeJS / npm available, npx esy is even shorter.

OPAM

You can also install melange with opam:

Pin melange to the version on GitHub:

opam pin melange https://github.com/melange-re/melange.git

You should now be able to run melange from your switch:

opam exec -- mel --help

Melange also has some runtime dependencies that need to be symlinked into node_modules to be discoverable by bundlers like webpack:

    rm -rf node_modules/melange
mkdir -p node_modules/melange
ln -sfn $(opam var prefix)/lib/melange node_modules/melange/lib

(adapted from the equivalent step in the esy build for melange-basic-template: https://github.com/melange-re/melange-basic-template/blob/3605fb491d45e74472be58f653482e15e21c9159/esy.json#L15).

Nix

Melange has good support for Nix:

  • nix run github:melange-re/melange -- build runs melange.
  • nix shell github:melange-re/melange -c $SHELL enters a shell with mel and melc in $PATH. Try out mel --help, for example. for available options.
  • Adding github:melange-re/melange as a flake input exports melange as the default package

Please reach out on the ReasonML Discord if you can't figure it out!

Editor support

Until Melange has first-class support in Dune, ocaml-lsp support relies on having Melange generate a .merlin file to provide the language server with information about your project.

To enable editor support via ocaml-lsp, add the following to your esy.json:

// esy.json
{
  "devDependencies": {
    "@opam/ocaml-lsp-server": ">= 1.12.0",
    "@opam/dot-merlin-reader": "*"
  }
}

Then use the --fallback-read-dot-merlin flag when running ocaml-lsp.

VSCode

If using the VSCode OCaml Platform extension, use the Custom sandbox option and provide the flag to ocaml-lsp via the command template:

// .vscode/settings.json
{
  "ocaml.sandbox": {
    "kind": "custom",
    "template": "esy $prog $args --fallback-read-dot-merlin"
  }
}

A note on OCaml versions

The current Melange distribution works on OCaml 4.14 and OCaml 5.00+trunk. If you need to use Melange with OCaml 4.12 (the only formerly supported version), you can consume the 0.1.0 tag for this repo (make sure to similarly use the 4.12.0+mel tag for melange-compiler-libs).

FAQ

How does this project relate to other tools?

Name

Purpose

Dependencies

Notes

Esy

Package manager

Installed with NPM

Obtaining dependencies (e.g. dune or reason)

OPAM

Package manager

None

Obtaining dependencies (e.g. dune or reason)

Dune

Build tool

Installed with esy or opam

Well-known OCaml build tool; supports custom rules that can be composed to build anything

Reason

Syntax

Installed with esy or opam

a library that implements an alternative syntax to OCaml

Melange

Compiler that emits Script

Esy (to install), Dune (to build), Reason (used as a library)

Supports OCaml, Reason and ReScript syntaxes; derived from ReScript, focused on compatibility with the wider OCaml ecosystem

ReScript

The brand around a syntax and a compiler that emits JavaScript

None

Distributed via NPM as prebuilt binaries; previously called BuckleScript

Can I use ReScript syntax?

Yes! ReScript syntax is supported, but ReScript won't have as many features as the OCaml or Reason syntaxes due to ReScript being built on top of an old OCaml version (4.06 - Released 2018). (e.g. letop binding operators, generalized module open expressions, or local substitutions in signatures).

Where has the refmt flag gone?

Upstream removed the refmt flag, which used to allow configuring the path to a custom Reason binary. This was a welcome change for this repo too, so we cherry-picked it. The rationale: this project uses Reason as a library, so you can simply depend on the Reason version that you'd like in the usual way, via your preferred package manager.

Contributing

See CONTRIBUTING.md.

Acknowledgments

  • Thanks to the ReScript project, its author and maintainer @bobzhang, and its many contributors. Melange is a fork of ReScript, and continues to incorporate patches to ReScript on a regular basis.
  • Thanks to the OCaml team, obviously, without such a beautiful yet practical language, this project would not exist.
  • Thanks to Bloomberg and Facebook. The ReScript project began at Bloomberg and was published in 2016; without the support of Bloomberg, it would not have happened. ReScript was funded by Facebook since July 2017.

See also Credits.md concerning some individual components of Melange.

Licensing

See COPYING and COPYING.LESSER

See Credits for more details.