The Gatsby Proof-of-Concept Playbook

Rebuilding your company’s website is a complex project. To reduce risk, when many companies are considering a new website, they start with a proof of concept to test out different technology stacks.

The Gatsby team has worked with hundreds of teams building proof of concepts (PoCs) with Gatsby and wrote this playbook to be a definitive guide for you and your team as you build your PoC.

Building a sandwich, or choosing the right scope for your proof-of-concept

The first step in building a PoC is defining the right scope. Think about scoping a proof-of-concept like ordering a pizza or building a sandwich. You definitely need two slices of bread but depending on your individual needs or tastes there’s a wide range of things you might want to put in the middle.

The two important decisions you’ll make in scoping your project are which pages to test (type of bread), and which add-ons to choose (sandwich ingredients).

Choosing pages to test

The most basic form of a Gatsby proof-of-concept is to pick 1 or 2 pages or page templates that are high-traffic or important to the business, and test a few features, and then build them out at near high-fidelity.

For example, businesses selling products online often choose to build out their Product Details Page. Why? Because this template may have a reasonably complex layout with variations. It includes images and data associated with a product, with pages generated with custom URLs corresponding to product data. From the business’s perspective, this is perhaps the most important page type on the site.

Surveying the list of add-ons

Almost all teams have the same “basic” proof of concept, but have a wide range of “add-ons” (aka sandwich ingredients):

Test	Description	Questions you are testing	Frequency (1-5)
Basic	Rebuild 1-2 of your pages or templates in a Gatsby demo site.	How does Gatsby work? Can I replicate existing functionality? Does my team like this tool?	Universal (5)
Performance	Run Lighthouse tests on your new site; compare to current Lighthouse scores	Can Gatsby deliver perf gains vs existing site?	Popular (4)
UX Upgrade	Redesign 1-2 pages of your site & build on Gatsby	Can Gatsby support design changes I want to make?	Occasional (2)
Conversion	Run AdWords campaigns against your existing site vs new Gatsby landing pages	Will new designs and better performance improve conversions?	Occasional (2)
Content Workflows	Connect Gatsby to your headless CMS; let content editors try CMS Preview or building landing pages	Does my content team like the headless CMS + Gatsby workflow? Can it do the things they are expecting?	Frequent (3)
CMS Bakeoff	Same as above, but with multiple headless CMSs	Which headless CMS does my team like the best?	Occasional (2)
DX	Set up a basic JS toolchain; write one file in TypeScript, one test in Jest; one story in Storybook	How will the process of writing code feel like day-to-day for my team with a standard JS toolchain?	Occasional (2)
Scalability (advanced)	Build out 20-50k pages with dummy content; deploy using different platforms	What are build & preview speeds like with lots of content?	Rare (1)

Choosing the right add-ons for your team

So which add-ons make sense for your team? That mostly has to do with what you’re trying to achieve, and why you’re looking at Gatsby in the first place.

Most teams we see start with proof-of-concepts are working on their first headless or Jamstack project, and generally fall into two categories:

Project type	Description	Typical PoC scope
Lift-and-shift	A team wants to keep the same site UX but switch to a new tech stack	Basic + Performance + Conversion, sometimes CMS Bakeoff too
Site rebrand	The site is being redesigned and rebuilt; the marketing team has opinions about their preferred CMS.	Basic + UX Upgrade + Content Workflows, sometimes Performance and Conversion too

Scoping: a tale of three teams

Here are some examples of teams that have built proof-of-concepts with Gatsby.

Testing performance

One consumer financial firm was worried about website performance – they benchmarked their website, built using a leading site builder, and compared to their peer group of 4 competitors, their site was the slowest. They were looking at Gatsby, among other alternatives to improve page performance.

This team focused on building two key pages with a close-to-realistic design, and tested performance (Basic + Performance). Their Lighthouse scores improved from 20 to the mid-80s.

Testing conversion

In 2017, in the early stages of their migration to Gatsby & Contentstack, language learning firm Berlitz was testing different landing pages. Because Berlitz’s website is a primary lead generation funnel for their online and offline courses, conversion rate is incredibly important to them and is a big part of optimizing their demand generation spend.

The Berlitz team built some landing pages with their previous solution and others with Gatsby & Contentstack. Their Gatsby pages converted at nearly double the rate of the previous ones, speeding their conversion.

Testing scalability

For example, when Penn State News moved their 70k-page website onto Gatsby, the most important thing for them was ensuring build times for their team of 100 content editors were predictably below 3 minutes, and preview times under a minute.

While Penn State News didn’t do this at the time, one possible approach would have been generating 70k pages worth of dummy data, putting it in their CMS (Drupal), and testing out build and preview speeds with the setup, using different rendering modes on Gatsby Cloud.

