Preston So - Gatsby: The Definitive Guide

Gatsby leverages React components as its atomic unit for building websites, whether that means a Gatsby page or a Gatsby component within a page. In other words, everything in Gatsby is built using components. To understand this more deeply, lets take a look at the typical Gatsby project structure:

/|-- /.cache|-- /plugins|-- /public|-- /src |-- /pages | |-- index.js |-- /templates | |-- article.js |-- html.js|-- /static|-- gatsby-config.js|-- gatsby-node.js|-- gatsby-ssr.js|-- gatsby-browser.js

For the purposes of illustrating Gatsbys component-based architecture one-by-one, lets imagine that this Gatsby project consists of a home page (index.js) that links to individual pages that adhere to an article template (article.js). This article template renders the full text of each article into a consistent template for individual articles. To simplify this example even further, lets assume that these articles are coming from an external database rather than from the local file system.

Gatsby has four main types of components, the first three of which we can readily identify in the project structure above:

Page components

Page components become full-fledged Gatsby pages. Any component that is placed under src/pages becomes a page automatically assigned the path suggested by its name. For instance, if you place a contact.js or contact.jsx containing a React component in src/pages, it will eventually be available at example.com/contact/. In order for a file in src/pages to become a page, it must resolve to a string or React component.

Page template components

For relatively static pages, page components work well. But for pages that are templates, such as our article template, we need a repeatable boilerplate according to which well render each article. It would be prohibitive to write a page component for each individual article, so instead of doing that, we prefer to write a single page template component through which all article data will flow. Page templates are located under the src/templates directory.

The HTML component

There is only one HTML component, and it is src/html.js. The src/html.js file is responsible for all concerns that are outside the area of the page that Gatsby controls. For instance, you can modify metadata contained in the

element and add other markup. Customizing this file is optional, as Gatsby also has a default html.js that it uses as a fallback.Non-page components

These are the typical in-page React components. They are sections of a page, such as a header, that is embedded in a larger page component, forming a hierarchy. As well see later in the chapter, there are some non-page components that have greater importance, such as the layout component. In our sample Gatsby codebase above, we dont see a src/components directory, but this would be where our non-page components would appear.

The three types of components that most Gatsby developers will spend the most time in are page components, page template components, and non-page components. But how does Gatsby know what data to use to populate the props in those components? Thats where GraphQL and Gatsbys data layer comes in.