How-to guides

Migrate a ReScript library to Melange

既存の ReScript (opens in a new tab)（旧 BuckleScript）のコードはほぼそのまま Melange で使用できます。ただし、両プロジェクトは異なる方向に進化しているため、ReScript の最新機能の一部は Melange で動作させるために直接変換することができないかもしれません。

このため、ライブラリの移行は、ReScript の過去のバージョンと互換性のある時期、たとえば v9（または v10 まで）に行うことをお勧めします。

以下はその手順です：

• opamファイルの追加
• dune-project ファイルの追加
• bsconfig.jsonファイルを 1 つまたは複数の dune ファイルに置き換える
• (オプション) ReScript 構文から Reason または OCaml 構文への移行
• 全て動作するかを確認：dune buile
• 最終ステップ: bsconfig.jsonを削除し、package.json にする

詳しく見ていきましょう：

opam-version: "2.0"
synopsis: "My Melange library"
description: "A library for Melange"
maintainer: ["<your_name>"]
authors: ["<your_name>"]
license: "XXX"
homepage: "https://github.com/your/project"
bug-reports: "https://github.com/your/project/issues"
depends: [
  "ocaml"
  "dune"
  "melange"
]
dev-repo: "git+https://github.com/your/project.git"

opam switch create . 5.1.1 -y --deps-only

(lang dune 3.8)

(using melange 0.1)

(library
 (name things)
 (modes melange)
 (preprocess (pps melange.ppx)))

{
  "namespace": "foo-bar"
}

(library
 (name fooBar) # or (name foo_bar)
 (modes melange)
 (preprocess (pps melange.ppx)))

{
  "sources": ["src", "helper"]
}

(include_subdirs unqualified)
(dirs src helper)
(library
 (name things)
 (modes melange)
 (preprocess (pps melange.ppx)))

"bs-dependencies": [
  "reason-react"
]

(library
 (name things)
 (libraries reason-react)
 (modes melange)
 (preprocess (pps melange.ppx)))

depends: [
  "melange-jest" {with-test}
]

{
  "js-post-build": {
    "cmd": "node ../../postProcessTheFile.js"
  }
}

(rule
  (deps (alias melange))
  (action (run node ../../postProcessTheFile.js))
)

{
  "warnings": {
    "number": "-44-102",
    "error": "+5"
  }
}

(library
 (name things)
 (modes melange)
 (preprocess (pps melange.ppx))
 (melange.compile_flags :standard -w +5-44-102))

opam install rescript-syntax

rescript_syntax myFile.res -print ml > myFile.ml

find src1 src2 -type f -name "*.res" -exec echo "rescript_syntax {} -print ml" \;

rescript_syntax ./myFile.res -print ml | refmt --parse=ml --print re > myFile.re

dune build

Throughout the process, you might run into some errors, these are the most common ones:

Warning 16 [unerasable-opt-argument] is triggered more often than before

Melange triggers Warning 16: this optional argument cannot be erased more often than before, as the type system in OCaml 4.12 was improved. You can read more about this in this OCaml PR (opens in a new tab).

Fix: either add () as final param of the function, or replace one labelled arg with a positional one.

Warning 69 [unused-field] triggered from bindings types

Sometimes, types for bindings will trigger Warning 69 [unused-field]: record field foo is never read. errors.

Fix: silence the warning in the type definition, e.g.

type renderOptions = {
  foo : string
} [@@warning "-69"]

Destructuring order is changed

Destructuring in let patterns in Melange is done on the left side first, while on ReScript is done on the right side first. You can read more in the Melange PR (opens in a new tab) with the explanation.

Fix: move module namespacing to the left side of the let expressions.

Pervasives is deprecated

This is also another change due to OCaml compiler moving forward.

Fix: Use Stdlib instead.

Runtime assets are missing

In ReScript, building in source is very common. In Melange and Dune, the most common setup is having all artifacts inside the _build folder. If your library is using some asset such as:

external myImage : string = "default" [@@bs.module "./icons/overview.svg"]

Fix: You can include it by using the melange.runtime_deps field of the library:

(library
 (name things)
 (modes melange)
 (preprocess (pps melange.ppx))
 (melange.runtime_deps icons/overview.svg))

You can read more about this in the Handling assets section.

Final step: remove bsconfig.json and adapt package.json

If everything went well, you can remove the bsconfig.json file, and remove any dependencies needed by Melange from the package.json, as they will be appearing in the opam file instead, as it was mentioned in the bs-dependencies section.

Migrate

This section contains information about migrating from older versions of Melange to newer ones.

To v2 from v1

Melange v2 is only compatible with OCaml 5.1. In order to upgrade, let's update the local opam switch first, to make sure the local repository gets the versions v2 of Melange and 5.1 of OCaml:

opam update

Now, update the version of the OCaml compiler in the local switch to 5.1:

opam install --update-invariant ocaml-base-compiler.5.1.1

Finally, we can upgrade all packages to get Melange v2 and the latest version of all libraries:

opam upgrade

To make sure you have the latest version of Melange, you can use the opam list subcommand:

opam list --installed melange
# Packages matching: name-match(melange) & installed
# Name  # Installed    # Synopsis
melange 2.2.0          Toolchain to produce JS from Reason/OCaml

Before building, we have to update some parts of the configuration to make it work with v2.

melange.ppx now includes most syntax transformations

Most of the attributes used to write bindings are now handled by melange.ppx. If you get errors of the kind Unused attribute, or type errors in externals that don't make much sense, then you probably need to add melange.ppx to your library or melange.emit stanzas.

(library
 ...
 (preprocess
  (pps melange.ppx)))

Warnings have been turned into alerts

Some warnings were turned into alerts, so they might be visible even if using vendored_dirs. To silence these alerts, either fix the root cause or silence them using (preprocess (pps melange.ppx -alert -deprecated)).

Wrapped libraries

Melange libraries like Belt and Js are now wrapped, so the access to modules inside them need to be adapted. Some examples:

• Js_string needs to be replaced with Js.String
• Belt_MapInt is now Belt.Map.Int

Changes in deriving

The bs.deriving attribute is replaced with deriving. Also, the payload taken by this attribute has been adapted to conform to ppxlib requirements. Note that mel.deriving is not accepted.

Let's see how the payload has changed in both OCaml and Reason syntaxes.

In Ocaml syntax:

In Reason syntax:

bs.* attributes and extensions become mel.*

All attributes or extension nodes prefixed with bs are now prefixed with mel instead.

For example @bs.as becomes @mel.as, and %bs.raw becomes %mel.raw.

Note that attributes in the deprecated form (@bs.*) are still accepted until v3, but node extensions (%bs.*) are not.

@bs attribute becomes @u

The @bs attribute, used for uncurried application (see the "Binding to callbacks" section), becomes @u.

@bs.val is gone

The @bs.val attribute is no longer necessary, and can be removed from external definitions. See more information in the "Using global functions or values" section.

Dom and Node are in their own libraries

The namespaces Dom and Node are now in the libraries melange.dom and melange.node respectively. These libraries are not included by default by Melange, and will need to be added to the libraries field explicitly.

Effect handlers

Although Melange v2 requires OCaml 5.1, it doesn't yet provide a good solution for compiling effect handlers to JavaScript. Until it does, they are disabled at the compiler level, and their APIs are not accessible.