Forem: Matt Hagner

A Primer on Testing & TDD

Matt Hagner — Fri, 09 Aug 2019 14:14:42 +0000

There are two types of people in the world: those who love testing in React, and those who have never tried @testing-library/react.

I joke, but this article is a light introduction into what test-driven
development is, why I find it useful with front end development, an overview of what should be tested, and what the differences are between different kinds of tests.

There are a lot of opinions that I express in this article that pertain to my personal style of development. You may not agree with some or all of my opinions and that totally is fine.

This is the first article in a series on testing in React. In the next post I will talk about @testing-library/react for unit testing, so if you'd like to be notified of future posts make sure to follow.

What is test-driven development?

Test-driven development took rise during the early 2000s. The basic premise was that we should write our tests before we write our implementations to avoid the false-positive affirmation that can happen when you write tests after you write your implementation.

The main ethos of test-driven development can be summed up in three words: red, green, refactor.

You write a test that you know will fail because you haven't implemented the feature yet. You write code to make that test pass. And now you can refactor the portion of code that is tested with confidence.

You repeat the cycle by writing more tests to cover other aspects of the feature, tests against regressions, and tests against edge cases you discover.

Test-driven development can be extremely powerful, however, the goal isn't to have 100% code coverage and you shouldn't feel the need to write a test for every little thing. This can be a slippery slope and at some point writing more tests is not going to increase your confidence in the code base, or make you more productive.

Why do I write tests?

I write tests because I've found that when employing test-driven development it helps me write more ergonomic components. I avoid poor design choices the first time around because I write the usage before I write the implementation.

Having tests written for a component or feature helps me refactor with confidence. If the test was passing before I made a change and the behavior is expected to be the same, then any change I make should not make the test fail. If it does I've either 1) broken the contract and will need to update all usage of the component throughout the application, or 2) tested implementation details and I should delete the tests if not needed, or update them to not test implementation details.

I've also found that when practicing test-driven development I'm a lot more focused. I can write down some expectations, set a timer for 25 minutes, and then get to work. I focus on one thing at a time. Write a test. Watch the test fail. Start implementing the feature. Watch the test pass. Refactor if needed. And then move on to the next thing. I tend to get a lot more done a lot faster than if I just start writing code without a clear direction in mind.

What should we test?

A better first question might be who should we write tests for? The answer is pretty simple. Our users. As developers we have two users of our code. The actual end-user who is interacting with our website or application, and our future selves or other developers who will use our code to implement other features or make changes to our code.

For example let's say we need to make a Button in React. There could be a developer who uses that Button in a different part of the application, and there could be a user of the app who interacts with that Button.

The parts that those two users need to interact with should be the things that we test. What are their expectations? What are our intentions?

The user probably expects to be able to interact with it. Depending on the context of the button on the page they could expect it to submit a form, lead them to a new page (a link that looks like a button), to increment a counter, to save some data, etc.

The developer might expect to be able to pass their own click handler into it and have it fire reliably. They might expect to be able to change the button text, override, append, or modify styles, they might expect to have some mechanism for disabling the button.

Some of these expectations can be tested in a generic way at the unit level, and some will make more sense as an integration test where the component is actually being used in a specific context.

We can even use static testing via linters or tools like Storybook and the a11y addon to test our code for best practices. Like making sure that we are using a button for interactive elements or passing the DOM element the applicable aria properties like role=button, aria-pressed and making it focusable if we are using something like a div.

A11y is shorthand for accessibility. A, 11 letters in the middle, y.

Unit vs Integration vs End to End

Guillermo Rauch once tweeted "Write tests. Not too many. Mostly integration". I think this is a pretty good tweet to model your testing practices after.

So what are some of the different types of tests?

Unit Tests

Unit tests are tests centered around a unit of code. It could be a singular function, or a component. When you first start testing you will typically write a lot of unit tests. Soon you will realize though that they don't really give you confidence in your application, instead in an isolated piece of code. You end up having to mock a lot of things, and any time you have mocks in your tests your overall confidence in these tests are lowered.

Note on mocking. Sometimes it's necessary to mock some functionality or 3rd party library. Take data fetching for example. You don't want to be making requests to APIs in your tests because this would make your tests slow. You also don't know when or how many times your tests will be run so making potentially dozens or hundreds of requests every time your tests run 😬 That's a big yikes from me.

Integration Tests

Integration tests focus on larger chunks of code. In React it could be a page, or a larger component like a form that contains a bunch of smaller components. Integration tests are the bread and butter of testing. This is where you are testing the actual usage of your components, instead of testing the potential usage.

End to End Tests

End to end tests are typically harder to set up, and more costly to run. You should still consider having end to end test in your code base. End to end tests simulate user interaction through the entire application/website. Usually you will test certain flows through the application like signing a user up, making a new post, editing the post, or deleting a post the user is authorized to delete.

Property-Based Tests

Property-based testing hasn't really made too many waves in JavaScript but is popular in languages like Clojure and Elixir. We won't do any property-based testing in this series but the idea is that you test a provable property (think of mathematical properties) against your piece of code, you use some sort of input generation, and it can catch edge cases where that property breaks.

Static Tests aka Static Analysis

