Getting started

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 from scratch, the easiest way to get started with Melange is by using the melange-opam-template.

Keep reading to get up and running with Melange in no time!

Install a package manager

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.

Get the template

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.

Editor integration

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.2.0. Refer to Supported Syntaxes to learn how to set up format-on-save. 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.

Alternative package managers (experimental)

Melange can also be used with other package managers. The following instructions apply to Nix and esy.

Nix

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.

esy

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:

1. esy install to build and make all dependencies available
2. esy shell to enter a Melange development environment