DEV Community: Paul Bacchus

Reason and React Meta-Frameworks

Paul Bacchus — Tue, 17 Oct 2023 13:49:48 +0000

In my previous post on trying to use the NextJS App Router and Reason I described some of the problems and limitations of their compatibility with one another. With the release of Melange 2 I decided to see if the new features of Melange 2 could help to increase the compatibility of Reason and the NextJS App Router. I have also documented some of the things learnt after trying Melange (v1) with Astro and Remix.

Melange 2

Melange 2 introduces a couple of new features that help to make Reason and ReasonReact more compatible with the NextJS App Router.

`@mel.as`

The @mel.as attribute allows us to redefine a name in the output JavaScript. Using @mel.as we can solve one of the previous problems with NextJS API route functions and Reason. NextJS expects API route functions to export a function with the name of a HTTP method. With @mel.as we can rename our Reason API function to the HTTP method we want in the output JS and get no export related errors from NextJS:

[@mel.as "POST"]
let handler = () => {
    ...
};

Will be compiled to:

function POST(param) {
    ...
}

export {
  POST ,
}

Astro API endpoints also require the route function to be named after a HTTP method, so this will be useful for Astro as well.

`$$default`

Another previous compatibility problem was the export of $$default whenever default was used as the function name in ReasonReact instead of make. The export of $$default would cause NextJS to complain and not compile. In Melange 2 $$default is still present but it is exported properly in the output JS:

[@react.component]
let default = () => {
    ...
};

Compiles to:

function Page$default(Props) {
    ...
}

var $$default = Page$default;

export {
  $$default as default,
}

@mel.as and the changes to $$default make Reason and ReasonReact much more compatible with the NextJS App Router.

Structuring a Reason and React meta-framework app

After experimenting with Reason plus Astro, NextJS, and Remix, I think there are two main ways to structure a React meta-framework app for use with Reason, and it depends upon how much Reason you want to use and how you are deploying your app. If you want to write a few components in ReasonReact then it is best to promote (i.e., copy) the output JS back into the src folder of your app. If you want to write most of your app in Reason then it is best to add the meta-framework files as Melange dependencies and then promote all the output JS out of the _build folder and back into the root.

Why promote

Developing in the OCaml way can be done by copying all of the meta-framework files to the _build folder as Melange dependencies and then serving the app from the JavaScript output folder in _build. However, I have found that this doesn't always go smoothly and can cause the meta-framework development tooling to behave in unexpected ways. You could try and debug these unexpected behaviours, but ...

I have found that the meta-framework dev tooling works much better if you promote the output JS into a folder that the meta-framework dev tooling expects to be used.

Promoting the output code also makes it much easier to deploy an application via linking a Git repository to a platform like Vercel or Netlify and deploying on push.

Promoting components

If your are only using ReasonReact to create a few components then it is best to promote the output JS of those components back into the src folder. For example, if you have an Astro app like:

/
├── _build/
├── public/
├── src/
│   ├── dune
│   ├── layouts/
│   │   └── Layout.astro
│   ├── pages/
│   │   ├── dogs.astro
│   │   ├── jokes.astro
│   │   └── index.astro
│   └── reason_components/
│       ├── Dog.re
│       ├── Dog.rei
│       ├── Joke.re
│       ├── Joke.rei
│       └── dune
├── package.json
├── astro-reason.cfg.mjs
├── <project_name>.opam
├── dune
├── dune-project
└── Makefile

After promoting the output of the reason_components folder you will end up with:


/
├── _build/
├── public/
├── src/
│   ├── dune
│   ├── layouts/
│   │   └── Layout.astro
│   ├── pages/
│   │   ├── dogs.astro
│   │   ├── jokes.astro
│   │   └── index.astro
│   ├── reason_components/
│   │   ├── Dog.re
│   │   ├── Dog.rei
│   │   ├── Joke.re
│   │   ├── Joke.rei
│   │   └── dune
│   └── reason_components_output/
│       ├── node_modules/
│       └── src/
│           └── reason_components/
│               ├── Dog.js
│               └── Joke.js
├── package.json
├── astro-reason.cfg.mjs
├── .opam
├── dune
├── dune-project
└── Makefile

