Design Concept: Gatsby

[arcticicestudio]

This epic documents the design concept of the static site generator that'll be used to build Nord Doc'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 Nord Docs as documented in #24.

• 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 #TODO).
• 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 Nord Docs 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.

Core Configuration

The core configuration of Gatsby is the gatsby-config.js file that will be placed in the project root. It will define 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 #27 - “Gatsby initial configuration”

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:

• Babel configuration #29 - “Babel configuration”

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.

Nord Docs 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 #27 - “Gatsby initial configuration”

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:

• Babel configuration #29 - “Babel configuration”

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:

• Webpack configuration #31 - “Webpack configuration”