DEV Community

loading...

Make Gatsby Great

justinjunodev profile image Justin Juno ・6 min read

Set your Gatsby projects up for success with ESLint, Husky, React Axe, and Webpack Bundle Analyzer.

Preface:

Gatsby is a React-based front-end framework for building blazing fast websites and apps. I've used it in production across several teams/ products, and it even powers my personal site. However, like any framework, things can get hairy and go awry quickly without a proper setup.

My goal is to show you how to make a great Gatsby setup for you and your team. In this article, you'll learn how to:

  • Initialize a new Gatsby project.
  • Setup ESLint for monitoring code quality and styling.
  • Enforce code standards with Git hooks via Husky.
  • Watch for accessibility issues with React Axe.
  • Visualize your project's production bundle with Webpack Bundle Analyzer.

Before we get started, it is essential to note that this is not a tutorial for those looking to learn Gatsby or React. While you can easily follow along without any prior knowledge, it does not cover any foundational topics or information on building/ shipping a project with Gatsby.


1. Initialize a new Gatsby project.

Let's get started with a new Gatsby project. Open your terminal and run the following command.

npm init gatsby -y make-gatsby-great
Enter fullscreen mode Exit fullscreen mode

I've decided to name my project make-gatsby-great. However, you can pick a different name. After running this command, it'll prompt a few questions regarding the name and desired directory for your project. Answer them based on your preferences. You can select the No option for the CMS and Styling prompts, then Done for the additional features, as they aren't the focus of this tutorial.

Now that your site is ready follow the provided instructions and navigate into your project's directory.

cd make-gatsby-great
Enter fullscreen mode Exit fullscreen mode

2. Setup ESLint for monitoring code quality and styling.

If you are unfamiliar with ESLint, it is a tool for analyzing and identifying issues within your JavaScript codebase. As mentioned above, it monitors both code quality and code styling issues. While you can create your own rules and presets, I prefer to extend existing ones, as there are several with widespread adoption and use.

My current favorite is by Wes Bos. Not only are his rules and formatting great, his eslint-config-setup includes several peer-dependencies for prettier, react, react-hooks, jsx-a11y, and the infamous Airbnb standard. Best of all, we can install all of it with a single line of code.

In your terminal, run the following command.

npx install-peerdeps --dev eslint-config-wesbos
Enter fullscreen mode Exit fullscreen mode

Now we need to create a .eslintrc.js file. We will use this file to tell Gatsby to extend our desired ESLint configuration throughout our project. In your terminal, run the following command. It'll add the file to the root directory of your project.

touch .eslintrc.js
Enter fullscreen mode Exit fullscreen mode

Then open the file in your code editor and paste the following code. If you have any issues or would like more information on how to overwrite any of his settings, here is the repo.

module.exports = {
  globals: {
    __PATH_PREFIX__: true,
  },
  extends: `wesbos`,
}
Enter fullscreen mode Exit fullscreen mode

Assuming you have ESLint enabled in your IDE, you should already see some errors/ warnings in your project's code. While you could go through and resave each of these files manually to have them reformat and adhere to our new ESLint rules, there is a better way.

In your package.json, we need to add a few additional scripts. The first script, lint will check for any linting issues within our src directory. The second, lint:fix will check for and fix any linting issues within the src directory. Update your scripts object to look like this:

"scripts": {
  "develop": "gatsby develop",
  "start": "gatsby develop",
  "build": "gatsby build",
  "serve": "gatsby serve",
  "clean": "gatsby clean",
  "lint": "eslint ./src",
  "lint:fix": "eslint ./src --fix"
},
Enter fullscreen mode Exit fullscreen mode

Return to your terminal and try running the following commands. The first will return all of our current linting issues. The second command will fix them. To test this, you can rerun the first command; you shouldn't see or have any errors in your terminal.

npm run lint
Enter fullscreen mode Exit fullscreen mode
npm run lint:fix
Enter fullscreen mode Exit fullscreen mode

3. Enforce code standards with Git hooks via Husky.

Now that our code is formatted correctly and applying our linting preferences let's keep it that way with Husky. Husky allows us to set up Git hooks that will run specific scripts and tests at certain points in our Git execution. This step is crucial for those working with teams or on open-source projects that have multiple contributors.

