Project scaffolding tool and set of templates for Reason and OCaml.
Using Homebrew (macOS)
brew install tmattio/tap/spin
opam install spin
yarn global add @tmattio/spin # Or npm -g install @tmattio/spin
Using a script
curl -fsSL https://github.com/tmattio/spin/raw/master/scripts/install.sh | bash
You can generate a new project using a template with
spin new. For instance:
spin new native my_app
Will create a new native application in the directory
Anyone can create new Spin templates, but we provide official templates for a lot of use cases. The official templates for each type of applications are listed below.
Templates for native applications
- native - A native project containing the minimum viable configurations.
- cli - Native command line interface.
- lib - A library to be used in native or web applications.
- ppx - A PPX library to be used in native or web applications.
Templates for Bucklescript applications
- bs-react - React Single-Page-Application in Reason.
spin new TEMPLATE [PATH] [--default] [--ignore-config]
Create a new ReasonML/Ocaml project from a template.
PATH defaults to the current working directory.
--default is passed, the user will not be prompted for configurations that have a default value.
--ignore-config is passed, the configuration file will be ignored and the user will be prompted for all the configurations.
List the official Spin templates.
List the generators available for the current project.
spin gen GENERATOR
Generate a new component in the current project.
Prompt the user for values that can be saved in the configuration file.
If a value is present in the configuration file, it will not be prompted when generating a new project.
We would love your help improving Spin!
You need Esy, you can install the latest version from npm:
yarn global add esy@latest # Or npm install -g esy@latest
NOTE: Make sure
esy --versionreturns at least
0.5.8for this project to build.
Then run the
esy command from this project root to install and build dependencies.
Now you can run your editor within the environment (which also includes merlin):
esy $EDITOR esy vim
Alternatively you can try vim-reasonml which loads esy project environments automatically.
After you make some changes to source code, you can re-run project's build
again with the same simple
This project uses Dune as a build system, and Pesy to generate Dune's configuration files. If you change the
buildDirs configuration in
package.json, you will have to regenerate the configuration files using:
After building the project, you can run the main binary that is produced.
You can test compiled executable (runs
scripts.tests specified in
Documentation for the libraries in the project can be generated with:
esy doc open-cli $(esy doc-path)
This assumes you have a command like open-cli installed on your system.
NOTE: On macOS, you can use the system command
open, for instance
open $(esy doc-path)
Creating release builds
To release prebuilt binaries to all platforms, we use Github Actions to build each binary individually.
The binaries are then uploaded to a Github Release and NPM automatically.
To trigger the Release workflow, you need to push a git tag to the repository. We provide a script that will bump the version of the project, tag the commit and push it to Github:
The script uses
npm version to bump the project, so you can use the same argument.
For instance, to release a new patch version, you can run:
The following snippet describes Spin's repository structure.
. ├── .github/ | Contains Github specific files such as actions definitions and issue templates. │ ├── docs/ | End-user documentation in Markdown format. │ ├── bin/ | Source for Spin's binary. This links to the library defined in `lib/`. │ ├── lib/ | Source for Spin's library. Contains Spin's core functionalities. │ ├── test/ | Unit tests and integration tests for Spin. │ ├── test_runner/ | Source for the test runner's binary. | ├── dune-project | Dune file used to mark the root of the project and define project-wide parameters. | For the documentation of the syntax, see https://dune.readthedocs.io/en/stable/dune-files.html#dune-project │ ├── LICENSE │ ├── package.json | Esy package definition. | To know more about creating Esy packages, see https://esy.sh/docs/en/configuration.html. │ ├── README.md │ └── spin.opam Opam package definition. To know more about creating and publishing opam packages, see https://opam.ocaml.org/doc/Packaging.html.
- Add more templates
- data-science - Data Science workflow.
- desktop - Native UI application using Revery.
- graphql-api - HTTP server that serves a GraphQL API.
- rest-api - HTTP server that serves a REST API.
- react-components - React component library with Storybook.
- Support more CI/CD
- Google Build
- Bitbucket Pipeline
- Create infrastructure of generated projects (i.e. generate terraform code)
- Write tutorials for the templates (e.g. Add user authentication for graphql-api)