Forem: Kepler Sticka-Jones

Carraway: A Tool to Simplify Gatsby

Kepler Sticka-Jones — Sun, 10 Nov 2019 01:38:48 +0000

Gatsby is an incredible tool. It allows web developers to build fast, modular, and powerful websites with minimal effort. However, like all great software, there is room for improvement. This is why I've created Carraway.

Gatsby is Great, Why do I Need Carraway?

Let's take a step back here. Gatsby is a JavaScript framework named after the titular character of F. Scott Fitzgerald's The Great Gatsby. This American classic follows narrator Nick Carraway as he recounts his experiences of the summer he lived next to the great Jay Gatsby. Throughout the book, Gatsby demonstrates his great generosity and power in the New York of the 1920s, however, to achieve his ultimate goal he needs the help of his neighbor Nick.

Nick Carraway simplifies Jay Gatsby's lifelong pursuit. Carraway helps Gatsby.

This relationship is what inspires my new tool, Carraway. While building a series of websites built in Gatsby (my personal website, the vanity website for my surname, the AtomBuild website, and the AtomLinter website) I became very interested in using Gatsby's Theme functionality to abstract away the code portions of my websites and making the repositories for my sites only responsible for the site's content and configuration. The result of doing this using only Gatsby is a repo that contains no source code files aside from the gatsby-config.js required by Gatsby. This is where Carraway comes in.

Carraway allows us to configure Gatsby using a JSON object in either gatsby.config.json or package.json (under the "gatsby" key.) This allows us to create Gatsby sites with no source files, letting us focus on the content of our sites.

How Do I Use Carraway?

Much like the character, it's named after, Carraway is rather simple. Using Carraway in your Gatsby project is a simple three-step process: installing the package, moving your configuration, and using Carraway to run Gatsby.

Installation

Carraway is available on NPM. To install it run the following in your site directory:

npm install carraway

Or, if you are using Yarn:

yarn add carraway

Configuration

Next, you'll need to move your site's Gatsby config to either gatsby.config.json or package.json (under the "gatsby" key) as a JSON object. You should have either a gatsby.config.json with the following structure:

{
  "siteMetadata": {},
  "plugins": []
}

Or the following structure in your package.json:

{
  "gatsby": {
    "siteMetadata": {},
    "plugins": []
  }
}

Usage

After installation and configuration, you're ready to use Carraway! Carraway will now handle your Gatsby configuration and will invoke Gatsby for you. If you were using NPM scripts to run Gatsby in your project, update your scripts to match this. You should go from a scripts section like the following:

{
  "scripts": {
    "build": "gatsby build",
    "develop": "gatsby develop"
  }
}

To the following:

{
  "scripts": {
    "build": "carraway build",
    "develop": "carraway develop"
  }
}

Conclusion

Carraway is a simple tool in both idea and implementation. But using it will have some profound effects. It encourages the development of open software when building websites, and good organization of the content that makes your website. Hosting the code that powers your website in NPM packages will allow you to build your site like the software it is, while isolating your site-specific content and configuration.

The source code for Carraway can be found on Github. If you have any ideas for improvement, please contribute! Let's make powerful website creation simple and powerful.

Simplifying Gatsby Unit Testing using a Jest Preset

Kepler Sticka-Jones — Sat, 10 Aug 2019 21:19:08 +0000

Recently I have been expanding the codebase for my website and blog in order to have a more robust web presence. Part of this of course includes unit testing the source code using Jest. This code base's test suite is primarilly composed of Jest Snapshot Tests to ensure components and the pages they build are behaving and rendering as expected. Like any codebase, creating robust unit tests like this has many advantages; the primary ones for this code base being automated dependency updates using Dependabot and mutation testing (to ensure tests are working effectively) using Stryker.

I've used Jest for many projects before, and have built a few Jest plugins to improve the experience. I've built Jest runners to run linters alongside unit tests (jest-runner-prettier, jest-runner-stylelint, and jest-runner-tslint) and I've built a transformer module to make working with webpack projects easier jest-raw-loader. So when I saw room for improvement in testing my Gatsby codebase I knew exactly what to do.

Using Jest's Preset Functionality to Reduce Configuration Boilerplate

The Gatsby documentation on unit testing is fantastic and incredibly helpful (like the rest of the Gatsby documentation.) It runs you through the ropes of unit testing your site's code and gets you up and running quickly with little friction. However, it has one flaw: the config it requires you create inadvertantly creates a lot of boilerplate. Thankfully, Jest has functionality built in to abstract away boilerplate behind a preset.

Jest presets are found throughout the Jest documentation as a reccomended method to make testing easier in known environments. They're used to test React Native projects, run tests with Puppeteer, and make testing MongoDB and DynamoDB easier. Given this, let's abstract away the boilerplate needed to configure Jest to run Gatsby code and make life just a bit easier for us.

I've created a module which exports the default Jest config from the Gatsby documentation as a Jest preset. By using it our Jest config goes from this:

module.exports = {
  transform: {
    "^.+\\.jsx?$": "<rootDir>/.jest/gatsby-preprocess.js"
  },
  testRegex: "(/__tests__/.*|(\\.|/)(test|spec))\\.(jsx?)$",
  moduleNameMapper: {
    ".+\\.(css|styl|less|sass|scss)$": "identity-obj-proxy",
    ".+\\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$":
      "jest-raw-loader"
  },
  moduleFileExtensions: ["js", "jsx", "json", "node"],
  testPathIgnorePatterns: ["node_modules", ".cache"],
  transformIgnorePatterns: ["node_modules/(?!(gatsby)/)"],
  globals: { __PATH_PREFIX__: "" },
  testURL: "http://localhost",
  setupFiles: ["<rootDir>/.jest/loadershim.js"]
};

To this:

module.exports = { preset: "jest-preset-gatsby" };

TypeScript, too!

Abstracting this boiler plate has the added benefit of making life easier for us TypeScript users too. Configuring Jest to run in your Gatsby+TypeScript project becomes as easy as setting the following in your Jest config:

module.exports = { preset: "jest-preset-gatsby/typescript" };

Installation From Scratch

Interested in testing your Gatsby project, and haven't configured it yet? Now's a great time to start!

JavaScript Projects

Install jest, react-test-renderer, and jest-preset-gatsby using npm:

npm install --save-dev jest react-test-renderer jest-preset-gatsby

or Yarn:

yarn add --dev jest react-test-renderer jest-preset-gatsby

And configure Jest to use the preset in your package.json:

{
  "jest": {
    "preset": "jest-preset-gatsby"
  }
}

Or jest.config.js:

module.exports = { preset: "jest-preset-gatsby" };

And just like that you're ready to write your tests! Please see the Gatsby documentation on writing your first test.

TypeScript Projects

Install jest, react-test-renderer, jest-preset-gatsby, and the relevant type definitions using npm:

npm install --save-dev jest react-test-renderer jest-preset-gatsby @types/jest @types/react-test-renderer

or Yarn:

yarn add --dev jest react-test-renderer jest-preset-gatsby @types/jest @types/react-test-renderer

And configure Jest to use the preset in your package.json:

{
  "jest": {
    "preset": "jest-preset-gatsby/typescript"
  }
}

Or jest.config.js:

module.exports = { preset: "jest-preset-gatsby/typescript" };

And just like that you're ready to write your tests! Please see the Gatsby documentation on writing your first test.

Caveats

While this does make configuring Jest for Gatsby easier, it does come with one caveat. This project does not provide mocks for the gatsby module. Please see the Gatsby documentation on mocking gatsby in order to effectively test your code.