Learn Gatsby - Core Concepts & Main Architecture

#Introduction

Now that you understand Gatsby's history and position, let's move to the most important part: how Gatsby works behind the scenes. You don't need to memorize every internal detail, but understanding its architecture will make all the hands-on episodes that follow far more intuitive.

Episode 2 breaks down the GraphQL data layer, the build process, project structure, the query system, and routing. This is the conceptual foundation you'll use every day while developing with Gatsby.

#Gatsby's Data Layer with GraphQL

#GraphQL as the Backbone of Data

Gatsby builds an in-memory graph containing all of your site's data: files, Markdown, CMS content, APIs, and metadata. This graph is queried with GraphQL. The advantage: you only request the data you need, and the results are clearly typed.

Source plugins pull data in. For example, gatsby-source-filesystem reads local files, gatsby-source-contentful pulls content from Contentful, and gatsby-source-graphql fetches data from external GraphQL APIs.

#Build Process: Source, Transform, Generate

The entire Gatsby flow follows three main stages:

source → transform → generate

• Source: plugins pull raw data into GraphQL nodes.
• Transform: transformer plugins convert the data, e.g., Markdown to HTML and Sharp producing responsive images.
• Generate: Gatsby renders pages into static HTML files.

When you run gatsby build, these three stages execute in sequence and the results are written to the public folder.

#Gatsby Project Structure

#Core Files and Folders

A standard Gatsby project has a structure like this:

my-gatsby-site/
  src/
    pages/
    components/
    templates/
    images/
  content/
    posts/
  gatsby-config.js
  gatsby-node.js
  gatsby-browser.js
  gatsby-ssr.js
  package.json

The role of each folder and file:

• src/pages: .jsx files here automatically become routes.
• src/components: reusable components like header and footer.
• src/templates: templates for programmatically created pages.
• gatsby-config.js: main configuration, site metadata, and the plugin list.
• gatsby-node.js: the API for creating dynamic pages and modifying the schema.
• gatsby-browser.js: the lifecycle API for code that runs in the browser.

#Page Query vs Static Query

#Page Query

A page query can only be used in a page or template file. The query is defined as a named export query and runs at build time:

Page query in a page file

import { graphql } from "gatsby"
 
export const query = graphql`
  query HalamanTentang {
    site {
      siteMetadata {
        title
      }
    }
  }
`

The query result is automatically available as the data prop on the page component.

#Static Query with useStaticQuery

Non-page components can't use page queries. For that, Gatsby provides useStaticQuery:

Static query in a component

import { useStaticQuery, graphql } from "gatsby"
 
const Header = () => {
  const data = useStaticQuery(graphql`
    query {
      site {
        siteMetadata {
          title
        }
      }
    }
  `)
  return <header>{data.site.siteMetadata.title}</header>
}

The useStaticQuery hook can only be called once per component and runs at build time.

#File-Based Routing and Client-Only Routes

#File-Based Routing

Gatsby's routing is file-based: src/pages/index.jsx becomes /, src/pages/about.jsx becomes /about/, and src/pages/blog/first-post.jsx becomes /blog/first-post/. No manual router configuration needed.

#Client-Only Routes

Sometimes we need pages that only exist on the client, such as application routes after login. You do this with the matchPath property on a page:

Client-only route with matchPath

const AppPage = () => <h1>Halaman Aplikasi</h1>
 
export default AppPage
 
export function Head() {
  return <title>Aplikasi</title>
}
 
AppPage.matchPath = "/app/*"

The matchPath: "/app/*" property tells Gatsby that this route is handled entirely on the client. This is useful for applications that require authentication — we'll cover it in detail in episode 13.

#Static Assets, Image Optimization, and Prefetching

#Handling Assets and Images

Gatsby optimizes images automatically through gatsby-plugin-image and Sharp: modern formats like WebP and AVIF, responsive sizes, lazy loading, and blur placeholders. Episode 6 covers this in depth.

#Page Prefetching

One of the features that makes Gatsby feel incredibly fast: when a user hovers over a Gatsby Link, the destination page is prefetched immediately, so navigation feels instant. This is default behavior, not an extra plugin.

#Conclusion

Episode 2 provided Gatsby's conceptual map: the GraphQL data layer that unifies many sources, the source-transform-generate build process, project structure, the page query and static query system, and file-based and client-only routing.

Key takeaways:

• The GraphQL data layer unifies all data sources into a single graph.
• The build flow is always source, transform, then generate.
• src/pages defines routes; everything else is managed by gatsby-node.
• Page queries are for page files; useStaticQuery is for components.
• matchPath creates client-only routes.
• Gatsby optimizes images and prefetches links by default.

In the next episode we'll get hands-on: creating a Gatsby project with the CLI, exploring the generated structure, running the dev server, and adding basic plugins. Open your terminal — time for real code.