Spin Announcement

I remember when I started my first application with Elixir and Phoenix. I knew nothing of the language or the framework, so I read the first few lines of the documentation and very quickly ran mix phx.new to generate a new project. From there, I simply explored the structure of the project, read the source code and continued with a few mix phx.gen.json to create new components that I needed. And just like that, in a few commands, I had built a production-ready application that I knew was following web development and Elixir best practices.

Nowadays, Reason and OCaml are undoubtedly my favourite languages, but I was missing having a tool that I can trust to start new production-ready project that follow best practices. During the past months, I have been working on a project to fill this gap. I think I reached a point where it could be useful to other people, so I would like to introduce Spin, a project scaffolding tool for Reason and OCaml.

What is Spin?

Spin is a cross-platform command line interface to quickly start new OCaml and Reason projects and generate components inside generated projects.

To some extend, it is similar to tools such as mix, cargo, cookicutter or yeoman. But there are some differences that also make it a unique project scaffolding tool.

First, Spin provides official templates for certain types of applications. For now, only general types of applications such as cli and lib have official templates, but I am planning on adding domain specific templates such as GraphQL servers or data science projects.

Second, not only Spin can generate new projects, it can also be used to generate new components in existing applications. For now, only the cli template provides generators for new subcommands, but it will be really useful for the GraphQL template for instance to generate new database schema or GraphQL nodes.

Third, you will notice that the generated projects are not exactly minimalist. There are a lot of things included, in particular release scripts and CI/CD pipelines. This is because one of the goal of Spin is to decrease the time you spend on things that are not specific to your project as much as possible. Ultimately, you should be able to generate a new project and deploy it in production in a few minutes.

How to use it?

You can install it with yarn global add @tmattio/spin, or checkout the project documentation for other installation methods: github.com/tmattio/spin

If you are generating native applications, you will also need to install esy: yarn add esy.

spin ls

To list the official templates, you can use spin ls. The name of the official template can be used with spin new as the TEMPLATE.

The smallest templates are native and react for native and web applications respectively.

spin new TEMPLATE [PATH]

spin new can be used to generate new projects from a template. The project will be generated in the current directory if no PATH is provided.

Try using spin new native demo-project!

spin gen [GENERATOR]

Some templates also come with generators. The cli template for instance provides a cmd generator to generate new subcommands.

If no GENERATOR is provided (just spin gen), this will list the available generators for the current project.

Try generating a new CLI with spin new cli my-cli && cd my-cli and generate a new command with spin gen cmd!

spin config

Some template will ask you a lot of question, such as you Github username, your NPM username, etc. This is to generate the CI/CD and release scripts that are custom to your project.

To avoid having to answer to many questions when you create new projects, you can configure Spin's global environment with spin config. This will prompt you for the supported global environment values.

Design Principles

Here are some guidelines that I followed when building Spin and the official templates.

Offer a great and unified Developer Experience

The generated projects should offer a complete setup to develop on the project. This includes unit test setup, compilation watch mode, repl, documentation, etc.

All the commands are provided as Esy run scripts for native projects and NPM run scripts for web projects.

Be real-world proof

A user generating a project should be confident enough to deploy it in production as-is. This means that large templates such as CLI and GraphQL should be secure and scalable.

Bridge the gap between OCaml and Reason

OCaml and Reason are often viewed as two distinct communities, and sometimes as two different languages. This does not make sense to me and I think it would be a waste of time to duplicate the effort when the bridge between OCaml and Reason is so small to build. Spin considers OCaml and Reason as just syntax differences. The libraries, the naming conventions, the tools, and everything else are the same.

Include everyone

Even if Spin is very opiniated, it tries to be inclusive and support different workflow and platform. It currently does not support Windows and Opam, but I am working on it and would welcome any help on these issues.

Where to go from there?

Stabilize the current templates

Before creating a lot of new templates (and there a lot to build!), I would like to wait for community feedback on the existing ones. Spin is opiniated and it might be that some decisions I have taken are not the best ones, please don't hesitate to open an issue if you have any feedback or encounter any problem.

Wait for community feedback to support other CI/CD platforms

Currently, the only CI/CD platform supported is Github Actions. I am using Gitlab CI at my job, so I will probably include it in the official templates soon, but I would welcome any feedback on the need to build CI/CD pipelines for other pipelines.

Build templates for REST APIs and GraphQL APIs

The next templates that I want to build are the REST servers and GraphQL servers, they should arrive in the official templates in a few weeks.

Want to contribute?