While not necessarily tests in the traditional sense, static analysis is the combination of tools like Eslint, and type checkers (if you're using a statically typed language like TypeScript), among other things, that allow you to check your code for correctness in some way. When static analysis is used correctly it helps you catch potential bugs early, or notify that you are doing something you shouldn't, like putting an onClick handler on a div instead of just using a button. When used incorrectly, like using Airbnb's Eslint rules, static analysis will cause you headaches and make you significantly less productive, unless of course you work at Airbnb and need to adhere to their code style guide.

Conclusion

We've talked about what test-driven development is, why I like to practice test driven development, how to identify what we should be testing, and what the difference between different types of tests are.

If you have any questions please post them in the comments.

Setting up Tailwind With create-react-app

Matt Hagner — Fri, 02 Aug 2019 13:58:42 +0000

What is Tailwind?

Tailwind is a functional CSS framework that is ergonomic to use, but low level enough to make it fully customizable. You can configure it, add plugins, and override defaults. It generates CSS class names for you so that you can use compose them throughout your project.

I've found that Tailwind lends itself particularly well to developing components in React and Vue.

What does it look like?



import React from 'react'

export default function Input(inputProps) {
  return (
    <input 
      className="px-2 py-1 text-gray-700 bg-gray-200 rounded-lg shadow-md border-2 border-gray-800 focused:border-blue-400"
      {...inputProps} 
    />
  )
}

What do all of those classes mean? Most of the classes should be pretty self explanatory. The px-2 and py-1 are horizontal (x), and vertical (y) padding respectively. The 2 and 1 refer to the sizing.

By default Tailwind generates a set of sizes for you that you can customize. Sizing 1 starts at 0.25rem and the sizing goes up by 0.25rem each step.

The class naming follows pretty easy to understand conventions so once you start learning some you will understand how to use most. For instance to set a margin vertical margin of 2 rem you would use the class name my-8. m because you are setting margin, y because you want to set only the vertical axis margin, and 8 because you want 2 rem and the sizing is 4 per rem.

Things that can accept a color value like text, border, or background have their prefix text, border and bg, followed by the color name text-gray, border-gray or bg-gray and then a value from 100-900 that jumps by 100. So text-gray-700 will make the text a fairly dark gray, and bg-gray-200 will give the background a fairly light gray color.

The focused:border-blue-400 class applies a blue 400 color to the border when the focused pseudo class is active for the element.

rounded has a number of suffixes to affect the class like sm, lg, and full with the default being a medium rounded border if there isn't a suffix. There is even the ability to change any corner individually.

shadow is similar to rounded but with the default being small with no suffix, and sizing all the way to 2xl. Additional modifiers that make sense for a box shadow are also available like inner or outline.

Why would you use it?

When you get into the flow it's like writing regular CSS with shorthands except you don't have to do it in a separate file, you don't have to come up with a bunch of class names, and you don't have to possibly update two files every time you change the styles for a single element.

It makes your code easier to delete. We'll touch on this more later, but traditional CSS is append only, which means it is really hard to know when you are okay to delete some styles.

Component based styling, which you can absolutely do with Tailwind, allows you to delete the styles along with the component when you no longer need it.

Tailwind is also totally and completely extendable. Want to add different colors, or change the ones included with Tailwind? You totally can and the API to do so is pretty well documented and easy to follow.

How do we set up create-react-app to use Tailwind?

Let's set up our project by scaffolding a new react app with create-react-app. If you don't have it installed you can use npx.



npx create-react-app setting-up-tailwind && cd setting-up-tailwind

Now we need to install some dev dependencies.



yarn add -D tailwindcss autoprefixer postcss-cli

In the root of the project create a postcss.config.js file and open it up in your favorite editor.



module.exports = {
  plugins: [
    require('tailwindcss'),
    require('autoprefixer'),
  ]
}

If you're interested in finding out more about PostCSS check out the Github

Autoprefixer is recommended to install alongside Tailwind, because autoprefixer automatically tracks caniuse.com to see which CSS properties still need to be prefixed, and out of the box Tailwind does not provide any vendor prefixing.

Now we should initialize Tailwind. This will create a tailwind.config.js file in the root of our project with a default configuration. This step is optional, but I usually do this when setting up a Tailwind project so that I can customize things later without having to come back.



npx tailwind init

If you open it up it looks pretty barren right now. Maybe in a different post I'll go over adding plugins, or customizing Tailwind.



// tailwind.config.js
module.exports = {
  theme: {
    extend: {}
  },
  variants: {},
  plugins: []
}

We also need to create an input CSS file for PostCSS to process with Tailwind. I usually call this tailwind.css and add it to the src folder in my React projects, but you can name it whatever, and place it in any place that makes sense to you.



/* src/tailwind.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

These are Tailwind directives that add the three main parts of core Tailwind. You can make your bundle smaller by omitting one or multiple if you don't need them, but to get the most from Tailwind you will probably end up using at least some classes from each.

When Tailwind (the first plugin in PostCSS) sees these directives it will replace each @tailwind <name> with some CSS.

To make it easy on ourselves in the future case where we might be changing the tailwind.config.js we should add a few scripts to our package.json file. Add the following three scripts to the scripts object.



// package.json
{
  //...
  "scripts": {
    //... place these after the four scripts created by CRA
    "build:styles": "postcss src/tailwind.css -o src/styles.css", 
    "prebuild": "yarn build:styles",
    "prestart": "yarn build:styles"
  }
}

Or if you use npm change yarn to npm run



{
  //...
  "scripts": {
    //... place these after the four scripts created by CRA
    "build:styles": "postcss src/tailwind.css -o src/styles.css",
    "prebuild": "npm run build:styles",
    "prestart": "npm run build:styles"
  }
}

Building our React component

Let's delete some of the unnecessary stuff that create-react-app makes for us.



rm src/App.test.js src/App.css src/index.css src/logo.svg

Open up src/index.js and make the following changes.



// src/index.js
import React from 'react';
import ReactDOM from 'react-dom';
import './styles.css' // <- change './index.css' to './styles.css'
import App from './App';
import * as serviceWorker from './serviceWorker';

ReactDOM.render(<App />, document.getElementById('root'));
serviceWorker.unregister();

Now open up src/App.js, delete the whole thing and start from scratch.



// src/App.js
import React from "react";
import Button from "./components/button";

function App() {
  return (
    <div className="flex flex-col w-3/4 mx-auto my-12 items-center">
      <h1>Super cool page</h1>
      <Button onClick={() => console.log("I was clicked")}>
        I am a button
      </Button>
    </div>
  );
}

export default App;

Let's create a simple button component, this will be a small wrapper around a normal button, but will contain some styles. I'm making this component in a components directory inside of src, but you can put the component wherever you want.



// src/components/button.js
import React from "react";

export default function Button({ children, ...buttonProps }) {
  return (
    <button
      className="px-2 py-1 rounded-lg bg-green-400 text-green-800 text-xl font-light uppercase shadow-md hover:shadow-lg"
      {...buttonProps}
    >
      {children}
    </button>
  );
}

If you run yarn start now you should see that PostCSS is processing our styles for us, and then you should see something like this.

Such beauty. It is almost too much to behold!

Checking our app out in production

So our app is looking great now and we are ready to send it off into the world, but first we need to build for production.



yarn build

Now to check our production build, we can use a tool like serve. Either install it globally, yarn global add serve or you can use npx.

If you installed globally you'll use



serve -s build

or if you want to use npx



npx serve -s build

Sweet! Our page looks pretty rad if I do say so myself. Now let's just open up the developer tools in our browser, click on the network tab, refresh the page and see how slim our sleek new CSS is...

Look at the size of the CSS bundle. 350KB... Yikes! Why is it so big!?

Well Tailwind generates classes. A lot of classes. The stylesheet that it generates is over 3000 lines long. But we are only using a fraction of those classes right now so what can we do?

Slimming Our Build

There is a utility called PurgeCSS which will parse any files that match the given file globs for the usage of the selectors in your CSS. If a selector isn't present in any of the matched files, then it rips those styles out of the CSS, ultimately slimming the build.

There is a PostCSS plugin for PurgeCSS so we can just install our new dependency, and add a little bit more set up to postcss.config.js.



yarn add -D @fullhuman/postcss-purgecss

Open up your postcss.config.js file and make some additions. The following set up is taken directly from the Tailwind docs.



// postcss.config.js
const purgecss = require('@fullhuman/postcss-purgecss')({

  // Specify the paths to all of the template files in your project 
  content: [
    './src/**/*.js',
    './public/index.html',
  ],

  // Include any special characters you're using in this regular expression
  defaultExtractor: content => content.match(/[A-Za-z0-9-_:/]+/g) || []
})

