The version of my toolchain on this date:

• Reason 3.3.3 @ e10fa53
• BuckleScript 4.0.5

Note: This article is aimed for beginners without any knowledge about Reason.

In April 2018, Nik Graf and I were giving workshops at React-Finland and got some really good impressions on how newcomers learn to code in Reason for their very first time.

The tools in the Reason ecosystem are quite useful to learn the language itself, so I try to show you how I work on Reason code inside VSCode and the terminal, to make it easier for you to get started.

Luckily since August 2018, the installation steps got way easier with the new VSCode plugin done by Jared Forsyth.

What’s the major difference to the existing ocaml / reason plugin? You can read the motivation behind this here.

This is also the only plugin which works on Windows without any hacks, therefore makes it the official recommended way of developing Reason.

Step 1— Installing the VSCode Reason Plugin

Go to the extension tab and search the marketplace for a plugin called reason-vscodeby Jared Forsyth, press the install button and reload your VSCode instance.

Now your editor should be able to interact with Reason code. After an initial build with BuckleScript, you should be able to see type information on cursor hover, inferred types and also basic type errors. Also you will notice that *.re will have correct syntax highlighting.

Step 2— Let’s try out the setup

For the next steps, let’s check out a Reason / BuckleScript based project. For convenience, we will use the same repository I use for my workshops:

ryyppy/reason-workshop

Clone the repository and run npm install to install all necessary dependencies. Since bs-platform is defined as a devDependency, all the tools you need to compile Reason to JavaScript will also be installed inside your node_modules directory.

We already defined some convenience scripts inside package.json to easily interact with the BuckleScript compiler:

"scripts": {
  "bs:clean": "bsb -clean-world",
  "bs:build": "bsb -make-world",
  "bs:watch": "bsb -make-world -w"
}

So by running npm run bs:watch you will start the BuckleScript compiler in watch mode, actively recompiling Reason files (*.re) on each change. Since BuckleScript also offers better error messages than Merlin, let’s use the watch command inside the VSCode terminal itself:

In the screenshot above, you’ll see BuckleScript up and running in the bottom terminal pane. Whenever there is a type error in our code (after saving a file), the compiler will show nice error messages for troubleshooting:

For me, I find it much easier to have BuckleScript running inside my VSCode, since I will never be required to switch from my IDE to my terminal. As soon as I adapted this workflow, I realized that my feedback loop was much quicker and I got a much more immersive coding experience.

Of course, there are many other tools which need to be run in the background, like webpack or a development server. I usually keep them in my separate terminal, because in most cases, errors only happen whenever BuckleScript doesn’t fully compile.

Last Quick Tip: Reformatting

Whenever you are editing a *.re file, you can run Shift-Option-F to reformat the editor buffer.

To try this, copy this code snippet in one of the reason files inside thesrc directory and hit the Shift-Option-F hotkey:

let addAndStringify = (
  a,
  b) => {
let c = a + b;

string_of_int(c);

};

The code should now be correctly formatted.

That’s it! After following these 2steps, you are now able to work on Reason code in VSCode.

If you have any problems with your setup, make sure to ask questions on our Reason Discord #editorsupport channel.

For more blog articles & news about Reason and other web related programming languages, follow me on Twitter.

The date for ReasonConf 2018 is coming closer but we still didn’t have the chance to talk about the Reason community and especially about the people you will meet at the conference.

Software and technology is only as strong as the people behind it. Building a productive and friendly ecosystem requires strong social and open source skills.

And let’s be honest here: especially in JavaScript, it’s quite hard to find the right candidate who satisfies all the technical, social and idealistic needs.

Let us explain why you, either as a company or individual, might be interested to join our conference and why it’s worth to be a sponsor.

But first of all: What is Reason and why should I care as a company?

Reason is a new language by Facebook, which is built on top of the reliable and established OCaml ecosystem. It’s especially popular in the ReactJS community, since it offers first class support for ReactJS and is being used to develop the Facebook Messenger app.

The Reason project tries to tackle several important pain points in the React & JavaScript community:

• Make functional programming paradigms (like those in ReactJS) approachable for JS developers
• Build even more type-safe programs than with other typed-JS tools like TypeScript & Flow … This is especially important for mission critical software with no fault-tolerance
• Offer performant & optimized JS output, without many compromises
• Bring and keep developers in the Pit of Success