No doubt, the path to the components in the promoted output folder is ugly and cumbersome, but you can remedy this by adding a path alias in a tsconfig.json or jsconfig.json file:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/reason_components_output/src/reason_components/*"]
    }
  }
}

Promoting serverless functions

How you promote serverless functions depends on where you are deploying them. If you are using something like Netlify, where functions can be configured independently of the frontend, then promoting the serverless functions folder might be the best option.

Expanding on the Astro example above we can add serverless functions:


/
├── _build/
├── public/
├── reason_netlify_functions/
│   ├── dune
│   └── joke.re
├── reason_netlify_functions_output/
│   ├── node_modules/
│   └── reason_netlify_functions/
│       └── joke.js
├── src/
...
└── Makefile

We can then tell Netlify the location of our functions (./reason_netlify_functions_output/reason_netlify_functions) in a netlify.toml file. See this basic Astro, Reason and Netlify application for an example.

If you are using something like Vercel, where the serverless functions are expected to be in a certain folder, then it might be best to promote the whole app.

Promoting the whole app

When promoting only certain folders extra paths are created when the output JS files are copied back next to the Reason source files. If we were to do this for applications that require serverless function routes to be in an api folder then the path for that route would be long and ugly; for example, you could end up with something like api/output/reason_serverless_functions/joke/route.js. You could use some hacks to get around such a path, e.g., redirects or a .env value to shorten the path, but...

A better and cleaner solution is to promote the whole app. What does it mean to promote the whole app? Promoting the whole app involves adding all the meta-framework files to a melange.runtime_deps stanza as dependencies so that they are copied to the _build folder and next to the output JS files. We can then promote all the meta-framework files back out of the _build folder along with the output JS.

A typical TypeScript NextJS App Router application will be structured something like:

├── README.md
├── app/
│   ├── api/
│   │   └── joke/
│   │       └── route.ts
│   ├── jokes/
│   │   └── page.tsx
│   ├── favicon.ico
│   ├── globals.css
│   ├── layout.tsx
│   └── page.tsx
├── next-env.d.ts
├── next.config.js
├── node_modules/
├── package-lock.json
├── package.json
├── postcss.config.js
├── public/
├── tailwind.config.ts
└── tsconfig.json

We can then convert it to a Reason application:


├── README.md
├── reason_app/
│   ├── api/
│   │   └── joke/
│   │       ├── dune
│   │       └── route.re
│   ├── jokes/
│   │   ├── dune
│   │   ├── page.re
│   │   └── page.rei
│   ├── favicon.ico
│   ├── globals.css
│   ├── layout.tsx
│   ├── page.tsx
│   └── dune
├── next-env.d.ts
├── next.config.js
├── node_modules/
├── package-lock.json
├── package.json
├── postcss.config.js
├── public/
├── tailwind.config.ts
├── tsconfig.json
├── <project_name>.opam
├── dune
├── dune-project
└── Makefile

It is important to note that we are not using a src folder (i.e., ./src/app/) for our application structure and Reason source code. We will be using the src folder eventually because it is important when promoting the output JS.

We have to rename the app folder to reason_app because an app folder at the root level will take priority over a src/app folder.

In ./app/dune we add the NextJS files to the melange.runtime_deps stanza:


(library
 (name app)
 (modes melange)
 (libraries reason-react jokes)
 (melange.runtime_deps
  favicon.ico
  globals.css
  (glob_files *.tsx))
 (preprocess
  (pps reason-react-ppx melange.ppx)))

We can then add a reason_bindings folder at the root level for any bindings we want, and when we build the app the output in the _build folder will be:

./_build/default/output/
├── reason_app/
│   ├── api/
│   │   └── joke/
│   │       └── route.js
│   ├── jokes/
│   │   └── page.js
│   ├── favicon.ico
│   ├── globals.css
│   ├── layout.tsx
│   └── page.tsx
├── reason_bindings/
└── node_modules/

Note the node_modules folder. This node_modules folder contains the output JS for the Melange libraries used in the application. It is not the contents of the node_modules folder created from package.json.

Using dune directory-targets (add (using directory-targets 0.1) to the ./dune-project file) we can promote the output JS in the _build folder how we like. In ./dune we can add a rule for the promotion of the output code to the all important ./src folder, thus creating a typical NextJS application structure that uses ./src/app:

(rule
 (alias promote-app)
 (mode
  (promote (until-clean)))
 (deps
  (alias_rec nextjs))
 (targets
  (dir src))
 (action
  (bash
   "mkdir src && cp -r output/reason_app src/app && cp -r output/reason_bindings src && cp -r output/node_modules src")))

alias promote_app is an alias we can use in our Makefile so that the rule is run after every build. deps (alias_rec nextjs) is a dependency on the recursive construction of our main application code which has the alias of nextjs. dir src sets the target for the promotion of the output JS as src. In the action stanza we use bash to copy output/reason_app to src/app, making it recognisable to NextJS. We also copy reason_bindings and the Melange node_modules to src so that they are at the same directory level as app, which is important for maintaining import paths defined in the application when it was built and put into the build folder. What we end up with is:

/
├── _build/
...
├── public/
├── reason_app/
├── reason_bindings/
├── src/
│   ├── app/
│   ├── node_modules/
│   └── reason_bindings/
├── package.json
├── next.config.js
...
├── <project_name>.opam
├── dune
├── dune-project
└── Makefile

And the app should work perfectly with the NextJS dev tooling. See this basic NextJS App Router, Reason and Melange 2 application for an example.

Miscellaneous

Melange `node_modules` and deployment

If you want to deploy your app by connecting a Git repo to a service like Vercel or Netlify then you need to include the Melange node_modules folder in the repository. If you don't you will likely get errors about being unable to find certain Melange libraries during the build process.

If you don't want to commit the Melange node_modules folder to your repo then you can build the app locally using the Vercel/Netlify CLI and deploy using the CLI as well.

Another option is to use a CI/CD workflow to spin up a Linux container, install opam and build everything from scratch, but...

Directives

To use the directives "use client" and "use server" in a NextJS App Router application add [@mel.config {flags: [|"--preamble", "\"use client\";"|]}]; to the top of a file.

React Server Components

React Server Components are not yet supported by ReasonReact. You can work around this by creating a standard page.tsx file. If you need a React component then you can write one in ReasonReact and import it into the page file.

Editor errors when importing components from ReasonReact

If you structure your application so that the whole app is going to be promoted out of the _build folder and you import a ReasonReact component from a .re file into a page.tsx file you will get an editor error about the import. This error occurs because you have to import the component as if the .re file was a JS component file. Once compiled the .re file will be converted to a .js file in the _build folder and it will be in the correct location for the import to work properly after promotion. This is another reason to ensure that the folder structure of the output JS in the _build folder is maintained when promoting the code.

Special characters in file names

Dune will allow some special characters in folder names but it does not allow them in file names (in my limited experience). Remix uses file name based routing and the file names can have special characters in them, e.g., concerts.$city.js. When a file name with special characters in it fails to compile we can use a Dune rule stanza to create an output JS file with special characters in it:


; ./src/routes/dune

(library
 (name app)
 (libraries reason-react routes bindings)
 (modes melange)
 (melange.runtime_deps tailwind.css concerts_city.js)
 (preprocess
  (pps reactjs-jsx-ppx melange.ppx)))

(rule
 (target concerts.$city.js)
 (deps %{project_root}/remix/app/routes/concerts_city.js)
 (action
  (copy %{deps} %{target})))

In the above dune file we add concerts_city.js to the melange.runtime_deps - this is the output JS file name created from the Reason source code file concerts_city.re. In the rule stanza we set the target as the special character containing file name we want and the dependency (deps) as the path to concerts_city.js in the _build folder. The rule then copies concerts_city.js to concerts.$city.js, which should then work perfectly in a Remix application. Here is a broken and unfinished Remix app that may be of some limited use.

Hot Module Replacement (HMR)

If you find that HMR is not working properly it might help to add a delay to the meta-framework file watcher. For NextJS you could add the following to next.config.js:

...
const nextConfig = {
  ...
  webpack: function (config, context) {
    config.watchOptions = {
      poll: 1000,
      aggregateTimeout: 300,
    };
    return config;
  },
  ...
};
...

Ignore `_build` and `_opam` folders

A meta-frameworks file watcher will watch for any changes in any of the files and folders in root. The presence the OCaml _build and _opam folders can cause the meta-frameworks file watcher to behave in unexpected ways, so it is best to configure the meta-frameworks file watcher to ignore the _build and _opam folders. For Astro you can add the following to astro.config.mjs:

...
export default defineConfig({
  ...
  vite: {
    server: {
      watch: {
        ignored: ["**/_build/**", "**/_opam/**"]
      }
    }
  },
  ...
});

Conclusion

Melange 2 and the capabilities of Dune allow Reason and ReasonReact to work very well with React meta-frameworks. There maybe a few aspects of the meta-framework and their development tools that you have to work around, but hopefully the information above should help to make development go smoothly.

Thank you to Javier Chávarri for the help with Dune.

NextJS, the App Router and ReasonReact

Paul Bacchus — Mon, 21 Aug 2023 14:36:47 +0000

TLDR

After creating a demo application with Astro and ReasonReact I thought I would try and recreate the app using NextJS and the App Router. In the Astro app components were written using ReasonReact and then imported into an Astro file from the output JS files created by Melange. This time I wanted to try and use no JS at all and write the whole thing in Reason. The code can be found here.

The Dune way

The `_build` folder

When Dune builds a projects the output is placed into the _build directory. For the Astro application mentioned above ReasonReact components were promoted out of the _build folder and back into the src folder, which made it easier to import the components into .astro files. Because NextJS uses folder based routing I wanted to try and keep the directory structure as clean as possible and without promoted folders, thus making the directory structure the same as a regular JavaScript NextJS app.

For the NextJS app to work properly from the _build directory, files and folders required by the app have to be copied into the output directory using the runtime_deps stanza in a dune file:

(melange.emit
 (target nextjs-app-folder-reason)
 (alias nextjs)
 (module_systems es6)
 (libraries app api components bindings)
 (runtime_deps
  jsconfig.json
  next-env.d.ts
  next.config.js
  package.json
  postcss.config.js
  tailwind.config.js
  tsconfig.json
  (source_tree public)))

This effectively replicates the standard app directory structure in the _build folder, and on compilation the Reason files will be compiled to JS files:

To run the app from the root directory the commands in package.json have to be updated, e.g., "cd _build/default/nextjs && next dev".

`dune` files

In the image above you can see that there are a lot of dune files. The dune files contain stanzas that, among other things, can define libraries, specify what libraries this library relies on, and how the library should be processed. For example, the dune file in the api folder is:

(library
 (name api)
 (libraries melange-json melange-fetch bindings joke)
 (modes melange)
 (preprocess
  (pps melange.ppx)))

Every subfolder of api/ is a route, e.g., api/joke/, and requires its own dune file, which is then referenced in the api/dune file.
Writing a dune file for each route (and page) is not hard, but it could get tedious really quickly if there are a lot of them.

One way to get around this is to modify the api/dune file with (include_subdirs qualified); this means that every subdirectory of api/ can be referenced by module namespacing and we don't have to write dune files for every route (or pages) folder. However, the OCaml LSP does not like it and red squiggles will show up in the editor (although the app with still compile without errors). Trying to develop the app knowing those red squiggles cannot be vanquished would drive me nuts, so instead of using (include_subdirs qualified) I just wrote dune files for every route (and page) which gets rid of the red squiggles.

Dune and the NextJS dev server are completely fine with this application and directory structure, and everything works during development; but when trying to build the app NextJS turns cantankerous.

Computer Says No

`make`

When creating a React component with Reason it is typical to use the word make as the name of the function that will create the component. So the dogs page, for example, might look something like:

// src/app/dogs/page.re

[@react.component]
let make = () => {
  <Dog />; // Dog component from src/app/components/Dog.re
};

In the output JS file created by Melange the export will be:

// ...
var make = Dog;

export { make };

But next build will give a type error:

Type error: Page "src/app/dogs/page.js" does not match the required types of a Next.js Page.
"make" is not a valid Page export field.

Okay. Let's try changing make to default. Now the output JS has a default export:

// ...
var $$default = Page$default;

export { $$default, $$default as default };

But still next build will give a type error:

Type error: Page "src/app/dogs/page.js" does not match the required types of a Next.js Page.
"$$default" is not a valid Page export field.

Deleting the extra $$default from the export in the output JS file, so that the the export is just export { $$default as default };, seems to fix the problem, but editing the output JS is a bad idea and not practical. I'm not sure why Melange adds the extra $$default to the export but NextJS does not like it.

Routes

According to the NextJS docs routes have to export a function with the name of the HTTP method you want to use, e.g., export async function POST(request) {...};. In Reason/OCaml we cannot use POST as the name of a function because a word beginning with an uppercase letter is a constructor for a data type. To get around this we can we use bs.raw to write some raw JavaScript in the Reason code:

// src/app/api/joke/route.re
let handler = request => {
/// ...
};

[%%bs.raw {|export const POST = handler|}];

And the output JS will be:

...
export const POST = handler
;

export {
  decodeJokeCount , // JSON decoder function
  decodeJoke ,      // JSON decoder function
  handler ,
}

Will next build let us pass??? No.

Type error: Route "src/app/api/joke/route.js" does not match the required types of a Next.js Route.
"decodeJokeCount" is not a valid Route export field.

Type error: Route "src/app/api/joke/route.js" does not match the required types of a Next.js Route.
"decodeJoke" is not a valid Route export field.

Type error: Route "src/app/api/joke/route.js" does not match the required types of a Next.js Route.
"handler" is not a valid Route export field.

Once again NextJS does not like the extra export fields. Using an interface file can restrict the exports and make decodeJokeCount and decodeJoke private; however, trying to make handler private so that the only export is export const POST = handler; is not possible, and trying to do so causes Melange to output an empty JS file.

Refactoring

To stop next build from slapping us with type errors we have to wrap the Reason code with JavaScript, which means creating page.js and route.js files and importing the Reason code (the output JS code) into them. This is now a situation that is similar to the Astro project, and so now, rather than having many folders and many dune files, all of the Reason code can be put into one folder. Because of this it also makes sense to promote the output JavaScript out of the _build folder and back into the src folder, which means that project files no longer have to be copied to the _build folder.

Directives and bindings

"use client" directive binding:

[@bs.config {flags: [|"--preamble", "\"use client\";"|]}];

Font and metadata bindings for the root layout:

[%%bs.raw "import './globals.css'"];
[%%bs.raw "import { Inter } from 'next/font/google'"];
[%%bs.raw "const inter = Inter({ subsets: ['latin'] })"];

type font;
type metadata = {
  title: string,
  description: string,
};

[@bs.val] external inter: font = "inter";

[@bs.get] external fontClassName: font => string = "className";

Since the Reason code is now wrapped in JS less bindings are required because they can just be written in the JavaScript file; therefore, bindings like those above are no longer needed.

The refactored code is the code in the main branch. The all Reason code version of the app can be found on the include-subdirs-qualified branch.

Conclusion

Replacing all of the JavaScript in a NextJS App Router application with Reason is currently not possible. Reason can be used for the majority of the code but it will need to be wrapped in JS for it to be compatible with NextJS. I'm not sure why NextJS is so strict on what fields are exported. As long the fields NextJS needs are exported I don't see why other export fields are a problem, especially since they cause no problem during development. I also wish these problems would have showed up sooner during development instead of during building. There may be some Dune or NextJS configuration options that I have missed, but at this point I'm too tired and bored to try and figure it out.

ReasonReact, Auth0 and 3rd Party React Components

Paul Bacchus — Sun, 16 Jul 2023 12:17:56 +0000

One of the ways I like to test a technology is to try and implement something that could be required in a real world app, and authentication is one of those things. I have also been wanting to see how easy it is to use a third-party JS React component with ReasonReact. So, to kill two birds with one stone I created a simple app that uses the Auth0 React component. You can view the app here, and the code is here.

Using the `Auth0Provider` component

The login for the app is based on the Auth0 quick start tutorial for React, and the first thing we have to do is wrap our App in the Auth0Provider. In JavaScript we would do import { Auth0Provider } from '@auth0/auth0-react'; and wrap our App component with the imported Auth0Provider component, but in ReasonReact we need to write some bindings to the component using Melange attributes.

module Auth0Provider = {
  type auth_param = {redirect_uri: string};

  [@bs.module "@auth0/auth0-react"] [@react.component]
  external make:
    (
      ~domain: string,
      ~clientId: string,
      ~authorizationParams: auth_param,
      ~children: React.element
    ) =>
    React.element =
    "Auth0Provider";
};

@bs.module is a Melange attribute that lets us bind to a value from a JS module. The = "Auth0Provider" at the end is the JavaScript name of the value/component we are binding to. The external before the make is used for JS interop/FFI and is like an FFI let binding. Everything else in between is the type signature of a React component in ReasonReact.

In Reason each file is a module, and it is common to have one ReasonReact component per file with the filename being the name of the component. We can also define modules within files which is what we have done for the Auth0Provider in the snippet above, and we use the component like so:

<Auth0Provider
  domain="dev-dj37pygvjwvaxjde.us.auth0.com"
  clientId="e6mvq0WBov5jSBW0clTFdAIXgbyyK4gv"
  authorizationParams={redirect_uri: origin ++ "/profile"}>
  <App />
</Auth0Provider>

Using the `useAuth0()` hook

Now that we have wrapped our App with the Auth0Provider we can start using the useAuth0() hook in our components, and to do so we must write some bindings to the hook.

Because in JavaScript we would import the hook we again have to use the @bs.module attribute to bind to it:

type hook;
[@bs.module "@auth0/auth0-react"] external useAuth0: unit => hook = "useAuth0";
|--------------------1-------------------| |---2---| |-3-|  |-4-|   |----5----|

Here we are telling Reason that we are binding to an external something in the module "@auth0/auth0-react"(1) and that something is called "useAuth0"(5) in JS land; we are binding "useAuth0"(5) to the name useAuth0(2) in Reason land; and useAuth(2) takes a unit(3) (i.e., takes no arguments; equivalent to useAuth0() in JS) and returns a hook(4). We have to give the return value a type (type hook) so that the type system knows what we have just "imported"/bound to, and which we need when we want to bind to the values and methods of the hook.

(You don't have to use the same JS name in Reason for a binding. For example, you could do something like:

[@bs.module "@auth0/auth0-react"] external useAuth0Reason: unit => hook = "useAuth0";

You would then just use useAuth0Reason in your ReasonReact code. In fact, you may need to rename bindings if they clash with reserved key words in Reason.)

The useAuth0 hook provides various state values and methods, and to use them we need more bindings.

To call a method we use the bs.send attribute:

[@bs.send] external loginWithRedirect: hook => unit = "loginWithRedirect";

To get a value we use the bs.get attribute:

type user;
[@bs.get] external user: hook => user = "user";

Once defined we can use the bindings in our ReasonReact components:

// LoginButton.re
[@react.component]
let make = () => {
  let ua = Bindings.Auth0.useAuth0();

  <button
    className="py-2 px-4 rounded-md bg-blue-500 text-white"
    onClick={_ => Bindings.Auth0.loginWithRedirect(ua)}>
    {React.string("Log In")}
  </button>;
};

And the very readable output JavaScript of the LoginButton ReasonReact component:

// Generated by Melange

import * as React from "react";
import * as Auth0React from "@auth0/auth0-react";

function LoginButton(Props) {
  var ua = Auth0React.useAuth0();
  return React.createElement(
    "button",
    {
      className: "py-2 px-4 rounded-md bg-blue-500 text-white",
      onClick: function (param) {
        ua.loginWithRedirect();
      },
    },
    "Log In"
  );
}

var make = LoginButton;

export { make };
/* react Not a pure module */

