Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Community Plugin
View plugin on GitHub


Gatsby plugin so you can write your site in ReasonML!

Check out gatsby-starter-reason for an in-depth example of how to use this plugin with your site.


  1. Install gatsby-plugin-reason

    npm i gatsby-plugin-reason


    yarn add gatsby-plugin-reason
  2. You’ll need bs-platform to compile Reason -> BuckleScript.

    You can either

    a) install globally and link to the binary

        npm i -g bs-platform
        npm link bs-platform

    or b) Install as a dependency

        npm i bs-platform
  3. Add 'gatsby-plugin-reason' to gatsby-config.js.

    // gatsby-config.js
    module.exports = {
        // ...
        plugins: ['gatsby-plugin-reason']
        // ...
  4. Create a bsconfig.json file at the root of your gatsby app with the following contents:

        "name": "my-gatsby-app",
        "reason": { "react-jsx": 2 },
        "bs-dependencies": ["reason-react"],
        "sources": [
                "dir": "src",
                "subdirs": true
        "package-specs": {
            "module": "commonjs"
        "suffix": ".bs.js",
        "refmt": 3

    For more configuration options refer to the BuckleScript docs or the bsconfig.json spec

  5. That’s it! Create your .ml/.re files and they’ll automatically be compiled to javascript when you run gatsby develop.


Creating Pages

Normally, Gatsby will take all the components defined in src/pages and turn each component into its own page, using the file name as the path.

e.g. src/pages/home-page.js exports a component that creates the page shown when a user navigates to /home-page in your site.

However, ReasonML does not allow dashes in file names or file names composed of only numbers, which means you can’t create files such as home-page.re or 404.re.

To get around that, you can use the derivePathFromComponentName option to remap the path to your component based on the name you give your page component. For instance, you can have src/pages/NotFound.re map to the 404 route as shown below:

/* Whatever string you pass to ReasonReact.statelessComponent will be the page's route
In this case, this page will be used for the 404 page */
let component = ReasonReact.statelessComponent("404");

let make = children => {
    /* ... */

let default = ReasonReact.wrapReasonForJs(~component, jsProps => make(jsProps##children));

Import ReasonReact components from JS components

  1. Create your ReasonReact component (e.g. Paragraph.re shown below)

    let component = ReasonReact.statelessComponent("Paragraph");
    let make = children => {
        render: _self => <p> children </p>
    let default = ReasonReact.wrapReasonForJs(~component, jsProps => make(jsProps##children));
  2. Import the reason file from your JavaScript components

    import React from 'react';
    import Paragraph from './Paragraph.re';
    const Component = () => {
        return <Paragraph>Hello world!</Paragraph>;


Name Type Default Description
derivePathFromComponentName boolean false Instead of deriving a page’s URL path from its file name, use the name of the component instead. See Creating pages



© 2023 Gatsby, Inc.