You will find more technical details and why Reason might be a good fit for your company in another article called “Reasons to support ReasonConf” by Andrey Okonetchnikov.

What companies care about Reason & OCaml?

There are many other big industries and companies leveraging the OCaml (and partly Reason) platform, such as Bloomberg, Facebook, JaneStreet, Docker, Citrix, Issuu and many more.

We were really surprised when Accenture, one of the biggest consulting agencies in the world, reached out to us and said they want to sponsor us. After we thought about it and talked to them, we realized that keeping track of emerging technologies is key to get ahead of competitors and outperform them on the long run.

Now let’s talk about the community and conference attendees

There will be around 180 attendees at the conference. Most of them are fluent with ReactJS and also see the bad parts of pure JavaScript codebases. They are enthusiastic about technology and put a considerable amount of time and effort to make the Reason ecosystem better on every release.

The background of our community members is vast. Many of them were on the lookout for a functional language which is also more approachable for their coworkers. They tried Haskell, ClojureScript, PureScript, Elm, Scala, Elixir and other similar languages, which don’t really fulfil the aspect of being “JavaScripty” enough to be easily understood by their colleagues. Luckily for us, some of them got stuck with Reason.

They build things like type-safe GraphQL queries with Reason-Apollo-GraphQL or highly efficient, natively compiled, single executable graphql-servers, which are also preventing essential runtime bugs and outperform Node.js with ease.

Also there are efforts on building a natively compiled, slimmer version of webpack, called fastpack. Other projects like Esy try to eliminate unacceptable build times of native dependencies in a CI environment. Esy is a package-manager designed for building, tracking and caching native dependencies in JS and OCaml projects, while being compatible with the npm workflow.

As the conference organizers, we have a personal interest to get as many of these great minds in one place, since we are also contributing to the Reason project and want to get the most out of it.

We invited experts such as Cheng Lou (Facebook), Jared Forsyth (Khan Academy), Keira Hodgkison (Culture Amp), Cristiano Calgagno (FB Infer Project), Sven Sauleau (Babel), and many more — to educate and inspire our attendees.

We believe that most of our attendees are interested in complex technical challenges and are motivated to push forward technical innovation for better products and better engineering.

So what’s the progress?

The organization of ReasonConf 2018 is coming along quite nicely so far. We finalized the schedule, booked the flights and hotel for our speakers and also made sure that we have a really nice venue for all 3 days.

There are a few ideas which we can only make happen with stronger financial support, therefore we are looking for sponsors to make this event awesome.

By sponsoring our event, you will not only get in touch with highly talented JavaScript / ReactJS engineers, but you will also give your employees an opportunity to learn about upcoming web technologies in the heart of Vienna.

If you are interested, please get in touch.

Email: hi@reason-conf.com
Website: https://www.reason-conf.com

Patrick, Nik and Andrey

Some Words about the ReasonConf Attendees and Community was originally published in ReasonConf on Medium, where people are continuing the conversation by highlighting and responding to this story.

It’s super awesome to see a lot of libraries starting to adopt flow to add type-safetiness to their code…

BUT… what a lot of people forget is that npm packages usually ship ES5 code without any type information and in the end, the consumer of this library will only get any as imported types.

While working on the typings in styled-components, I have been looking for a guide on how to expose flow types for the user the right way and realized that there wasn’t any yet.

So this article aims to give library maintainers some guidelines / ideas on how to vendor flow definitions within the npm build process.

As a reference project, I created a repository with some bare bone package setup and some example code.

We will go through the setup step-by-step and also talk a little bit about some flow specific mechanics, e.g. how flow imports files.

So let’s get started!

Our example library my-lib consists of a src directory with some ES6 source code:

$ tree src
src
├── index.js
└── util
    ├── __tests__
    │   └── reduceChainPromises-test.js
    └── reduceChainPromises.js <-- showcasing a nested subdir

As maintainers we usually want to distribute our code as…

1. … web compatible format (UMD, AMD,…) in dist
2. … ES5 compiled source in lib (keeping the file structure of src)

We will completely ignore case 1, since as for right now, there is no easy way to expose type information for a single compiled file (except for writing a libdef file). In this article, we will focus on 2, how to make flow recognize types for files shipped in lib.

In our first step, we will install all necessary devDependencies to get our build chain going:

