.. _melange_main: *********************************** JavaScript Compilation With Melange *********************************** Introduction ============ `Melange `_ compiles OCaml to JavaScript. It produces one JavaScript file per OCaml module. Melange can be installed with opam: .. code:: console $ opam install melange Dune can build projects using Melange, and it allows the user to produce JavaScript files by defining a :ref:`melange-emit` stanza. Dune libraries can be used with Melange by adding ``melange`` to ``(modes ...)`` in the :doc:`/reference/dune/library` stanza. Melange support is still experimental in Dune and needs to be enabled in the :doc:`/reference/dune-project/index` file: .. code:: dune (using melange 0.1) Once that's in place, you can use the Melange mode in :doc:`/reference/dune/library` stanzas ``melange.emit`` stanzas. Simple Project ============== Let's start by looking at a simple project with Melange and Dune. Subsequent sections explain the different concepts used here in further detail. First, make sure that the :doc:`/reference/dune-project/index` file specifies at least version 3.8 of the Dune language, and the Melange extension is enabled: .. code:: dune (lang dune 3.20) (using melange 0.1) Next, write a :doc:`/reference/dune/index` file with a :ref:`melange-emit` stanza: .. code:: dune (melange.emit (target output)) Finally, add a source file to build: .. code:: console $ echo 'Js.log "hello from melange"' > hello.ml After running ``dune build @melange`` or just ``dune build``, Dune produces the following file structure: .. code:: . ├── _build │ └── default │ └── output │ └── hello.js ├── dune ├── dune-project └── hello.ml The resulting JavaScript can now be run: .. code:: console $ node _build/default/output/hello.js hello from melange Libraries ========= Adding Melange support to Dune libraries is done as follows: - ``(modes melange)``: adding ``melange`` to ``modes`` is required. This field also supports the :doc:`reference/ordered-set-language`. - ``(melange.runtime_deps )``: optionally, define any runtime dependencies using ``melange.runtime_deps``. This field is analog to the ``runtime_deps`` field used in ``melange.emit`` stanzas. .. _melange-emit: melange.emit ============ .. versionadded:: 3.8 The ``melange.emit`` stanza allows the user to produce JavaScript files from Melange libraries and entry-point modules. It's similar to the OCaml :doc:`/reference/dune/executable` stanza, with the exception that there is no linking step. .. code:: dune (melange.emit (target ) ) ```` is the name of the folder where resulting JavaScript artifacts will be placed. In particular, the folder will be placed under ``_build/default/$path-to-directory-of-melange-emit-stanza``. The result of building a ``melange.emit`` stanza will match the file structure of the source tree. For example, given the following source tree: .. code:: ├── dune # (melange.emit (target output) (libraries lib)) ├── app.ml └── lib ├── dune # (library (name lib) (modes melange)) └── helper.ml The resulting layout in ``_build/default/output`` will be as follows: .. code:: output ├── app.js └── lib ├── lib.js └── helper.js ```` are: - ``(alias )`` specifies an alias to which to attach the targets of the ``melange.emit`` stanza. - These targets include the ``.js`` files generated by the stanza modules, the targets for the ``.js`` files of any library that the stanza depends on, and any copy rules for runtime dependencies (see ``runtime_deps`` field below). - By default, all stanzas will have their targets attached to an alias ``melange``. The behavior of this default alias is exclusive: if an alias is explicitly defined in the stanza, the targets from this stanza will be excluded from the ``melange`` alias. - The targets of ``melange.emit`` are also attached to the Dune default alias (:doc:`/reference/aliases/all`), regardless of whether the ``(alias ...)`` field is present. - ``(module_systems )`` specifies the JavaScript import and export format used. The values allowed for ```` are ``es6`` and ``commonjs``. - ``es6`` will follow `JavaScript modules `_, and will produce ``import`` and ``export`` statements. - ``commonjs`` will follow `CommonJS modules `_, and will produce `require` calls and export values with ``module.exports``. - If no extension is specified, the resulting JavaScript files will use ``.js``. You can specify a different extension with a pair ``( )``, e.g. ``(module_systems (es6 mjs))``. - Multiple module systems can be used in the same field as long as their extensions are different. For example, ``(module_systems commonjs (es6 mjs))`` will produce one set of JavaScript files using CommonJS and the ``.js`` extension, and another using ES6 and the ``.mjs`` extension. - ``(modules )`` specifies what modules will be built with Melange. By default, if this field is not defined, Dune will use all the ``.ml/.re`` files in the same directory as the ``dune`` file. This includes module sources present in the file system as well as modules generated by user rules. You can restrict this list by using an explicit ``(modules )`` field. ```` uses the :doc:`reference/ordered-set-language`, where elements are module names and don't need to start with an uppercase letter. For instance, to exclude module ``Foo``, use ``(modules :standard \ foo)``. - ``(libraries )`` specifies Melange library dependencies. Melange libraries can only use the simple form, like ``(libraries foo pkg.bar)``. Keep in mind the following limitations: - The ``re_export`` form is not supported. - All the libraries included in ```` have to support the ``melange`` mode (see the section about libraries below). - ``(package )`` allows the user to define the JavaScript package to which the artifacts produced by the ``melange.emit`` stanza will belong. - ``(runtime_deps )`` specifies dependencies that should be copied to the build folder together with the ``.js`` files generated from the sources. These runtime dependencies can include assets like CSS files, images, fonts, external JavaScript files, etc. ``runtime_deps`` adhere to the formats in :doc:`concepts/dependency-spec`. For example ``(runtime_deps ./path/to/file.css (glob_files_rec ./fonts/*))``. - ``(emit_stdlib )`` allows the user to specify whether the Melange standard library should be included as a dependency of the stanza or not. The default is ``true``. If this option is ``false``, the Melange standard library and runtime JavaScript files won't be produced in the target directory. - ``(promote )`` promotes the generated ``.js`` files to the source tree. The options are the same as for the :ref:`rule promote mode `. Adding ``(promote (until-clean))`` to a ``melange.emit`` stanza will cause Dune to copy the ``.js`` files to the source tree and ``dune clean`` to delete them. - ``(preprocess )`` specifies how to preprocess files when needed. The default is ``no_preprocessing``. Additional options are described in the :doc:`reference/preprocessing-spec` section. - ``(preprocessor_deps ())`` specifies extra preprocessor dependencies, e.g., if the preprocessor reads a generated file. The dependency specification is described in the :doc:`concepts/dependency-spec` section. - ``(compile_flags )`` specifies compilation flags specific to ``melc``, the main Melange executable. ```` is described in detail in the :doc:`reference/ordered-set-language` section. It also supports ``(:include ...)`` forms. The value for this field can also be taken from ``env`` stanzas. It's therefore recommended to add flags with e.g. ``(compile_flags :standard )`` rather than replace them. - ``(root_module )`` specifies a ``root_module`` that collects all listed dependencies in ``libraries``. See the documentation for ``root_module`` in the :doc:`/reference/dune/library` stanza. - ``(allow_overlapping_dependencies)`` is the same as the corresponding field of :doc:`/reference/dune/library`. - ``(enabled_if )`` conditionally disables a melange emit stanza. The JavaScript files associated with the stanza won't be built. The condition is specified using the :doc:`reference/boolean-language`. Recommended Practices ===================== Keep Bundles Small by Reducing the Number of ``melange.emit`` Stanzas --------------------------------------------------------------------- It is recommended to minimize the number of ``melange.emit`` stanzas that a project defines: using multiple ``melange.emit`` stanzas will cause multiple copies of the JavaScript files to be generated if the same libraries are used across them. As an example: .. code:: dune (melange.emit (target app1) (libraries foo)) (melange.emit (target app2) (libraries foo)) The JavaScript artifacts for library ``foo`` will be emitted twice in the ``_build`` folder. They will be present under ``_build/default/app1`` and ``_build/default/app2``. This can have unexpected impact on bundle size when using tools like Webpack or Esbuild, as these tools will not be able to see shared library code as such, as it would be replicated across the paths of the different stanzas ``target`` folders. Faster Builds With ``subdir`` and ``dirs`` Stanzas -------------------------------------------------- Melange libraries might be installed from the ``npm`` package repository, together with other JavaScript packages. To avoid having Dune inspect unnecessary folders in ``node_modules``, it is recommended to explicitly include only the folders that are relevant for Melange builds. This can be accomplished by combining :doc:`/reference/dune/subdir` and :doc:`/reference/dune/subdir` stanzas in a ``dune`` file next to the ``node_modules`` folder. The :doc:`/reference/dune/vendored_dirs` stanza can be used to avoid warnings in Melange libraries during the application build. The :doc:`/reference/dune/data_only_dirs` stanza can be useful as well if you need to override the build rules in one of the packages. .. code:: dune (subdir node_modules (vendored_dirs reason-react) (dirs reason-react)) Design choices ===================== Melange support in Dune follows the following design choices: - :ref:`melange-emit` produces a "total" directory: the artifacts in the ``target`` dir contain all the JavaScript and ``runtime_deps`` assets necessary to run the application either through a JS framework, a bundler, or otherwise a deployment (excluding external dependencies installed via a JS package manager). The structure is designed such that relative paths and dependencies work out of the box relative to their paths in the source tree, before compilation. - public libraries are compiled to ``%{target}/node_modules/%{lib_name}`` such that the `resolution algorithm `_ works to resolve Melange libraries from compiled JS code.