Gatsby Config and Plugins — Extending Gatsby Functionality

In this tutorial, you will learn about Gatsby Config and Plugins. We cover key concepts, practical examples, and best practices to help you master this topic.

Learn Gatsby configuration, plugin ecosystem, installing and configuring plugins for data sourcing, transformations, and optimizations in Gatsby.

In this lesson, you'll understand gatsby-config.js, how plugins work, and how to configure common plugins for your project.

What You'll Learn

How to structure gatsby-config.js, find and install plugins, configure plugin options, and understand plugin types (source, transformer, plugin).

Why It Matters

Plugins are Gatsby's superpower. The right plugin configuration handles image optimization, SEO, data sourcing, and performance optimization without custom code.

flowchart LR
    A[gatsby-config.js] --> B[Source Plugins]
    A --> C[Transformer Plugins]
    A --> D[Site Plugins]
    B --> E[Pull Data]
    E --> F[GraphQL Layer]
    F --> G[Pages]
    C --> H[Transform Data]
    H --> F
    style A fill:#639,color:#fff

Basic Configuration

// gatsby-config.js
module.exports = {
  siteMetadata: {
    title: 'My Gatsby Site',
    description: 'A blazing-fast static site',
    author: '@dodatech',
    siteUrl: 'https://tutorials.dodatech.com'
  },
  plugins: []
};

siteMetadata stores global site information accessible via Graphql. The plugins array lists all plugins used by the site.

Source Plugins

Source plugins fetch data from external sources:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-filesystem',
      options: {
        name: 'content',
        path: `${__dirname}/content/`
      }
    },
    {
      resolve: 'gatsby-source-contentful',
      options: {
        spaceId: process.env.CONTENTFUL_SPACE_ID,
        accessToken: process.env.CONTENTFUL_ACCESS_TOKEN
      }
    }
  ]
};

Output: Files from the content/ directory become GraphQL nodes. Contentful data becomes available in the GraphQL data layer.

Transformer Plugins

Transformer plugins convert raw data into usable formats:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-filesystem',
      options: { name: 'posts', path: `${__dirname}/content/posts/` }
    },
    'gatsby-transformer-remark',  // Converts .md files to HTML
    'gatsby-transformer-sharp',    // Processes images for optimization
    'gatsby-plugin-sharp'          // Image processing utilities
  ]
};

Output: Markdown files in content/posts/ are transformed into HTML-rich MarkdownRemark nodes with processed images.

Site Plugins

Site plugins add features and optimizations:

module.exports = {
  plugins: [
    'gatsby-plugin-react-helmet',    // SEO meta tags
    'gatsby-plugin-sitemap',          // Auto-generate sitemap.xml
    'gatsby-plugin-manifest',         // PWA manifest.json
    'gatsby-plugin-offline',          // Service worker for offline access
    {
      resolve: 'gatsby-plugin-google-analytics',
      options: {
        trackingId: 'UA-XXXXXXXX-X'
      }
    }
  ]
};

Each plugin adds specific functionality. The order of plugins in the array sometimes matters (e.g., image plugins should come before their transformers).

Plugin Options

Many plugins accept options for customization:

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-manifest',
      options: {
        name: 'DodaTech Tutorials',
        short_name: 'DodaTech',
        start_url: '/',
        background_color: '#663399',
        theme_color: '#663399',
        display: 'minimal-ui',
        icon: 'src/images/icon.png'
      }
    },
    {
      resolve: 'gatsby-plugin-google-fonts',
      options: {
        fonts: ['Inter:400,700', 'Source Sans Pro:400,600']
      }
    }
  ]
};

Output: The manifest plugin generates a PWA manifest. The Google Fonts plugin adds font loading to the HTML head.

Common Mistakes

1. Installing plugins without adding to config: Installing a plugin with npm doesn't activate it. Add it to the plugins array in gatsby-config.js.
2. Wrong plugin order: Some plugins depend on others. gatsby-transformer-sharp requires gatsby-plugin-sharp to be listed first.
3. Hardcoding secrets in config: Use environment variables for API keys and tokens. Add .env files and access via Process.env.
4. Missing plugin options: Some plugins require mandatory options. Check the plugin's documentation for required fields.
5. Using incompatible plugin versions: Check plugin compatibility with your Gatsby version. Plugin pages document which Gatsby versions they support.

Practice Questions

1. What does a source plugin do? Answer: It fetches data from an external source (filesystem, CMS, API) and creates GraphQL nodes from it.

2. What does a transformer plugin do? Answer: It transforms raw data nodes into more usable formats, e.g., Markdown to HTML or images to optimized formats.

3. Where is site-wide metadata configured? Answer: In the siteMetadata object in gatsby-config.js. It's accessible via GraphQL as site.siteMetadata.

4. What is the minimum required plugin? Answer: None. But most sites use gatsby-source-filesystem and gatsby-plugin-react-helmet as a baseline.

Challenge

Configure a Gatsby site with three source plugins: gatsby-source-filesystem for local content, gatsby-source-graphql for an external API, and gatsby-source-contentful for a headless CMS.

Mini Project

Set up a new Gatsby site with: gatsby-source-filesystem, gatsby-transformer-remark, gatsby-plugin-sharp, gatsby-transformer-sharp, gatsby-plugin-react-helmet, and gatsby-plugin-sitemap. Verify each plugin works by checking the GraphiQL explorer and build output.

FAQ

What's Next

Learn about Gatsby Styling to style your Gatsby site with CSS Modules, global CSS, and CSS-in-JS libraries.