Bindings can be written as they are needed, and once written completing the Auth0 quick start guide is pretty straight forward.

Conclusion

Third-party JS React components can be successfully used in any ReasonReact project. Bindings may look complicated, but once you've written a couple of them you quickly get the hang of it.

Cover image by Miguel Á. Padriñán from Pexels

Getting started with ReasonReact and Melange

Paul Bacchus — Fri, 07 Jul 2023 13:01:35 +0000

A bit of background

To quote the official docs:

Melange is a backend for the OCaml compiler that emits JavaScript. Melange strives to provide the best integration with both the OCaml and JavaScript ecosystems.

Basically, Melange lets you generate JS code from OCaml code. Reason (aka ReasonML) is an alternative syntax for OCaml that looks more like JS. Reason React are Reason bindings to React so that you can create React apps with Reason.

You may have heard of BuckleScript and you may be wondering if there is a relationship between Melange and BuckleScript. To quote the docs again:

... at some point the goals of both BuckleScript and Reason projects become harder to reconcile. In August 2020, the BuckleScript team decides to rename to ReScript, stops adding support for the latest versions of the Reason parser, and replaces it with a new parser that changes the syntax. The reasons for the rebranding are explained in the official ReScript blog post.
...
This is where Melange comes in. A few weeks after the rebranding of BuckleScript to ReScript, António Monteiro starts working on a fork of BuckleScript with a simple (not easy) goal: replace the Ninja build system, which BuckleScript had been using from its creation, with Dune, which is the most used build system for OCaml projects.