module.exports = {
  plugins: [
    require('tailwindcss'),
    require('autoprefixer'),
    ...process.env.NODE_ENV === 'production'
      ? [purgecss]
      : []
  ]
}

The content property in the PurgeCSS plugin takes an array of file globs that it should check for the inclusion of CSS selectors. In a create-react-app project we want it to check all of our React components so we pass ./src/**/*.js which means check any nested folders inside of src for any file with an extension of .js. We also want it to look at our ./public/index.html file because Tailwind uses Normalize, and without having it check the projects HTML page, it will gut a lot of the Normalize rules that we want it to include.

There are some pitfalls with PurgeCSS, like it won't actually render your components to check dynamic class usage, so you want to avoid partial class names in dynamic renders and instead stick to full class names.



import React from 'react'

// DO NOT DO THIS
function Button({ color, children }) {
  return <button className={`text-${color}`}>{children}</button>
}

const App = () => (
  <Button color="red-300">Do not click me</Button>
)

///////////////////////////////////
// Instead do this!

function Button({ color, children }) {
  return <button className={`${color}`}>{children}</button>
}

const App = () => (
  <Button color="text-red-300">Do not click me</Button>
)

The other thing that we need to do is make a slight modification to one of our scripts in package.json. The addition of NODE_ENV=production to our prebuild script will set the environment variable for Webpack which create-react-app uses under the hood, and will trigger the PostCSS cli to use PurgeCSS in the building of our styles.



// package.json
{
  "scripts": {
  //...
    "prebuild": "NODE_ENV=production yarn build:styles"
  }
}

Now let's build for production, serve our app, open up the dev tools and check out our network tab again.



yarn build && serve -s build

Much better!

If you want to further slim the build there is great documentation on how to control the size of Tailwind.

So now you know how to set up Tailwind in your create-react-app projects and how to get some decent production wins with PurgeCSS + PostCSS. Let me know if you any questions in the comments, or if you enjoyed this article.

What is Shadowing in Gatsby Themes?

Matt Hagner — Wed, 24 Jul 2019 02:28:11 +0000

This is the continuation of a series on Gatsby themes. In previous posts we covered how to start a Gatsby site from scratch, how to add a theme, and how to use theme options to customize our website.

We'll be picking up with Shadowing in Gatsby which is a powerful concept that allows you to use themes and customize only the parts that you want in a reliable, ergonomic way.

What is Shadowing?

Shadowing is Gatsby's answer to customizing parts of a theme, without throwing the baby out of the bathwater. It would suck if you needed to re-wire gatsby-theme-blog from scratch if you wanted to change some of the styles, components, or content.

It would also suck to have a giant object with theme options for everything you want a user to be able to override. It would also suck if some theme creator made some component, or style NOT overridable.

By making shadowing an inherent part of how Gatsby works, there is a consistent and simple way to override pretty much anything.

What can you Shadow?

With Gatsby themes you can shadow styles, components, and data requirements (GraphQL queries). Anything that lives in the src directory of a theme is fair game!

How do you Shadow?

Let's quickly change something small like the main color of our blog. I love purple, but you know what's an even better color? Tomato.

To shadow something from a theme we follow a simple convention. Inside of our src folder, we make a folder with the theme name, gatsby-theme-blog, and then we mimic the path to the file in the theme itself but we ignore the src inside of the theme.

So gatsby-theme-blog/src/gatsby-plugin-theme-ui/colors.js becomes src/gatsby-theme-blog/gatsby-plugin-theme-ui/colors.js.

Since we happen to want to change a color, and I happen to know that gatsby-theme-blog/src/gatsby-plugin-theme-ui/colors.js is the exact file that we need to shadow, we need to create some folders, and a new file in our Gatsby website so we can shadow it.

mkdir -p src/gatsby-theme-blog/gatsby-plugin-theme-ui
touch src/gatsby-theme-blog/gatsby-plugin-theme-ui/colors.js

Now pop open your favorite code editor and we are going to open up two files. File 1) node_modules/gatsby-theme-blog/src/gatsby-plugin-theme-ui/colors.js and file 2) src/gatsby-theme-blog/gatsby-plugin-theme-ui/colors.js.

When I'm shadowing, I find it easiest to look at the thing I'm going to shadow, while working on the new file.

Your node_modules/gatsby-theme-blog/src/gatsby-plugin-theme-ui/colors.js file should look something like this:

const purple60 = `#663399`
const purple30 = `#D9BAE8`
const grey90 = `#232129`
const black80 = `#1B1F23`
const white = `#fff`
const lightWhite = `rgba(255, 255, 255, 0.86)`
const opaqueLightYellow = `rgba(255, 229, 100, 0.2)`
const opaqueLightWhite = `hsla(0, 0%, 100%, 0.2)`
const lightGray = `hsla(0, 0%, 0%, 0.2)`

export default {
  text: grey90,
  background: white,
  primary: purple60,
  secondary: black80,
  muted: lightGray,
  highlight: opaqueLightYellow,
  heading: grey90,
  prism: {
    background: `#011627`,
    comment: `#809393`,
    string: `#addb67`,
    var: `#d6deeb`,
    number: `#f78c6c`,
    constant: `#82aaff`,
    punctuation: `#c792ea`,
    className: `#ffc98b`,
    tag: `#ffa7c4`,
    boolean: `#ff5874`,
    property: `#80cbc4`,
    namespace: `#b2ccd6`,
    highlight: `hsla(207, 95%, 15%, 1)`,
  },
  modes: {
    dark: {
      text: lightWhite,
      background: grey90,
      primary: purple30,
      secondary: lightWhite,
      muted: opaqueLightWhite,
      highlight: purple60,
      heading: white,
    },
  },
}

The color that we want to change is the primary key in the object.

export default {
  text: gray90,
  background: white,
  primary: purple60,
  //...
}

So what can we learn from this file? The first thing to take away is that we should have a default export in our shadowed colors.js file. The second is that, unless we want to change a bunch of these values, we will need some way to merge the gatsby-theme-blog colors, with our colors and just override the ones that we want to.

Before we get to figuring out how to merge our colors object, let's make an export default and set the primary key to 'tomato'.

export default {
  primary: 'tomato',
}

Now the cool part...

import colors from 'gatsby-theme-blog/src/gatsby-plugin-theme-ui/colors'

export default {
  ...colors,
  primary: 'tomato',
  modes: {
    dark: {
      ...colors.modes.dark,
      primary: '#ff755e'
    }
  }
}

We can import the thing we are shadowing and use whatever JavaScript method we want to merge, and override whatever we want. It's that easy. At least updating styles is that easy.

Why does Shadowing work this way?

When you are using a theme Gatsby first tries to resolve within your own projects src folder, looking in src/{theme-name}/{any-sub-dirs}/{file}, if it doesn't see anything there, it resolves to node_modules/{theme-name}/src/{any-sub-dirs}/{file}.

When building a theme you don't have to do anything special to allow shadowing. It just works. When you're consuming a theme you can follow these conventions to shadow whatever you need to.

BONUS

