Skip to content
Project scaffolding tool and set of templates for Reason and OCaml.
Reason JavaScript Shell Other
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows Fix CI/CD publish step Mar 9, 2020
bin Add extra check for local templates Mar 23, 2020
docs Fix grammar & spelling Feb 14, 2020
esy.lock Update dependencies Mar 11, 2020
lib
scripts Fix CI/CD publish step Mar 9, 2020
test
.gitattributes Clarify wording Dec 30, 2019
.gitignore Update ignore files Jan 12, 2020
.spin
CHANGES.md Add changes to templates in the changelog Mar 18, 2020
CODE_OF_CONDUCT.md Create CODE_OF_CONDUCT.md Feb 15, 2020
LICENSE Initial commit Dec 13, 2019
README.md Update template name Mar 11, 2020
dune-project
package.json Add ocamlformat to dev dependencies Mar 8, 2020
spin.opam Remove separated dev.opam file Mar 9, 2020
spin.opam.template

README.md

Spin

Project scaffolding tool and set of templates for Reason and OCaml.

Build Status npm version

FeaturesInstallationTemplatesUsageContributingRoadmap

Demo

Features

🚀 Quickly start new projects that are ready for the real world.

❤️ Have a great developer experience when developing with Reason/OCaml.

🏄 Be as productive as Ruby-on-Rails or Elixir's Mix users.

🔌 Establish a convention for projects organizations to make it easy to get into new projects.

Installation

Using Homebrew (macOS)

brew install tmattio/tap/spin

Using Opam

opam install spin

Using npm

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

Templates

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 ./my_app/

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.

Usage

spin new TEMPLATE [PATH] [--default] [--ignore-config]

Create a new ReasonML/Ocaml project from a template.

PATH defaults to the current working directory.

When --default is passed, the user will not be prompted for configurations that have a default value.

When --ignore-config is passed, the configuration file will be ignored and the user will be prompted for all the configurations.

spin ls

List the official Spin templates.

spin gen

List the generators available for the current project.

spin gen GENERATOR

Generate a new component in the current project.

spin config

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.

Contributing

We would love your help improving Spin!

Developing

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 --version returns at least 0.5.8 for this project to build.

Then run the esy command from this project root to install and build dependencies.

esy

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 esy command.

esy

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:

esy pesy

Running Binary

After building the project, you can run the main binary that is produced.

esy start

Running Tests

You can test compiled executable (runs scripts.tests specified in package.json):

esy test

Building documentation

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:

./scripts/release.sh

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:

./scripts/release.sh patch

Repository Structure

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.

Roadmap

  • 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.
    • bs-bindings - BuckleScript bindings to Javascript libraries.
  • Support more CI/CD
    • GitLab
    • Azure
    • 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)
You can’t perform that action at this time.