Building your proof-of-concept

When teams ask us for advice in building a proof-of-concept, we recommend that they follow the steps below:

Start with a starter. Some folks may prefer to start with a fairly minimal starter like gatsby-starter-default. Others may prefer starters with a bit more built out: gatsby-starter-shopify, gatsby-starter-wordpress-blog, gatsby-starter-landing-page,
Add a CMS (if needed). If your starter doesn’t already come integrated with the CMS you’re looking for, we have documentation for CMSs like Contentful, Contentstack, WordPress, Sanity, Drupal, and 15+ other CMSs.
Query your CMS data. With a source plugin installed you should be able to see data showing up in the graphql explorer locally at localhost:8000/__graphql. Read the Query for data with GraphQL documentation for more details.
Build a page with components and styling. The file system route API guide walks you through creating a page. If you’re new to React, you may want to check out Building with Components. Take a look at Styling to see how the styling solution you’re most comfortable with works with Gatsby.
Deploy to Gatsby Cloud. When you deploy to Gatsby Cloud, our engineering team will have visibility into your Gatsby code. If you have questions or challenges about the framework or cloud setup, we can help. In addition, Gatsby Cloud has significantly (5-10x) faster builds and previews than other platforms, so you’re set up for the best experience.

In our experience, these steps work for the majority of proof-of-concepts.

Getting organizational buy-in

But, of course, a proof-of-concept isn’t simply a technical task, it’s also a step in an organizational decision-making process. This decision-making process can take from a few days to a few weeks, and involve stakeholders like content editors, demand generation marketers, engineering leaders, and executives – either internally or at a client.

As a result, it’s often important to communicate scope, schedule, and success metrics clearly. Here are some guidelines that we’ve found work well for teams.

Define Success Upfront. What does success look like for the project? Better Lighthouse scores? Improved conversion? Better content workflows? A bit of clarity before your proof-of-concept starts goes a long way to making a business case after your proof-of-concept concludes.

Define Each Person’s Responsibilities. A POC is usually a team effort; make sure that everyone’s role is plainly spelled out. When we work with teams, we often find that fleshing this out can foster great alignment. Here’s an example from a prospective Gatsby user we worked with recently:

1. 1. Lead Engineer @ Company X – responsible for defining, developing, and delivering the POC
  2. Engineering Manager @ Company X – responsible for finding out the process for building a business case and next steps
  3. Gatsby Solutions Engineer – responsible for check-in calls with Company X and answering any technical questions
  4. Gatsby Sales – responsible for checking in on overall project progress and sharing resources

Broadcast Your Schedule. An aggressive schedule, widely communicated, will lend a sense of urgency in the process. Otherwise, scope creep can cause delay as various stakeholders, trying to be helpful, suggest additional things to include.

Make A Business Case. A good business case includes both customer-facing metrics like website performance or conversion rate, as well as internal measures like content editor or developer experience. It usually includes both quantitative and qualitative measures. And a good business case built by the engineering team tries to suss out and address marketing concerns before it’s presented to upper management.

A typical proof-of-concept timeline

While every company is different, a typical agency or organization we work with has a timeline like the following:

Phase 1 (Week 1)

Project Discovery & Definition
1. CMS
Align on Project Goals
Define Success Criteria
Loop in Gatsby representative

Phase 2 (Week 1)

Loop in CMS rep (Contentful, Contentstack, Sanity, etc.)
Assign dedicated roles and timeline
Meet with Gatsby engineers and begin PoC

Phase 3 (Week 2)

Check-in call with Gatsby team
Start on Gatsby Cloud

Phase 4 (Week 3)

Benchmark Gatsby site vs. old site
Review any outstanding questions
Fine-tune POC

Phase 5 (Week 3-4)

Build Business Case and Present
Evaluation Findings

To prevent delay, evaluate in parallel

We’ll conclude with a final caution: many teams new to the Jamstack world need multiple solutions: for example, they need a headless CMS, a framework, and a deploy/hosting provider. For these teams, because time is money, our recommendation is to evaluate solutions in parallel, not sequentially.

For larger companies, making decisions sequentially, in a “waterfall” approach, can feel more comfortable. Unfortunately, this can delay projects that otherwise could have been started (and completed!) sooner, delivering more business impact.

For example, if the budget for a headless CMS provider is only available in Q4, it doesn’t mean that a team can’t build and prototype different development alternatives before Q4. In fact, we see some teams take advantage of Gatsby’s data layer, building a prototype with dummy data stored in a JSON file.

Then, when the team gains access to their CMS, they are able to add data to the CMS and fairly easily rewrite their page and component GraphQL queries to point to the CMS.