Swiftpack.co - Package -


package.json workflow for native development with Reason/OCaml.

AppVeyor Travis npm npm (tag)

This README serves as a development documentation for esy. For user documentation refer to esy.sh documentation site.

Repository structure

The following snippet lists esy repository structured (omitting irrelevant or obvious items) with further explanations:

├── README.md
├── Makefile
│   Common tasks and workflows for esy development.
├── bin
├── docs
│   esy end user documentation in markdown format.
├── dune
├── dune-project
├── esy
│   This dune library implements sandbox builder - a routine which builds
│   the enture dependency graph and provides other introspection APIs.
├── esy/bin
│   This dune executable implements "esy" command.
├── esyi
│   This dune library implements installer.
├── esyi/bin
│   This dune executable implements "esy install" command.
├── esy-build-package
│   This dune library implements package builder. esy library uses this to
│   build each package.
├── esy-build-package/bin
│   This dune executable implements "esy-build-package" command.
├── esy-installer
│   Implementation of installation procedure defined with *.install files.
│   This re-implements opam-installer.
├── esy-command-expression
│   Parser for #{...} syntax used in esy manifests.
├── esy-shell-expansion
│   A simple shell expansion.
├── esy-yarn-lockfile
│   Parser for a subset of yarn lockfile format.
├── esy-lib
│   A collection of utility modules shared between other libraries.
├── site
│   Sources for https://esy.sh
├── esy.lock.json
├── package.json
├── scripts
├── test
│   Unit tests.
└── test-e2e
    End-to-end test suite.


To make changes to esy and test them locally:

% git clone git://github.com/esy/esy.git
% cd esy
% make bootstrap


% make

to see the description of development workflow.

Running Tests

% make test


There are two branches:

  • master — the active development, we cut new versions out of there regularly.
  • 0.0.x — maintainance branch for 0.0.x releases.

Workflow for esy.sh

To make changes to esy.sh:

  1. Bootstrap site's dev environment:
% make site-bootstrap
  1. Run site locally:
% make site-start
  1. When you are happy with the changes:
% make site-publish


Issues are tracked at esy/esy.

Publishing Releases

esy is released on npm.

Because esy is written in OCaml/Reason and compiled into a native executable we need to acquire a set of prebuilt binaries. We employ CI servers (thanks Travis CI) to build platform specific releases.

The release workflow is the following:

  1. Ensure you arre on master branch and run

    % make bump-patch-verson
    % git push && git push --tags

    (this bumps patch version, use bump-minor-version or bump-major-version correspondingly to bump either minor or major version of esy)

  2. Wait till CI finishes its task and uploads releases on GitHub, check https://github.com/esy/esy/releases for them.

  3. Run

    % make release

    Which downloads platform specific releases (which CI uploaded GitHub) and produces an npm releases with needed metadata inside _release directory.

  4. Ensure release inside _release directory is ok.

    You can cd _release && npm pack && npm install -g ./esy-*.tgz to test how release installs and feels.

  5. Run cd _release && npm publish to publish release on npm.

    Release tag next is used to publish preview releases.


Help us keep the lights on


Used By