Lions and Tigers and Errors, Oh My! Redesigning the Gatsby CLI

Shannon Soper
Shannon Soper
May 22nd, 2019

How did this project come about?

The CLI is the main entry point and interface people have (currently) for Gatsby. Everyone sees it! So it has a huge influence on people’s experience of Gatsby.

We conducted 4 usability tests with awesome Gatsby users to learn how they do tasks using the Gatsby CLI and how they use error messages to debug their projects. Thanks Simon Koelewijn, Gene Smith, Jonathan Prozzi, and Benjamin Lannon for teaching us how you use the CLI, and thanks to @sidharthachatterjee, @wardpeet, @pieh, @m-allanson, @gillkyle for copiloting the interviews with me and helping turn what we learned into action.

If you want to be part of future usability tests, sign up here.

What did we learn?

Our error messages aren't always helpful; sometimes they are even absent! They don't comply with best practices suggested by the research we did.

We did a thorough search of other CLIs and style guides to learn what we're doing well and where we might be falling short. Here are resources that informed our knowledge of problems that Gatsby CLI has and possible ways to solve those problems:

What do we need to do next?

To optimize the CLI design, we’ll use the data being collected through our telemetry setup, which collects data about CLI usage (opt out is possible).

  1. Crunch some numbers to find out what the most common error messages are that people get
  2. Make error messages better, starting with the most common ones
  3. Create a CLI style guide and make sure the CLI starts matching the style guide
  4. Do some other things that will make the CLI easier to use (easier = takes less time to do a task and/or is less frustrating). See issues tagged with topic: cli in the OSS repo!

Want to dive in and help / comment?

The first step is to get consensus on the Error Survey RFC & CLI Redesign RFCs and start on the changes they suggest.

All issues related to those RFCs will be tagged with topic: cli in the OSS repo.

List of issues (some already have PRs in progress):

Talk to our team of Gatsby Experts to supercharge your website performance.