jtberglund / gatsby-plugin-reason

ReasonML with Gatsby!

gatsby-plugin-reason

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.

Setup

1. Install gatsby-plugin-reason

   npm i gatsby-plugin-reason
   

   or

   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.

Usage

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 => {
       ...component,
       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>;
   };

Options

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

License

MIT

gatsby-plugin-reason's Issues

.re files are not being compiled unless imported

Followed the steps:
https://www.gatsbyjs.org/packages/gatsby-plugin-reason/

However .re files are only compiled if i import them, is there any way for me to have a watcher for re files so that they are automatically compiled on save without importing them in other modules?

package.json

"bs-platform": "^5.0.4",
"gatsby-plugin-reason": "^2.0.1"

bsconfig.json

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

gatsby-config.js

 plugins: [
    `gatsby-plugin-react-helmet`,
    'gatsby-plugin-root-import',
    `gatsby-plugin-sass`,
    `gatsby-plugin-catch-links`,
    `gatsby-plugin-netlify-cms`,
    `gatsby-plugin-reason`,
    `gatsby-plugin-remove-trailing-slashes`,
    {
      resolve: `gatsby-plugin-page-creator`,
      options: {
        path: `${__dirname}/src/gatsby/pages`,
      },
    },
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `images`,
        path: `${__dirname}/src/images`,
      },
    },
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: 'blog-posts',
        path: `${__dirname}/content/posts/`,
      },
    },
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: 'pages',
        path: `${__dirname}/content/pages`,
      },
    },
    `gatsby-transformer-remark`,
    `gatsby-transformer-sharp`,
    `gatsby-plugin-sharp`,
    {
      resolve: `gatsby-plugin-manifest`,
      options: {
        name: `gatsby-starter-default`,
        short_name: `starter`,
        start_url: `/`,
        background_color: `#663399`,
        theme_color: `#663399`,
        display: `minimal-ui`,
        icon: `src/images/gatsby-icon.png`, // This path is relative to the root of the site.
      },
    },
    {
      resolve: 'gatsby-plugin-react-svg',
      options: {
        rule: {
          include: `${__dirname}/src/svgs/`,
        },
      },
    },
    {
      resolve: 'gatsby-plugin-root-import',
      options: {
        src: path.join(__dirname, 'src'),
        components: path.join(__dirname, 'src/components'),
        constants: path.join(__dirname, 'src/constants'),
      },
    },
    {
      resolve: `gatsby-plugin-create-client-paths`,
      options: { prefixes: [`/gatsby/app/*`] },
    },
    // this (optional) plugin enables Progressive Web App + Offline functionality
    // To learn more, visit: https://gatsby.dev/offline
    // `gatsby-plugin-offline`,
  ],

.ml and .re files do not compile to .js files

Using the current latest version of Gatsby (1.9), I am not able to compile either .ml or .re files after following the setup guide in the README.md.

I understand this is a vague issue, but do you have any ideas as to why? Thanks

might use soon, note any critical issues

I am not sure if I will have any spare time to contribute to this project, but I may rely on it soon.

Can you note any issues that I may encounter which do not already have github issues tracking the problem?

Reason modules using the new component syntax don't work with derivePathFromComponentName

This code

let text = ReasonReact.string;

[@react.component]
let make = () => {
  <div>
    <h1> (text("404 Not Found")) </h1>
    <p>
        (text("You just hit a route that doesn't exist... the sadness."))
    </p>
  </div>
};

React.setDisplayName(make, "404");

Will provide the following error when you try to access http://localhost:8000/404:

Page components named "404" are not being used for Gatsby's 404 page

Creating a page component with the name 404 eg.

let component = ReasonReact.statelessComponent("404");

correctly creates a page called 404, (you can navigate to it at localhost:8000/404).

However, Gatsby does not recognize this page as the actual 404 page that should be displayed when the user navigates to a page that does not exist.

Upon navigating to a non-existent page you simply see the generic message "Not Found" instead of the 404 page.