Want an even easier way to do partial/deep updates of an object in JavaScript? There's a really cool library called immer that is particularly good at this.

Just install immer to the project, import it into our file and let the magic happen.

import produce from 'immer'
import colors from 'gatsby-theme-blog/src/gatsby-plugin-theme-ui/colors'

export default produce(colors, draft => {
  draft.primary = 'tomato'
  draft.modes.dark.primary = '#ff755e'
})

Conclusion

Shadowing is a concept in Gatsby that allows us to override and compose styles, components, and data from a Gatsby theme. It follows a simple convention of path resolution to allow shadowing. Anything in a theme's src/ folder is open to shadowing.

Next Up

Next time we will dive into shadowing gatsby-theme-blog and making it our own by shadowing styles and components.

Using Gatsby Theme Options Part 2

Matt Hagner — Tue, 16 Jul 2019 13:20:03 +0000

Previously in the series

This is the third post in a series about getting started with Gatsby themes where we learn about themes progressively. In the first blog post, we set up a Gatsby website from scratch, and added the gatsby-theme-blog, which takes some Markdown or Mdx content in a specified folder, transforms it into pages on our website, and gives us some nice base components and styles.

In the second post, we discussed what options are in themes, how to customize the theme with the options available, and where to look inside of the theme to find what options are available as well as how those options are used.

If you haven't read from the beginning of the series Using Your First Gatsby Theme, you might want to before continuing.

What are we going to discuss today?

In this post, we are going to customize our Gatsby website by changing some of the options available to us from gatsby-theme-blog.

In the next post we'll discuss what shadowing is as a concept in Gatsby, and how to find the things that can be shadowed in a theme.

If you'd like to see the completed code for this section, check the branch Using Gatsby Theme Options Pt 2 on Github.

Changing the base URL of our blog

Right now our blog index, the page rendering a list of our blog posts, is rendering at our root path "/", but what if we want to add a blog to an existing website, or what if we want to make something else our home page?

Luckily that's pretty easy to change.

If you remember, the gatsby-theme-blog has a few options that we can change. One of them is a property called basePath. This basePath determines the base URL for our blog content. The default is /, but let's go ahead and change that to /blog.

Open up gatsby-config.js

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-theme-blog',
      options: {
        basePath: '/blog',
      }
    }
  ]
}

What this will do is make the blog index render at '/blog' and make the blog posts render at '/blog/:slug' where :slug is replaced with the slugified version of your title.

It's pretty common to call it slugifying when you set all characters to lowercase and change any characters that don't fall between a-z or 0-9 into "-".

Last time we changed our src/pages/index.js page to /src/pages/_index.js so that Gatsby wouldn't try to render our index page in place of our blog index. Now that we have the blog rendering at a different path, let's change the filename back to index.js.

mv src/pages/_index.js src/pages/index.js

We'll also want to add a navigation component so that we can get to our home and blog page.

Let's first make a components directory inside of the src directory. And then we'll make two new components, layout, and navigation.

mkdir src/components
touch src/components/{layout,navigation}.js

In my experience with Gatsby I always need a generic page layout, or maybe a few different layouts for different types of pages. You will sometimes see these living in src/templates or sometimes src/components. Either is perfectly fine, but I try to stick with keeping layouts that affect markup and styles in src/components, and use src/templates only for tying the data requirements for programmatic pages to a visual component or set of visual components.

// src/pages/index.js
import React from 'react'
import Layout from '../components/layout'

export default function HomePage() {
  return (
    <Layout>
      <h1>Welcome!</h1>
      <p>
        Hello, from Gatsby{" "}
        <span role="img" aria-label="hand emoji waving hello">
          👋
        </span>
      </p>
    </Layout>
  )
}

/////////////////////////////////////////
// src/components/layout.js

import React from 'react'
import Navigation from './navigation'

export default function Layout({ children }) {
  return (
    <>
     <Navigation />
      <main>
       {children}
      </main>
    </>
  )
}

/////////////////////////////////////////
// src/components/navigation.js

import React from 'react'
import { Link } from 'gatsby'

export default function Navigation() {
  return (
    <nav>
      <ul>
        <li><Link to="/">Home</Link></li>
        <li><Link to="/blog">Blog</Link></li>
      </ul>
    </nav>
  )
}

There are a few things to note when we start our Gatsby site up 1) it's really ugly, and 2) the navigation is on the home page but not the blog page :( bummer.

To fix problem one just use your favorite styling method whether that's CSS-in-JS, CSS modules, Sass, etc. I won't be touching the general styles because that is beyond the scope of this series. If you're interested in learning about different ways to style your Gatsby website let me know in the comments and I'll write an article.

To fix problem two we are going to have to learn how to shadow components. We'll discuss what shadowing is in the next post.

Next up

If you found this post useful and want to see more from this series leave a reaction or comment. I'm trying to find the right length and depth per article so please let me know if you think this length is too short

In the next post, we'll learn about what shadowing is, why it's so powerful, and how Gatsby resolves shadowed content.

Using Gatsby Theme Options

Matt Hagner — Sun, 14 Jul 2019 01:09:17 +0000

This is the second post in a series about getting started with Gatsby themes where we learn about themes progressively. In the first blog post we set up a Gatsby website from scratch, and added gatsby-theme-blog, which takes some Markdown or Mdx content in a specified folder, transforms them into pages on our website, and gives some nice base components and styles.

If you haven't read Using Your First Gatsby Theme, you might want to do that before continuing on.

In this post we are going to dive deeper into the options that gatsby-theme-blog gives us to customize our experience.

In future posts we will discuss what shadowing is, and how to shadow components, styles, and data.

What are the options?

If we take a look at the documentation for the gatsby-theme-blog package, there are four options available to us.

basePath which defaults to "/". It is the url for the blog index page, and root url for all blog posts.
contentPath defaults to /content/posts. It is the location of the .md/.mdx files you want to be transformed into blog posts.
assetPath defaults to /content/assets. It is the location of your avatar (picture) for the bio component.
mdx which defaults to true. This determines whether gatsby-theme-blog should configure mdx for you, or if you will handle it yourself. If you have gatsby-mdx installed and configured for other pages, you can set this to false.

How do we override them?

We can override these defaults in the gatsby-config.js of our Gatsby website. When you don't need to change any of the options in a theme your config might look like this:

// gatsby-config.js
module.exports = {
  plugins: [
    'gatsby-theme-blog'
  ]
}

If we wanted to change one or more of the options we would use the longhand syntax for a plugin/theme.

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-theme-blog',
      options: {
        basePath: '/blog'
      }
    }
  ]
}

You might need to consult the documentation for the themes that you are using to see if there are any options that you must set, or if all are optional.

Where are the options used?

If we go to the folder of our Gatbsy website and open up node_modules/gatsby-theme-blog/gatsby-config.js in our favorite editor, we will see something like this.

