If you would like to learn OCaml and Melange from scratch, we recommend you to read "Melange for React Devs". This book will give you an overview of the OCaml language, as well as showcase some of the mechanisms that Melange offers to interact with JavaScript code. You’ll build a few projects along the way, and by the end, you’ll have a solid grasp of the language.
Alternatively, if you want to start your project, below you will find the two main ways to get started with Melange:
- Automated, using create-melange-app
- Manually, using melange-opam-template
If you prefer an automated way to install the Melange toolchain, you can use create-melange-app to start a new project. To do so, run these commands:
npm create melange-app@latest
npm run dev
If you prefer manually installing the toolchain, follow the instructions below.
To work with Melange, you need to install a package manager compatible with OCaml. If you are not sure which one to use, we recommend opam, a source-based package manager for OCaml, but there are other alternatives available.
Instructions for installing opam on different operating systems can be found at the opam install page, and you can find a whole section about it on this website.
You can clone melange-opam-template
from this
link, and follow
the instructions in the readme
file
to configure the local opam
switch and download the
necessary dependencies to build the project.
One of the goals of Melange is to remain compatible with OCaml. One of the major benefits of this compatibility is that developers working on Melange projects can use the same editor tooling as they would for OCaml.
OCaml developer tooling has been built, tested, and refined over the years, with plugins available for many editors. The most actively maintained plugins are for Visual Studio Code, Emacs, and Vim.
For Visual Studio Code, install the OCaml Platform Visual Studio Code extension from the Visual Studio Marketplace. When you load an OCaml source file for the first time, you may be prompted to select the toolchain to use. Select the version of OCaml you are using from the list, such as 5.1.1. Further instructions for configuration can be found in the extension repository.
For Emacs and Vim, the configuration may vary depending on the case, and there are several options available. You can read about them in the editor setup page of the OCamlverse documentation site.
Melange can also be used with other package managers. The following instructions apply to Nix and esy.
Melange provides an overlay that can be:
- referenced from a Nix flake
- overlayed onto a
nixpkgs
package set
Make sure Nix is installed. The following
flake.nix
illustrates how to set up a Melange development environment.
{
description = "Melange starter";
inputs = {
flake-utils.url = "github:numtide/flake-utils";
nixpkgs.url = "github:nixos/nixpkgs";
# Depend on the Melange flake, which provides the overlay
melange.url = "github:melange-re/melange";
};
outputs = { self, nixpkgs, flake-utils, melange }:
flake-utils.lib.eachDefaultSystem (system:
let
pkgs = nixpkgs.legacyPackages.${system}.appendOverlays [
# Set the OCaml set of packages to the 5.1 release line
(self: super: { ocamlPackages = super.ocaml-ng.ocamlPackages_5_1; })
# Apply the Melange overlay
melange.overlays.default
];
inherit (pkgs) ocamlPackages;
in
{
devShells.default = pkgs.mkShell {
nativeBuildInputs = with ocamlPackages; [
ocaml
dune_3
findlib
ocaml-lsp
ocamlPackages.melange
];
buildInputs = [ ocamlPackages.melange ];
};
});
}
To enter a Melange development shell, run nix develop -c $SHELL
.
First, make sure esy
is
installed. npm i -g esy
does the trick in most setups.
The following is an example esy.json
that can help start a Melange project. A
project template for esy
is also available if you prefer to start from a
template.
{
"name": "melange-project",
"dependencies": {
"ocaml": "5.1.x",
"@opam/dune": ">= 3.8.0",
"@opam/melange": "*"
},
"devDependencies": {
"@opam/ocaml-lsp-server": "*"
},
"esy": {
"build": [
"dune build @melange"
]
}
}
Run:
esy install
to build and make all dependencies availableesy shell
to enter a Melange development environment