Gatsby: The Definitive Guide

Table of contents

1. Foreword
2. Preface
   1. Who Should Read This Book
   2. Why I Wrote This Book
   3. Navigating This Book
   4. Conventions Used in This Book
   5. Using Code Examples
   6. O’Reilly Online Learning
   7. How to Contact Us
   8. Acknowledgments
3. I. Elementary Gatsby
4. 1. Gatsby Fundamentals
   1. What Is Gatsby?
      1. Gatsby Pages and Components
      2. Gatsby’s Data Layer: GraphQL and Source Plugins
      3. The Gatsby Ecosystem
   2. Why Gatsby?
      1. Performance
      2. Accessibility
      3. Developer Experience
      4. Security
   3. Gatsby and the Jamstack
      1. Static Site Generators
      2. Distributed Content and Commerce
      3. The Jamstack
   4. JavaScript in Gatsby
      1. Command-Line Interfaces
      2. Modular JavaScript
   5. React in Gatsby
      1. Declarative Rendering with JSX
      2. React Components
      3. React Props
   6. Getting Going with Gatsby
      1. The Command Line
      2. Installing the Gatsby CLI
   7. Creating Your First Gatsby Site
      1. Starting a Development Server
      2. Creating a Production Build
      3. Serving the Production Build Locally
   8. Conclusion
5. 2. Core Elements of Gatsby
   1. The Gatsby CLI
      1. Installing and Configuring the Gatsby CLI
      2. gatsby new
      3. gatsby develop
      4. gatsby build
      5. gatsby serve
      6. Other Useful Gatsby CLI Commands
   2. Starters
      1. Official and Community Starters
      2. Modifying Starters
      3. Creating a New Project from a Starter
      4. The gatsby-config.js File
   3. Gatsby Pages and Components
      1. Pages
      2. Components
      3. Linking Between Pages
      4. The Layout Component
   4. Using CSS in Gatsby
      1. Global Styling
      2. Modular Styling with CSS Modules
      3. CSS-in-JS
   5. Extending Gatsby with Plugins
      1. Installing Gatsby Plugins
      2. Loading Local Plugins
   6. Conclusion
6. 3. Adding Features to Gatsby Sites
   1. Pages and Routing in Gatsby
      1. Rehydration
      2. Static Pages
      3. Hybrid Application Pages
      4. Client-Only Routes
      5. Differences Between Gatsby Sites and React Applications
   2. Adding Forms
      1. Basic Forms
      2. Handling Form Submissions
   3. Adding Localization and Internationalization
      1. gatsby-plugin-i18n
      2. react-intl
      3. react-i18next
   4. Adding an XML Sitemap
   5. Adding a 404 Page
   6. Adding Analytics
   7. Conclusion
7. II. Data in Gatsby
8. 4. GraphQL and the Gatsby Data Layer
   1. GraphQL Fundamentals
      1. GraphQL Queries
      2. GraphQL Fields
      3. GraphQL Arguments
      4. GraphQL Query Variables
      5. GraphQL Directives
      6. GraphQL Fragments
      7. GraphQL Schemas and Types
   2. The Gatsby Data Layer
      1. GraphiQL
      2. GraphiQL Explorer
      3. GraphQL Playground
   3. Page and Component Queries
      1. Page Queries
      2. Component Queries with StaticQuery
      3. Component Queries with the useStaticQuery Hook
   4. Conclusion
9. 5. Source Plugins and Sourcing Data
   1. Using Source Plugins
      1. Installing Source Plugins
      2. Setting Up Source Plugins
      3. Using Environment Variables with Source Plugins
   2. Sourcing Data from the Filesystem
      1. Setting Up gatsby-source-filesystem
      2. Working with Files from the Filesystem
      3. Working with Multiple Directories in the Filesystem
   3. Sourcing Data from Database Systems
      1. MongoDB
      2. MySQL
      3. PostgreSQL
      4. Amazon Redshift, SQLite3, Oracle, and MSSQL
   4. Sourcing Data from Third-Party SaaS Services
      1. Airtable
      2. AWS DynamoDB
      3. Google Docs
   5. Sourcing Data from CMSs and Commerce Systems
      1. Contentful
      2. Drupal
      3. Netlify CMS
      4. Prismic
      5. Sanity
      6. Shopify
      7. WordPress
   6. Sourcing Data from Other Sources
      1. Sourcing Data from GraphQL APIs
      2. Sourcing Data from JSON and YAML
   7. Conclusion
