Design Concept: Gatsby

[arcticicestudio]

This epic documents the design concept of the static site generator that'll be used to build arctic’s and serves as a plan for the initial launch. It defines the process steps to decide about aspects like the Gatsby core configuration, Gatsby API implementations, required Gatsby plugins, custom configurations for Babel and Webpack and many more.

🚧 This is a living document which means it is work in progress, not completed yet and will be extended!

What is Gatsby?

Gatsby is a blazing fast modern site generator to build secure, modern and blazing fast websites and apps with React. It is fully compliant to JAMstack which is the web development architecture used to built arctic as documented in #3.

• Gatsby is one of the most popular and state-of-the-art projects of its kind, comes with many unique features builtin into the core while being fully extensible through a advanced plugin API with an large ecosystem.
• Gatsby generates PWAs (Progressive Web App) with code and data splitting out-of-the-box™ to only load the critical HTML, CSS, data, and JavaScript so the website loads as fast as possible and prefetches resources for other pages once loaded while clicking around the site to make it feel incredibly fast.
• Gatsby scales to the entire internet by building sites as “static” files which can be deployed easily on dozens of services and fits perfect when used in combination with a continuous deployment concept like e.g. like Netlify (see Design Concept: Hosting & Continuous Deployment #9).
• Gatsby provides data through a GraphQL API that can be injected into every component and page while the data can be pulled from almost every source: headless CMSs, SaaS services, APIs, databases, the file system…

Gatsby is much more than just a static “site” generator powered by React as explained by the founder and core team members:

It produces static HTML and then rehydrates into a React app.
Think of it as an opinionated CRA with built-in SSR and nice integrations with CMS.
Gatsby is also there to build apps. — Kyle Mathhews, Founder of Gatsby

Gatsby can handle apps with:

• User authentication? ✅
• Dynamic data? ✅
• Asynchronous requests? ✅
• Ecommerce? ✅
• Full-blown SaaS? ✅

You can do SO MUCH MORE than static sites with Gatsby. — Jason Lengstorf , Gatsby Core Team Developer

There are countless more features, but it is out of scope for this document to introduce these here. Instead, make sure to check their official project website with the extensive, well-written docs and really intense and beginner-friendly tutorials. It also includes a large overview and comparison of all features, a plugin library and inspiring showcases.
In their blog they publish a lot of great guides, tips & tricks and articles like how Gatsy got so popular that they founded Gatsby Inc. and blog posts about the companies feature plans and values.

Implementation Plan

To build arctic with Gatsby there are several process steps that must be planned and implemented. This section splits it up into categories and theirs tasks that will be documented and tracked within this epic.

Gatsby Themes

On July 3rd 2019, the long-awaited Gatsby Themes API was announced.
This allows to extract logic and components into own packages that can be composed together for reuse in other Gatsby projects or as template/starter for new projects.

arctic will make use of this awesome feature by implementing splitting up into multiple scoped (@arcticicestudio) packages for a simply modularized code base:

1. @arcticicestudio/gatsby-theme-arctic-core — A Gatsby Theme that provides basic and essential plugins and configurations that can simply be used in other projects or serve as base theme. It'll try to be as generic as possible while still being dynamic configurable.
2. @arcticicestudio/gatsby-theme-arctic-core — The main Gatsby Theme that'll be more opinionated when it comes to CSS-in-JS libraries and usage of other larger projects/plugins that are not only targeted to basic/essential configurations. It will be the main source for core components and layouts that can be used to extend another Gatsby Theme on.
3. www — The package of the website itself. It will use and compose both Gatsby Theme packages and adds additional Gatsby plugins and configurations specific to the site as well as plugins that can only be applied in this package due to their required loading order (e.g. gatsby-plugin-offline).

Since arctic’s repository structure is a monorepo, the modular architecture comes with even more improvements like hoisted dependencies and a way smoother developer experience due to direct loading of local packages.

Core Configuration

The core configuration of Gatsby is the gatsby-config.js file that will be placed in the root directories of the theme and website packages. It defines project-wide site metadata that can be used through the GraphQL API and configures all plugins that will be used.

All implementation details and requirements are documented and tracked in the corresponding issues:

• Gatsby initial configuration #35 (⊶ -) „Gatsby initial configuration“ — in progress ∞

API Implementations

Gatsby can be customized and extended to the core by providing…

• …the Node API that gives plugins and site builders many APIs for controlling the build process. It can be implemented in the gatsby-config.js file placed in the project root.
• …the SSR API to hook into the server-side rendering process. It can be implemented in the gatsby-ssr.js file placed in the project root.
• … the Browser API to hook into the APIs used for browser related functionality. It can be implemented in the gatsby-browser.js file placed in the project root.

All APIs come with a collection of functions called “Actions” that can be used to manipulate the build.

For more details make sure to read the API specification and philosophy and references for the GraphQL API.

All implementation details and requirements are documented and tracked in the corresponding issues:

• Gatsby initial configuration #35 (⊶ -) „Gatsby initial configuration“ — in progress ∞

Gatsby Plugins

Gatsby is designed to be easily extensible while being functional out-of-the-box™. This is possible by using the powerful plugin API to simply create own plugins or browse the plugin library since there is already a large ecosystem and a plugin for almost everything.

arctic will make use of various plugins to implement features and simplify the code base for a better developer experience.

All implementation details and requirements are documented and tracked in the corresponding issues:

• Gatsby initial configuration #35 (⊶ -) „Gatsby initial configuration“ — in progress ∞

Babel Configuration Modification

Gatsby comes with an already optimized Babel configuration to create SSR “static” websites and apps, but there are also use cases that require to modify and extend this configuration to e.g. add a new Babel plugin for the latest syntax feature/proposal support.
Of course Gatsby provides a way through the Node API by implementing the onCreateBabelConfig function.

All implementation details and requirements are documented and tracked in the corresponding issues:

• Gatsby initial configuration #35 (⊶ -) „Gatsby initial configuration“ — in progress ∞

Webpack Configuration Modification

This is almost the same like the section above about how to modify and extend the Babel configuration but now for Webpack instead of Babel. This can be necessary to e.g. add a builtin or third-party plugin or to add resolve aliases. For sure Gatsby supports this too by providing the onCreateWebpackConfig function through the Node API.

All implementation details and requirements are documented and tracked in the corresponding issues:

• Gatsby initial configuration #35 (⊶ -) „Gatsby initial configuration“ — in progress ∞