// node_modules/gatsby-theme-blog/gatsby-config.js
module.exports = options => {
  const { mdx = true } = options

  return {
    siteMetadata: {
      title: `Blog Title Placeholder`,
      author: `Name Placeholder`,
      description: `Description placeholder`,
      social: [
        {
          name: `twitter`,
          url: `https://twitter.com/gatsbyjs`,
        },
        {
          name: `github`,
          url: `https://github.com/gatsbyjs`,
        },
      ],
    },
    plugins: [
      mdx && {
        resolve: `gatsby-plugin-mdx`,
        options: {
          extensions: [`.mdx`, `.md`],
          gatsbyRemarkPlugins: [
            {
              resolve: `gatsby-remark-images`,
              options: {
                // should this be configurable by the end-user?
                maxWidth: 1380,
                linkImagesToOriginal: false,
              },
            },
            { resolve: `gatsby-remark-copy-linked-files` },
            { resolve: `gatsby-remark-numbered-footnotes` },
            { resolve: `gatsby-remark-smartypants` },
          ],
          remarkPlugins: [require(`remark-slug`)],
        },
      },
      {
        resolve: `gatsby-source-filesystem`,
        options: {
          path: options.contentPath || `content/posts`,
          name: options.contentPath || `content/posts`,
        },
      },
      {
        resolve: `gatsby-source-filesystem`,
        options: {
          path: options.assetPath || `content/assets`,
          name: options.assetPath || `content/assets`,
        },
      },
    // ...more config
  }
}

The most important thing to note is that the gatsby-config.js file is a
function that takes an object, here it's called options, as an argument and returns a config object. If we look carefully we will see three of the four options for gatsby-theme-blog being used at different spots in the config.

mdx which is used to determine whether or not to configure gatsby-mdx for us, along with some helpful plugins for Markdown/Mdx.

contentPath which is used inside of a gatsby-source-filesystem config
determining where on our filesystem to look for the posts, and what to call them when we are querying for them with GraphQL.

assetPath which is also used inside of a gatsby-source-filesystem config, but this time determining where on our filesystem to look for our assets, and what to call them when we are querying for them with GraphQL.

So we've located three of the four options. Where is the fourth one being used?

For this one we are going to look inside node_modules/gatsby-theme-blog/gatsby-node.js.

// node_modules/gatsby-theme-blog/gatsby-node.js
// Ensure that content directories exist at site-level
exports.onPreBootstrap = ({ store }, themeOptions) => {
  const { program } = store.getState()

  basePath = themeOptions.basePath || `/`
  contentPath = themeOptions.contentPath || `content/posts`
  assetPath = themeOptions.assetPath || `content/assets`

  const dirs = [
    path.join(program.directory, contentPath),
    path.join(program.directory, assetPath),
  ]

  dirs.forEach(dir => {
    debug(`Initializing ${dir} directory`)
    if (!fs.existsSync(dir)) {
      mkdirp.sync(dir)
    }
  })
}

You don't need to understand what's happening in this whole file, in fact that's the beauty of Gatsby, Gatsby plugins, and now Gatsby Themes, but if we look at the onPreBootstrap function we can see that the second argument is an object with the same options available to it as in the gatsby-config.js file.

When a Gatsby website with this theme is started up, Gatsby will check for these paths (contentPath, and assetPath) existence. If they don't exist, Gatsby will use the mkdirp package to make sure that they are created.

The next place we need to look is the createPages function in the same file. This time, we are taking advantage of the global basePath variable that we set in the onPreBootstrap function. The relevant part is here:

// node_modules/gatsby-theme-blog/gatsby-node.js
// inside of the exports.createPages function
  createPage({
    path: basePath,
    component: PostsTemplate,
    context: {
      posts,
      siteTitle,
      socialLinks,
    },
  })

The important thing to understand is that whatever our basePath is, that will be the path that our PostsTemplate gets rendered to with the data that is passed in via the context object.

That's a lot of stuff to take in but let's quickly recap:

The theme documentation should list what options are available, and what the defaults are
You can use the longhand plugin syntax that is standard in Gatsby to override the theme defaults if/when needed
You can also check the gatsby-config.js of the theme, and the gatsby-node.js for more context on how/where those options are being used if the documentation leaves more to be desired.

I hope this post was helpful. Next time we'll be diving into shadowing by going over what the concept of shadowing is in Gatsby.

Using Your First Gatsby Theme

Matt Hagner — Sun, 07 Jul 2019 01:23:44 +0000

Gatsby just announced the stable release of themes, and along with it released a bevy of themes-related content. This post will go over what a theme is, why they might be useful to you, and how to use your first theme. In later posts I'll dive into topics like component shadowing, and maybe even authoring your own theme.

If you'd like to dive right into the deep end Jason Lengstorf released a free egghead course on Gatsby themes that is superb.

What are themes?

The name theme might invoke the assumption that they only relate to visual content, however Gatsby themes are way more than that. They can include some default configuration, setting up transformers, plugins, and even other child themes. Themes can also include visual styles and components.

Themes are configurable, overridable, and best of all, composable.

Why are themes useful?

If you've used Gatsby in the past, you might have used a starter to bootstrap your website. Starters were a great stepping stone before themes. They allowed you to kick off a Gatsby site that was configured with some additional functionality out of the box, like say supporting Mdx, or maybe using an external service like Shopify.

However, if you ran into the case of wanting to quickly start a website that supported both Mdx AND Shopify you had to find a starter with both configured, use one of the starters and figure out how to get the other functionality set up, or configure everything from scratch.

Themes change this. Instead of starting with a this or that, we can easily make a this AND that. Remember, themes are configurable, overridable, and composable.

Let's get started

We're going to start off simple. Let's set up a Gatsby website from scratch, and then use gatsby-theme-blog to quickly bootstrap the basic functionality of a blog.

If you want to see the full code check out the Github repo.

Set up the directory

First we need to make a directory for our Gatsby website, and then we need to initialize it.

mkdir first-gatsby-theme
cd first-gatsby-theme
yarn init -y

I'm using yarn, but feel free to use npm if you'd like.

Installing Our Dependencies

We could use a starter by using the gatsby new <STARTER> command, but let's set one up manually. It's surprisingly easy to do.

We only need react, react-dom, and gatsby to get started. So let's install those. After that, let's open up the package.json file in the root directory and add some scripts for convenience.

yarn add react react-dom gatsby

// package.json
{
  "name": "first-gatsby-theme",
  "version": "1.0.0",
  "license": "MIT",
  "dependencies": {
    "react": "...",
    "react-dom": "...",
    "gatsby": "...",
  },
  "scripts": {
    "build": "gatsby build",
    "start": "gatsby develop",
    "clean": "gatsby clean"
  }
}

The ... are just placeholders. Your package.json file will have the specific versions you have installed.

Check that Gatsby is working

To see all of our hard work paid off, let's make some content and let Gatsby work its magic.

We need to make a directory at src/pages. By convention this is where Gatsby will look for content to transform into pages on the website, and handles the routing for us.

mkdir -p src/pages
touch src/pages/index.js

mkdir -p creates all missing directories in the path provided

src/pages/index.js will be mapped to the root path "/" of our website.

// src/pages/index.js

import React from 'react'

export default function HomePage() {
  return (
    <>
      <h1>Welcome</h1>
      <p>Hello, from Gatsby <span role="img" aria-label="hand emoji waving hello">👋</span></p>
    </>
  )
}

Now to start up the Gatsby website all you need to do is run.

yarn start

You should see something that looks like this.

Very exciting, I know.

Installing the theme

Now that we know we have Gatsby working, let's install a theme. Everyone says that they want to have a blog, but getting started is hard. The good news is that themes makes it so easy to get started that you won't have any excuses.

yarn add gatsby-theme-blog

In the root of your project make a gatsby-config.js file.

touch gatsby-config.js

And add the following

module.exports = {
  plugins: [
    'gatsby-theme-blog'
  ]
}

Before the stable release of themes, your themes used to live under an additional property called __experimentalThemes, but now that they're stable, they're just like plugins!

If you tried to start your Gatsby website up at the moment you'd get some errors :(. Let's figure out why in the next two sections.

Exploring the theme options

Right now there isn't a Github repo for gatsby-theme-blog, but if you look at the npm page you can see a section called Usage.

Most Gatsby plugins and themes will have options that you can set. For gatsby-theme-blog there are four options and defaults for each of them, meaning we can not pass any options in and the theme will still work.

That being said, it has some expectations. Right now gatsby-theme-blog expects some blog posts in the form of either Markdown or MDX in the content/posts directory, and an image with the title of avatar in the content/assets directory.

The errors you get from not having either of these are kind of cryptic which is a bit of a bummer.

For now we are going to leave the options set to the defaults. If you wanted to override any you would change your gatsby-config.js.

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-theme-blog',
      options: {
        contentPath: 'content/posts', // the file path to your blog posts
        basePath: '/', // the url for the root of your blog
        assetPath: 'content/assets', // the file path to your assets folder
        mdx: true, // whether or not to configure mdx for you
      }
    }
  ]
}