10. 6. Programmatic Page Creation
    1. Traversing GraphQL Data in Pages
    2. Working with Transformer Plugins
       1. Adding Transformer Plugins
       2. Transforming Markdown into Data and HTML
       3. Adding a List of Markdown Pages
    3. Working with gatsby-node.js
       1. Creating Slugs for Markdown Pages
       2. Adding a Template
       3. Adding Markdown Pages with createPages
    4. Conclusion
11. 7. Assets in Gatsby
    1. Working with Assets
       1. Types of Assets in Gatsby
       2. Importing Assets Directly with Webpack
       3. Querying for Assets with gatsby-source-filesystem
       4. Importing Assets with the static Folder
    2. Working with Images
       1. The gatsby-plugin-image Plugin (Gatsby 3.0)
       2. The gatsby-image Component (Gatsby 2.0)
    3. Working with Videos
       1. Creating Custom Components for Hosted Videos
       2. Querying Videos from Markdown Using GraphQL
       3. Self-Hosting Your Own Videos
    4. Working with Fonts
       1. Adding Local Fonts
       2. Adding Web Fonts
    5. Conclusion
12. 8. Adding Data-Driven Features to Gatsby Sites
    1. Adding Site Search
       1. Implementing Site Search with Algolia
       2. Configuring gatsby-plugin-algolia
       3. Querying Pages with GraphQL for Indexing
    2. Adding a Commenting System
    3. Adding Taxonomy to Blog Posts
       1. Adding Tags and Querying for All Tags
       2. Adding a Tag Page Template
       3. Programmatic Tag Page Creation with gatsby-node.js
       4. Adding a Tag Index Page
    4. Adding Pagination
       1. Preparing for Pagination in Page Templates
       2. Generating Paginated Pages with gatsby-node.js
    5. Adding an RSS Feed
       1. Adding an RSS Feed to a Markdown Blog
       2. Adding an RSS Feed for Non-Markdown Content
    6. Adding Authentication
       1. Preparing for Authentication
       2. Creating Client-Only Routes
       3. Managing Private Routes
       4. Providing Privileged Data to Routes
    7. Conclusion
13. III. Extending Gatsby
14. 9. Gatsby Plugins and Starters
    1. Creating Gatsby Starters
       1. Gatsby Starter Requirements
       2. Enabling Starter Configuration
       3. Starter Performance and Accessibility
       4. Licensing, Testing, and Releasing Starters
    2. Creating Gatsby Plugins
       1. Plugin Nomenclature
       2. Initializing a New Plugin Project
       3. Plugin Configuration with Options
       4. Interacting with Gatsby Lifecycle APIs
    3. Creating Source Plugins
       1. Initializing Projects for Source Plugin Development
       2. Installing the Source Plugin
       3. Creating GraphQL Nodes
       4. Querying and Sourcing Remote Data
       5. Establishing Foreign Key Relationships
       6. Using Plugin Options to Allow Customization
    4. Creating Transformer Plugins
       1. Reviewing an Example: gatsby-transformer-yaml
       2. Ensuring Needed Data Is Sourced
       3. Transforming Nodes
       4. Establishing the Transformer Relationship
       5. Creating New Nodes from Derived Data and Querying
    5. Publishing and Maintaining Plugins
       1. Submitting Plugins to the Gatsby Plugin Library
       2. Maintaining Plugins
    6. Conclusion
15. 10. Gatsby Themes
    1. Gatsby Themes in Context
       1. Differences from Plugins and Starters
       2. Deciding Between Using and Creating a Theme
    2. Using Gatsby Themes
       1. Starting a New Site from a Theme
       2. Using a Theme in an Existing Site
       3. Using Multiple Gatsby Themes
    3. Creating Gatsby Themes
       1. Creating New Themes
       2. Gatsby Theme Conventions
       3. Converting Starters into Themes
    4. Theme Shadowing
       1. Theme Shadowing in gatsby-theme-blog
       2. Shadowing Other Files
       3. Extending Shadowed Files
    5. Conclusion