Melange has reached a 1.0 release, and it is used in production at Ahrefs. server-reason-react, which was discussed by ThePrimeagen, is a great article that shows what Melange, Reason/OCaml and ReasonReact can do.

Reading

If you know nothing about OCaml and its ecosystem the new(ish) docs are a great place to start. I would then spend some time going over the Melange docs which explain how to set everything up and JS interop. If you know JS then the syntax in the Reason docs should not be too alien. And if you know React then it should not take long to go over the ReasonReact docs.

Quick start templates

A template using both OCaml and Reason syntax, ReasonReact and webpack: https://github.com/melange-re/melange-opam-template.
A template using both OCaml and Reason syntax, ReasonReact and Vite: https://github.com/pdelacroix/melange-vite-template
A template using only Reason syntax, ReasonReact, Tailwind and Vite: https://github.com/psb/melange-opam-template.

Example apps

Here is a Hacker News app that uses ReasonReact and Tailwind. It is a port of the original app that used BuckleScript. A good exercise for the reader would be to update the app to use the official HN API.

Because Melange outputs JS you can sprinkle Reason and ReasonReact into existing JS apps. Here is an example Astro application that uses ReasonReact components and Reason lambda functions on Netlify. I'll admit that it did take a while to figure out how to get everything setup properly so that everything worked together, but now you don't have to 😄. Check out the open and closed issues in the repo to see what kind of problems I was having.

