A short month ago, we released a new set of starters at GatsbyConf ‘22 geared towards making homepage websites with Gatsby and your favorite CMS even more straightforward.
If you attended GatsbyConf, you may have even caught a breakout session with Design Manager Molly Misek and myself showing just how easy it is to tailor the Figma community file and Contentful flavor of the homepage starter to the branding needs of a made up company “Acme Corporation”.
But there’s more to the story for how you can make the Homepage Starters work for you.
Read on for some insight into why we decided to invest in these starters and who we envision benefiting from them. We’ll also dive into the design of the development repository behind all the starters and touch on the improvements we’ve made in the last month — such as TypeScript versions, support for optional blogs and additional CMSs.
Bringing Developers and Content Editors Together
In the past few quarters, we took stock and identified gaps in our official starters. One key take-away we internalized was the need to provide more practical “real-world” use cases — and the homepage starters felt like a natural progression beyond the typical blog and portfolio use cases you’ll find with other starters.
The homepage starters are ideal for any professional developer looking to create a performant website for their startup, company, or a client. They also demonstrate Gatsby’s versatility to work with whichever headless CMS you prefer or have already invested in, providing a familiar experience for any content editor. And, it is precisely that relationship between content editors and developers that was a focus while planning the homepage starters project.
We believe that Gatsby can serve as a bonding agent between these two personas — allowing developers to keep up with modern tooling on a modern stack, while their colleagues who create content are free to do so wherever they feel most comfortable. In fact, with Gatsby’s data layer, you’re not tied to just one CMS — a feature we also aimed to showcase within the starters with the inclusion of the optional blog themes.
For example, does your company have a blog on WordPress but you’d like to start using something more modern and flexible like Contentful for marketing landing pages? Not a problem at all! Fetch your data from multiple sources at build time and bring it all together in the content mesh. In fact, I didn’t need to reach far for this example as it is the exact situation for gatsbyjs.com.
Creating a Development Repository That Scales
As of April 12th, 2022 there are a total of ten variations of the homepage starter available — five supported CMSs (Contentful, WordPress, Drupal, DatoCMS and Sanity) and both TypeScript and JavaScript UIs to pair with them. All of these variations are generated from a single source development repository through the power of plugins (and themes) which makes it easy to maintain a single source of truth and feature parity across the different CMSs.
A fundamental aspect to making this possible was explicitly defining types in the GraphQL schema with the use of Gatsby’s Schema Customization API and the @dontInfer type directive. This practice allowed us to create a unified data layer interface to query from our page components while delegating the specifics of mapping data from the varying formats of different CMSs to each plugin. For example, the UI queries for HomepageHero rather than ContentfulHomepageHero or WpHomepageHero. And this explicit contract between the data model of the CMS and what the site expects means that data model changes on the backend won’t break the site! You can read more about this practice in our documentation on Customizing the GraphQL Schema.
With a consistent, explicitly typed interface to the data, we were then able to create a set of “block” or “section” React components that corresponded to different segments of the pages in the Figma designs. These section components are labeled and identifiable by a special key, blocktype, and each one defines the data they expect to receive as props via GraphQL fragments. Those fragments are then combined in the query providing a page component (e.g., index or about page) with its data. You can see this demonstrated with this snippet from the index page:
This creates a dynamic, composable pattern where page components are not much more than a Layout and mapping function over the different blocks or “sections”, and pairing up the block data with the corresponding section component by the block’s blocktype.
While there are a myriad of different sections provided with the starter to fit common web designs, we also recognize that user’s needs will likely require creating new section components. You’ll be able to find an example in the repository README addressing this need, which details the steps involved for adding a new “homepage banner” section. There is also an example PR for reference if you prefer to learn that way.
Going one layer deeper, each of the section components are built with a set of “UI” components that create a lightweight design system of sorts for reusable and consistent UI. These components are styled with vanilla-extract which we also utilize to create a theme — allowing for easily interchangeable colors, font properties and spacing to fit your branding needs. As demonstrated in the breakout session, this system empowers designers and developers to make site wide aesthetic changes by changing just a few lines of code.
The initial release of these starters was in JavaScript, but as part of the effort to better support the TypeScript community at Gatsby, they are now available in TypeScript as well. Given our development repository setup, this intention presented a somewhat unique use case for transpiling the now TypeScript source — not to ES5, but to JavaScript that is syntactically equivalent to the source code’s prior state. After some experimentation, this was realized programmatically within the development repository’s publish script via a combination of ts.transpileModule, prettier and a bit of a hack to preserve newlines in the resulting transpiled JavaScript.
The end result is a fully type-safe project — from the explicitly typed GraphQL schema, to the style system powered by vanilla-extract, to the React components written in TSX — you’ll always know what you’re getting. And, if you choose this starter as a quick way to get your next homepage off the ground, you not only get the choice of CMS but also the choice of JavaScript or TypeScript. We think that’s pretty cool!
Still Not Finding Your Fit?
The beauty is that this starter lays out a recipe that can be followed for adding any other CMSs — something we’re looking to the community for help with! If that sounds interesting to you, be sure to check out our guide for creating a new homepage starter. We look forward to your pull request!
Lastly, if you have any questions about these starters (or others), reach out to us in this dedicated channel on Discord. Happy coding.