These are the default values, but to change any of them, set the value you would like in the options object.

Add Content

So now that we know why our Gatsby website is failing after adding this theme, let's use the default options as a guide for what we need to do to get our website working again.

First we need to make the necessary folders. In the root of the project we're going to create content, content/posts, and content/assets directories.

mkdir -p content/{posts,assets}

the {} here is called brace expansion and is equivalent to running mkdir -p content/posts and mkdir -p content/assets, just in a shorter way.

Now that we have our folders in place we need to make a blog post, and add an avatar.

Make a file called hello-world.md, inside of your content/posts directory and add whatever content you'd like.

---
title: "Hello, World"
---

The worlds greatest blog post!

Next, save a picture of yourself named avatar in content/assets.

The third thing we need to do is temporarily remove our src/pages/index.js page, because gatsby-theme-blog defaults to making the root of the blog the "/" root path.

mv src/pages/index.js src/pages/_index.js

If you run yarn start now, everything should work and you'll see something like this:

Site/Author Info

The other thing that gatsby-theme-blog does is look in our gatsby-config.js for some site metadata.

Pop open your gatsby-config.js one last time and add your information in.

module.exports = {
  siteMetadata: {
    title: "Awesome Blog", // Enter the title of your blog here
    author: "Matt Hagner", // Change this to your name
    description: "A really cool blog",
    social: [
      {
        name: 'twitter',
        url: 'twitter.com/_hagnerd',
      },
      {
        name: 'github',
        url: 'github.com/hagnerd',
      },
    ]
  },
  plugins: [
    'gatsby-theme-blog',
  ]
}

Hopefully that wasn't too painful and helped highlight just how quick it is to install and set up a Gatsby theme. The best part is that you can install more themes, as needed and it won't require you to fundamentally change how your website is structured.

Next Up

The quick set up for our blog was great, but what if we want to change the styles? Or how some of the default components are rendered? To do that we'll use a feature called shadowing.

I'll update with a link to the post when it's finished.

Where Did All My Methods Go? Modules in ReasonML

Matt Hagner — Sun, 30 Jun 2019 18:22:50 +0000

Coming from JavaScript to ReasonML there are a lot of barriers. While the syntax may look friendly at first, and the type inference is amazing requiring very little effort from you to massage it, there are a lot of symbols, and a huge mental shift needs to take place.

To help others coming from non-functional languages, and JavaScript
specifically, I want to start sharing some of the things that tripped me up when I was learning ReasonML.

The community is one of the best around and someone will always help you no matter how silly you think your question is, but there isn't a ton of content surrounding ReasonML online. Join the discord, and don't be afraid to post on the forum.

Functional programming languages tend to structure their code differently than non-functional languages. Whether or not you consider JavaScript to be an object oriented language, it still has some form of inheritance using the prototype chain, and you call methods directly on the instance of the data structure.

The JavaScript Way

An example. In JavaScript you can create an array literal like so:

const myFriends = ["Me", "Myself", "I"];

And you can use the Array methods by using the dot notation on the instance of the data structure.

const myFriends = ["Me", "Myself", "I"];

const shoutingFriends = myFriends.map(friend => friend.toUpperCase());

Under the Hood

In JavaScript when you declare a new array literal you are creating a new instance of the Array pseudo-class.

const myFriends = new Array("Me", "Myself", "I");

A naive implementation of an Array in JavaScript using pseudo-classes might look like this:

function MyArray() {
  // pretend I didn't use an actual Array in my definition
  this.value = Array.from(arguments)
  this.length = arguments.length
}

MyArray.prototype.forEach = function(cb) {
  for (let i = 0; i < this.value.length; i++) {
    cb(this.value[i], i, this.value);
  }  
}

MyArray.prototype.map = function(cb) {
  let __internal = [];

  this.forEach(function(element, index, array) {
    __internal.push(cb(element, index, array));
  });

  return __internal;
}

const myFriends = new MyArray("Me", "Myself", "I");
const shoutingFriends = myFriends.map(friend => friend.toUpperCase());

You might be used to seeing classes instead of pseudo-classes, but under the hood JavaScript classes are just syntatic sugar that results in the same thing.

Important to note that our methods have an implicit dependency on this (the instance itself). We aren't passing an array into the method. The implicit dependency on this is what allows the dot notation myFriends.map....

Our instance of MyArray doesn't actually copy over forEach, or map because that would be extremely inefficient. If our program has tens-of-thousands of arrays it would be unnecessary to copy EVERY method to each instance of the data structure. Instead JavaScript has this thing called the prototype.

So when we use myFriends.map... the engine goes "Hmmm.... 🤔 myFriends doesn't seem to have a function called map on its prototype. Perhaps its proto does." and then it checks MyArray, because when we create an instance of a (pseudo-)class JavaScript adds some information to our instance so later it knows who to inherit functions from.

Then it sees that "Ahhh. Yes! MyArray does a have function on its prototype called map", and then it uses that map function for our operation.

All of this rambling is to show you how data structures and methods are
tightly coupled in JavaScript. To map an array we use the instance of the array, and chain a function onto it like so [1,2,3].map(n => n + 1).