npm install babel-cli babel-core babel-preset-es2015 babel-plugin-transform-flow-strip-types flow-copy-source rimraf --save-dev

If you have already been using babel, then you are probably familiar with most of these dependencies. The babel plugin babel-plugin-transform-flow-strip-types will make sure that all flow related code will be stripped out in our compiled ES5 code.

Additionally, we install rimraf for running rm -rf commands and flow-copy-source to easily create so-called “flow-files”, which will be explained later on.

The most interesting part is, that all our tools are running on node so we don’t have to worry about any Windows / OSX / Linux development setups.

For completeness, here is our .babelrc:

{
  "presets": ["es2015"],
  "plugins": ["transform-flow-strip-types"]
}

Alright, now babel understands ES6 + flow syntax! Let’s go through our package.json scripts next:

{
  "name": "my-lib",
  ...
  "scripts": {
    "test": "jest",
    "build": "npm run build:clean && npm run build:lib && npm run    
              build:flow",
    "build:clean": "rimraf lib",
    "build:lib": "babel -d lib src --ignore '**/__tests__/**'",
    "build:flow": "flow-copy-source -v -i '**/__tests__/**' src lib"
  }
  ...

}

In our scripts section, we can find thebuild instruction, which will do three things:

1. npm run build:clean: Removes the current lib directory
2. npm run build:lib: Builds lib from scratch by compiling src via babel
3. npm run build:flow : Creates our flow-files, which are also put into lib

Step 3) is relevant for our goal… we call flow-copy-source which will (by default) copy all *.js files in src and copy them into the target directory lib , preserving the original directory hierarchy. Those files will have a different file-ending, called *.js.flow.

Side Note:
I am using jest for testing, that’s why I added ignore rules for **/__tests__/** globs. I don’t want test files to land in lib.

Here is a listing of our resulting lib after running npm run build:

$ tree lib
lib
├── index.js
├── index.js.flow <-- Exact same content as src/index.js
└── util
    ├── reduceChainPromises.js
    └── reduceChainPromises.js.flow

Introducing “flow-files” (*.js.flow)

So if there is a file src/util/reduceChainPromises.js, the whole file will be copied to lib/util/reduceChainPromises.js.flow … but why do we need that?

Flowtype resolves modules the same way as node does. If you are importing my-lib/lib/util/reduceChainPromises, you would probably do it like this:

import reduceChainP from 'my-lib/lib/util/reduceChainPromises';

By default, flow will look into node_modules/my-lib and try to find the file lib/util/reduceChainPromises. But wait! Files in lib only contain pure ES5 code, so we loose our type information (flow will most likely treat reduceChainP as type any).

Luckily, if flow finds files with a *.js.flow file ending, it will prefer it over the actual *.js. So we vendor additional files, which will only tell flow what types are exposed in the accompanied ES5 file. Since these files are generated in our build process, we can always be sure that our flow-files are synced up with the actual code.

What about the file bloat?

You will probably argue that copying the whole src files to lib will unnecessarily bloat the resulting npm package, right? The flow team is aware of that issue and is working on an experimental command called flow gen-flow-files:

$ flow gen-flow-files --help
Usage (EXPERIMENTAL): flow gen-flow-files [OPTIONS] [FILE]

e.g. flow gen-flow-files ./src/foo.js > ./dist/foo.js.flow

As soon as this feature is stable, we will be able to extract pure type information from our ES6 code, and put those type information in our *.js.flow, ultimately stripping the implementation code (kinda like the invert of what babel does to our src files).

Okay nice, so we now have a build system which will generate backwards compatible ES5 code AND add type definitions for our library, ready to be used by the consumers.

This was just a very basic introduction to this topic.

There are still a lot of open questions:

• What about dependencies for our library?
• What about dependency collisions with our library (e.g. lodash)?
• What about different flow versions between the consumer & my library?

As soon as I find some time, I will do some follow up articles where we will deep dive into these problems and discover how to solve them as well!

You can check out our flow-support docs on styled-components to see how a more complex library is being typed and shipped with flow.

For questions or more updates on Flowtype leave me a tweet or follow me on Twitter @ryyppy

Shipping Flowtype Definitions in NPM Packages was originally published in Netscape on Medium, where people are continuing the conversation by highlighting and responding to this story.