Let's install Husky, return to your terminal and run the following command. The first will install husky, and the second will enable our Git hooks.

npm install husky --save-dev && npx husky install
Enter fullscreen mode Exit fullscreen mode

First, let's create a pre-commit hook that will automatically check and fix our linting issues before committing any code to our Git repo. To do this, we will take advantage of the script we wrote earlier. In your terminal, run the following command.

npx husky add .husky/pre-commit "npm run lint:fix"
Enter fullscreen mode Exit fullscreen mode

Lastly, let's add a pre-push commit as a final catch-all to check again for any linting issues. This check will force us and any contributors to resolve any linting issues before pushing code to our Git repository. We will take advantage of the script we wrote previously while setting up ESLint. Return to your terminal and run the following command.

npx husky add .husky/pre-push "npm run lint"
Enter fullscreen mode Exit fullscreen mode

If you'd like to see this in action, feel free to pause here and try making a commit. If you've followed the tutorial so far, it'll pass as we resolved our code's issues in the previous section. Hopefully, you can see how useful this is, as you can extend it to run tests and perform additional actions before allowing contributions to your project.


4. Watch for accessibility issues with React Axe.

Axe is an accessibility testing engine. It will monitor our Gatsby project and let us know if we have any accessibility issues within our application. If a problem is present, it'll print the information in our browser's console.

Fortunately, Gatsby has a plugin for it that'll make setup a breeze. In your terminal, run the following command:

npm install --save gatsby-plugin-react-axe
Enter fullscreen mode Exit fullscreen mode

Return to your code editor and open your gatsby-config.js file. Add the following snippet to your plugins array. We will include debounce options and make sure that our warnings only print in our development environment. You can explore more options here.

{
  resolve: 'gatsby-plugin-react-axe',
    options: {
      debounce: 1000,
      showInProduction: false,
    },
},
Enter fullscreen mode Exit fullscreen mode

Make sure your development environment is running. If not, run the following command and visit the provided preview link (should be http://localhost:8000).

npm run develop
Enter fullscreen mode Exit fullscreen mode

If you've followed the tutorial so far, you'll see we already have an error in our browser's console, as Gatsby doesn't ship with an HTML language attribute by default. It's an easy fix, but I'm going to ignore it as it isn't relevant to this tutorial.

When developing with this plugin, keep your browser's console open so you can monitor and fix additional a11y problems when they arise.


5. Visualize your project's production with Webpack Bundle Analyzer.

This one isn't for everybody, but I recommend it when working on large websites or complex applications. With the Webpack Bundle Analyzer, we can visualize the size of our bundled project. It provides an interactive treemap where we can view all of our site's modules, their size and look for performance optimizations.

Gatsby has a plugin for this as well, so let's install it. Head back to your terminal and run the following command.

npm i gatsby-plugin-webpack-bundle-analyser-v2 --save-dev
Enter fullscreen mode Exit fullscreen mode

Just like before, we will need to add this plugin to our gatsby-config.js file. Add the following snippet to the plugins array. Order isn't of importance here. It can come before or after the previously installed gatsby-plugin-react-axe plugin. Since we would like to view this in our development environment, we will provide that information to our options object.

{
  resolve: "gatsby-plugin-webpack-bundle-analyser-v2",
    options: {
      devMode: true,
    },
},
Enter fullscreen mode Exit fullscreen mode

Now, if you restart your development environment, you'll have an additional link displayed in your terminal for the Webpack Bundle Analyzer (it should open automatically, but if not, try http://localhost:3001). At first glance, it is a lot to take in. Just click around and learn more about the bundles in your application.


Wrapping Up.

I hope these tools will improve your productivity and make a difference in you/ your team's workflows. I barely scratched the surface on them, but I believe this is a great starting point for making a great Gatsby project.

If any of the steps mentioned above were confusing, or if you want a reference, here is a link to the final repo. In the future, I may revisit this article and include additional tools that I believe are helpful in production environments.


Enjoy this article? Let me know @justinjunodev and consider sharing it on your favorite social network.

Discussion (0)

pic
Editor guide