When you learn this as the norm, you think, "Well yeah, duh. How else would you do it?".

The ReasonML Way

In functional programming languages data structures store data. That's it. How do you do operate on data structures then? In ReasonML we place collections of functions that operate on a type into Modules. A module might know how to operate on one type only, like an Array for example.

The functions have an explicit dependency of an Array.

In ReasonML the Array module contains most functions that know how to operate on the array data structure. What are the benefits of modules? They're self-contained. They don't have to be copied or have pointers created to their 'owners'. They also avoid notions of 'this/self' or the instance of the data structure at all.

They are pure functions that take explicit arguments and return consistent results.

An Example

In ReasonML Array.map is a function that takes two arguments:

A function that takes whatever the type of data that is contained inside of the array (in the following example it takes a string) and does something to transform each element returning either the same, or a different type (in following example it returns a string).
The actual Array we want to operate on.

let myFriends = [| "Me", "Myself", "I" |];
let shoutingFriends = Array.map(friend => String.uppercase(friend), myFriends);

This explicit need for the Array to be passed in might still seem like an odd choice, especially if you're used to taking advantage of method chaining in JavaScript or other object oriented languages.

const myArray = [1, 2, 3, 4, 5, 6];
const res = myArray
  .map(n => n * 3)
  .filter(n => n % 2 === 0)
  .reduce((acc, n) => acc + n, 0);
// => 36

However, you can achieve the same thing in ReasonML in a few different ways.

(I am using a List here instead of an Array for reasons we'll explore in another post, but for our purposes squint and pretend it's an array).

let myArray = [1, 2, 3, 4, 5, 6];
let res = myArray
  |> List.map(n => n * 3)
  |> List.filter(n => n mod 2 === 0)
  |> List.fold_left((acc, n) => acc + n, 0);
/* => 36 */

Alternatively if you are using Bucklescript you can use Belt.

let myArray = [| 1, 2, 3, 4, 5, 6 |];
let res = myArray
  -> Belt.Array.map(n => n * 3)
  -> Belt.Array.keep(n => n mod 2 === 0)
  -> Belt.Array.reduce((acc, n) => acc + n, 0);
/* => 36 */

Or the Js.Array module...

let myArray = [| 1, 2, 3, 4, 5, 6 |];
let res = myArray
  |> Js.Array.map(n => n * 3)
  |> Js.Array.filter(n => n mod 2 === 0)
  |> Js.Array.reduce((acc, n) => acc + n, 0);
/* => 36 */

I don't want to dive into what the |> and -> operators are in this post. Just know that the |> and -> operators, in addition to currying, can help you achieve this same idea of method chaining. You're taking the result from one function and piping it into the next function.

So in ReasonML methods move from being available on the instance of a data structure, to being contained within a dedicated module. This allows them to be pure functions that require you to explicitly pass in the data structure you want to operate on.

Some Additional Info

If you're comfortable reading type signatures, the following links contain the type definitions for the Array and List modules.

Array module
Belt Array module
List module
Belt List module

What's next?

ReasonML is still evolving so there are often many ways to skin a cat, and there are often good reasons when to choose one over the other.

In future posts I'm going to explore some of the different modules included in the standard library in ReasonML, as well as Belt and how they relate to JavaScript.

I Wrote This Article In The Terminal

Matt Hagner — Thu, 13 Jun 2019 22:03:10 +0000

This article was written with my new tool devto, a CLI for creating new articles, and posting them to Dev.to. It's dead simple, and probably a little rough around the edges.

Prior Art

This tool was heavily inspired by Tim Deschryver who wrote this article about a VS Code extension called New Blog Post. If you use VS Code, check it out!

If you're interested in using the CLI app you can install it globally at @hagnerd/devto, or run it with npx @hagnerd/devto.

Once installed it will be globally available with devto new.

The following commands are available:

devto new - creates a new article with frontmatter.
devto publish - pushes the article up to your dev.to account*
devto dashboard - just a quick alias to open dev.to/dashboard in the browser. Great if you want to push a draft up, and make changes or preview it.
devto reset - deletes your global ~/.devto file (which stores your API key)

* I haven't tested it with orgs so if someone that is part of an org tries it
out and the cli doesn't behave correctly, let me know!

npm link
Github link

Getting up and running with Reason, React, and Parcel

Matt Hagner — Tue, 19 Feb 2019 04:08:21 +0000

UPDATED: 4/23/2019

Recently the Reason React project released new bindings. It uses a new version of "react-jsx", and utilizes the React Hooks API instead of the old record based API.

This means that if you have experience with hooks, you'll feel pretty much right at home with Reason React, with some small differences.

With the rise of TypeScript on the front end, I think there will be an increased willingness to learn and utilize typed, compile-to-javascript languages. One strong contender for me is Reason.

You may have heard about Reason and thought about learning it, but it's hard to give up the JavaScript tools you already know and love. The good news is that Bucklescript and tools like Parcel make Reason a breeze to work with.

The following will show you how to set up a Reason React project with Parcel, but teaching you Reason, or how Reason React works compared to React in JavaScript are outside of the scope of this article. If you'd like to learn more about those things, let me know in the comments and I'll gladly write more.

Quick Background

What is Reason?

Reason is a special syntax that will look extremely familiar to JavaScript programmers, that uses OCaml under the hood.

Why does Reason use OCaml under the hood?

Facebook has been using OCaml for a long time to write some of their internal tools (Flow is written in OCaml). OCaml is a fast, mature language that has great type inference, strong type safety, and can compile to many different targets including JavaScript, and Native.

What is Bucklescript?

Bucklescript is a compiler that takes OCaml (or Reason), and turns it into highly optimized, and surprisingly readable JavaScript.

What will we be using today?

The set up we are using will use Reason as the language of our code, reason-react as the front-end framework, Bucklescript for compiling our Reason code to JavaScript, and Parcel for bundling everything up.

Expectations

To get the most out this, you'll want to be comfortable with React.

Initialization

The first we are going to do is make a new folder for our project, and change into the directory.

mkdir reason-parcel
cd reason-parcel

Then we are going to initialize using either npm, or yarn, and install all of our dependencies.

To use the new Reason React bindings you'll want to make sure that you are using bs-platform ^5.0.0, and reason-react ^7.0.0.

yarn init -y 
yarn add -D parcel-bundler bs-platform bsb-js
yarn add react react-dom reason-react

Scripts

Now open up your package.json file, and we are going to add a start script. Add the following to the bottom of your package.json

{
    "scripts": {
        "start": "parcel src/index.html"
    }
}

Set up index.html

Let's make a directory called src. We need to make an index.html file inside of src to match the start script we added to the package.json. While we're at it, we might as well make the file where our Reason code will live.

mkdir src
touch src/index.html
touch src/Main.re

You can use whatever HTML boilerplate you'd like. I highly recommend emmet, and if you use VSCode it's already available. Or you can copy the following:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title></title>
</head>
<body>

</body>
</html>