16. IV. Production Gatsby
17. 11. Debugging and Testing Gatsby
    1. Testing Gatsby
       1. Unit Testing with Jest
       2. Testing React Components
       3. Visual Testing with Storybook
       4. End-to-End Testing with Cypress
    2. Debugging Gatsby
       1. Debugging Static Builds
       2. Debugging the Build Process
       3. Debugging Server-Side Rendering Issues
       4. Debugging Cache Issues
       5. Debugging Asynchronous Lifecycle Methods
    3. Conclusion
18. 12. Deploying Gatsby
    1. Environment Variables
       1. Defining Environment Variables
       2. Using Environment Variables
    2. Using Path and Asset Prefixes
       1. Path Prefixes
       2. Asset Prefixes
    3. Deploying to Hosting Services
       1. Netlify
       2. Vercel
       3. Gatsby Cloud
       4. AWS Amplify
       5. Azure
       6. Amazon S3
       7. Heroku
       8. Firebase
       9. GitHub Pages
    4. Conclusion
19. V. Advanced Gatsby
20. 13. Advanced Topics in Gatsby
    1. Creating Recipes
       1. Infrastructure as Code
       2. Automating Site Operations with Recipes
    2. Adding Components to Markdown with MDX
       1. Getting Started with MDX
       2. Creating MDX Pages
       3. Importing Components into MDX Files
       4. Customizing Markdown Components
    3. Schema Customization
       1. Explicitly Defining Data Types
       2. Implementing the createResolvers API
       3. Creating Custom Interfaces and Unions
    4. Custom Gatsby Configuration
       1. Babel
       2. Babel Plugin Macros
       3. Webpack
       4. Customizing html.js
       5. ESLint
       6. Proxying API Requests
    5. Performance Optimization
       1. Caching Gatsby Sites
       2. Adding a Progressive Web App Manifest File
       3. Adding Offline Support with Service Workers
       4. Profiling with React Profiler
       5. Performance Tracing for Gatsby Builds
       6. Conditional Page Builds
    6. Conclusion
21. 14. Gatsby Internals
    1. APIs and Plugins in Gatsby
       1. Loading Configured Plugins
       2. The apiRunInstance Object
       3. Executing Plugins and Injecting Arguments
    2. The Gatsby Build Lifecycle
       1. Node Creation
       2. Schema Generation
       3. Schema Inference
       4. Schema Root Fields and Utility Types
       5. Page Creation
       6. Query Extraction and Execution
       7. Writing Out Pages
    3. Bundling Gatsby
       1. Generating the JavaScript Bundle
       2. The production-app.js file
       3. Enabling Code Splitting and Prefetching
    4. Conclusion
22. A. The Gatsby CLI
    1. Gatsby Cheat Sheet
       1. Common CLI Commands
       2. Quick Start Commands
       3. Helpful File Definitions
       4. Top Documentation Pages
    2. Gatsby CLI Commands
       1. new
       2. develop
       3. build
       4. serve
       5. info
       6. clean
       7. plugin
       8. repl
23. B. Gatsby Component APIs
    1. <Link />
       1. <Link /> Usage
       2. Active Styles for <Link />
       3. Working with Props in <Link />
       4. navigate
    2. gatsby-plugin-image
       1. StaticImage
       2. GatsbyImage
       3. Image Options
       4. Helper Functions
24. C. Gatsby Configuration APIs
    1. Config APIs
       1. siteMetadata
       2. plugins
       3. flags
       4. pathPrefix
       5. polyfill
       6. mapping
       7. proxy
       8. developMiddleware
    2. Node APIs
       1. createPages
       2. createPagesStatefully
       3. createResolvers
       4. createSchemaCustomization
       5. onCreateBabelConfig
       6. onCreateDevServer
       7. onCreateNode
       8. onCreatePage
       9. onCreateWebpackConfig
       10. onPostBootstrap
       11. onPostBuild
       12. onPreBootstrap
       13. onPreBuild
       14. onPreExtractQueries
       15. onPreInit
       16. pluginOptionsSchema
       17. preprocessSource
       18. resolvableExtensions
       19. setFieldsOnGraphQLNodeType
       20. sourceNodes
       21. unstable_onPluginInit
       22. unstable_shouldOnCreateNode
25. Index