Getting help

Hopefully the docs and example apps can get you up and running with Melange, Reason and ReasonReact, but if you need further help then the Reason Discord channel is a great place to get help. I owe thanks to António Monteiro, Javier Chávarri, David Sancho and Dimitris Mostrous for helping me. Pop in and say hi 👋. There is also the Reason forum.

You can get help with OCaml and OCaml tooling in the Reason Discord but there are more OCaml people in the OCaml Discord channel and OCaml forum.

So far I have really enjoyed working with this stack. The compiler is incredibly fast, the type system and tooling are great, and Reason can fit in to the typical JS workflow. I still have some experiments I want to do with ReasonReact (e.g., using third party React components), but I hope to be able to play with Dream soon and build some full stack applications. Type safety from the DB to the frontend would be great!

DEV Community: Paul Bacchus

Reason and React Meta-Frameworks

Melange 2

@mel.as

$$default

Structuring a Reason and React meta-framework app

Why promote

Promoting components

Promoting serverless functions

Promoting the whole app

Miscellaneous

Melange node_modules and deployment

Directives

React Server Components

Editor errors when importing components from ReasonReact

Special characters in file names

Hot Module Replacement (HMR)

Ignore _build and _opam folders

Conclusion

NextJS, the App Router and ReasonReact

TLDR

The Dune way

The _build folder

dune files

Computer Says No

make

Routes

Refactoring

Directives and bindings

Conclusion

ReasonReact, Auth0 and 3rd Party React Components

Using the Auth0Provider component

Using the useAuth0() hook

Conclusion

Getting started with ReasonReact and Melange

A bit of background

Reading

Quick start templates

Example apps

Getting help

Next

`@mel.as`

`$$default`

Melange `node_modules` and deployment

Ignore `_build` and `_opam` folders

The `_build` folder

`dune` files

`make`

Using the `Auth0Provider` component

Using the `useAuth0()` hook