Inside the <body> tag of index.html add:

  <div id="app"></div>
  <script src="./Main.re"></script>

There are two important things to note:

The id of the div is "app". This will be used later inside of our Main.re file to render our app.
The src property on our script element coincides to the name of the file we just created. Parcel is smart enough to see this src, and know that it needs to process the Reason file, and replace the src property with the outputted JavaScript file path.

Set up bsconfig.json

In the root of your project make a file called bsconfig.json.

touch bsconfig.json

Bucklescript will read from this file for configuration. If you want to read more about all of the available options for the config file, Bucklescript has great documentation.

Copy the following config into bsconfig.json

{
    "name": "reason-parcel",
    "reason": {
        "react-jsx": 3
    },
    "version": "0.1.0",
    "sources": [{
        "dir": "src",
        "subdirs": true
    }],
    "package-specs": {
        "module": "commonjs",
        "in-source": true
    },
    "suffix": ".bs.js",
    "bs-dependencies": ["reason-react"],
    "refmt": 3
}

Let's go through some of the interesting properties:

reason
- reason-react: Is set to 3 to allow the new JSX features.
sources
- dir: Is set to the src folder we made earlier.
- subdirs: Is true because this tells Bucklescript to recursively check within our src folder for Reason files.
package-specs
- module: commonjs is the default 👍 which is good enough for us.
- in-source: Will make our outputted JavaScript files appear next to their Reason counterparts.
bs-dependencies: This is an array of the Reason specific libraries you depend on. Right now we are only using reason-react, but you could use component libraries, styling libraries, etc.
refmt: should be set to 3 for the ReasonV3 syntax.

Let's Finally Write Some Reason

Now with all of that out of the way, let's write some Reason code, and view it in the browser!

Open up src/Main.re and copy the following exactly. Semi-colons, double-quotes, and all. We'll run through exactly what is happening shortly.


module HelloWorld = {
   [@react.component]
    let make = () => <h1>{React.string("Hello, World!")}</h1>
};

ReactDOMRe.renderToElementWithId(<HelloWorld />, "app");

Now save the file, and run yarn start or npm run start, and open up localhost:1234/

Alright so there's a few things that are probably familiar, and a few things that are probably weird.

The Familiar

Rendering to element with a specific id:

ReactDOMRe.renderToElementWithId(<HelloWorld />, "app");

That should look pretty familiar to you if you've written React before. It's essentially doing the same as:

ReactDOM.render(<HelloWorld/>, document.getElementById("app"));

JSX

For the most part, JSX in Reason is the exact same. There are some small caveats to HTML attributes that name-clash with Reason reserved words like the type property on input elements becomes type_.

The Weird

What is with the `module` declaration?


module HelloWorld = {
};

The full explanation goes a little deeper than the scope of this article, but in Reason a file is automatically a module.

To create components in Reason React you need to either declare each new component in a new module, or in a new file. By wrapping our component in module HelloWorld ={}; it allows us to use the JSX element <HelloWorld />.

What is this [@react.component]?

This is the recommended way to make a new Reason React component. It does some stuff for us behind the scenes which makes our lives easier, but if you want to learn how to manually create your own components without it, check out the new page on components in the Reason React documentation.

What is the `make` function?

let make = () => <h1>{React.string("Hello from Reason")}</h1>

Similar to how in React class components React looks for a render method, in a Reason React module, Reason React expects a make function. This make function will take all of the props as an argument, and simply return some JSX.

Is that really what I have to do to make strings?

React.string("Hello, from Reason")

Yes. Yes it is. At least that it is how you have to make strings that are valid Reason React elements. Stay tuned for the next section for some tips to make strings in Reason React less painful.

Let's Refactor a Little

First let's pull out our component and put it in its own file.

touch src/HelloWorld.re

Then we can copy and paste the HelloWorld module, but this time because it's in its own file so we don't need to wrap it in a module.

Inside of HelloWorld.re

let s = React.string;

[@react.component]
let make = () => <h1>{s("Hello, from Reason")}</h1>;

I also made it easier to call React.string by assigning it to a short variable, s. This technique is something you'll see quite frequently in Reason React code.

Now let's go back to our Main.re file and delete everything besides the last line.

Main.re

ReactDOMRe.renderToElementWithId(<HelloWorld />, "app");

Notice how we didn't have to explicitly import HelloWorld into Main.re? This will seem extremely weird at first, but because of how OCaml's module system works, all file-level modules are globally available under the file name.

So in Main.re we have access to the HelloWorld module. By using it in our JSX Reason React knows to call the module's make function.

Now you have all of the pieces necessary for starting a Reason React project with Parcel. Feel free to play around with things, and let me know what questions you have regarding Reason, Reason React, or Parcel.

P.S. I wouldn't feel right without quickly mentioning bsb as an alternative for bootstrapping Reason React projects:

bsb -theme react -init <PROJECT_NAME>

To use the bsb command you will have to install it globally

yarn global add bsb

Or use npx (if you're using npm 5.2 or newer you already have it installed) to run the command

npx bsb -theme react -init <PROJECT_NAME>

Forem: Matt Hagner

A Primer on Testing & TDD

What is test-driven development?

Why do I write tests?

What should we test?

Unit vs Integration vs End to End

Unit Tests

Integration Tests

End to End Tests

Property-Based Tests

Static Tests aka Static Analysis

Conclusion

Setting up Tailwind With create-react-app

What is Tailwind?

What does it look like?

Why would you use it?

How do we set up create-react-app to use Tailwind?

Building our React component

Such beauty. It is almost too much to behold!

Checking our app out in production

Slimming Our Build

What is Shadowing in Gatsby Themes?

What is Shadowing?

What can you Shadow?

How do you Shadow?

Why does Shadowing work this way?

BONUS

Conclusion

Next Up

Using Gatsby Theme Options Part 2

Previously in the series

What are we going to discuss today?

Changing the base URL of our blog

Next up

Using Gatsby Theme Options

What are the options?

How do we override them?

Where are the options used?

Using Your First Gatsby Theme

What are themes?

Why are themes useful?

Let's get started

Set up the directory

Installing Our Dependencies

Check that Gatsby is working

Installing the theme

Exploring the theme options

Add Content

Site/Author Info

Next Up

Where Did All My Methods Go? Modules in ReasonML

The JavaScript Way

Under the Hood

The ReasonML Way

An Example

Some Additional Info

What's next?

I Wrote This Article In The Terminal

Prior Art

Getting up and running with Reason, React, and Parcel

UPDATED: 4/23/2019

Quick Background

What is Reason?

Why does Reason use OCaml under the hood?

What is Bucklescript?

What will we be using today?

Expectations

Initialization

Scripts

Set up index.html

Set up bsconfig.json

Let's Finally Write Some Reason

The Familiar

Rendering to element with a specific id:

JSX

The Weird

What is with the module declaration?

What is this [@react.component]?

What is the make function?

Is that really what I have to do to make strings?

What is with the `module` declaration?

What is the `make` function?