Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Community Plugin
View plugin on GitHub


IMPORTANT NOTE: This module is published for the forker’s own needs and WILL BE UNPUBLISHED when community gets the updated original package. So DO NOT INSTALL it into your business project and DO NOT RELY ON IT

NOTE: This plugin requires that your Wagtail site use the Wagtail-Grapple

library to build a compatible GraphQL endpoint. It does not work without a GraphQL endpoint.

Features: 🚀

  • Stitches your Wagtail GraphQL endpoint into the internal Gatsby one.
  • Simple router that matches your Django models to Gatsby templates.
  • Redirect support, making your Wagtail redirects work with sites hosted on Netlify & S3.
  • Out-of-the-box Wagtail Preview with realtime update as you type in the admin.
  • Gatsby Image Support 🔥
  • Incremental builds using GATSBY_EXPERIMENTAL_PAGE_BUILD_ON_DATA_CHANGES=true flag.

How to use


npm install @p.boiko/gatsby-source-wagtail


Add the package to your gatsby-config.js with the url to your Wagtail GQL endpoint:

  resolve: "@p.boiko/gatsby-source-wagtail",
  options: {
    url: "http://localhost:8000/graphql"

Available Config Options

Option Required Description Datatype Default
url Y The Wagtail GraphQL endpoint URL string null
websocketUrl N* The GraphQL subscriptions endpoint URL. It can be inferred during development, but needs to be set in a production env string N/A
headers N A JSON object of headers you want appended to all HTTP requests (Gatsby Build + Page Preview). json {}
fieldName N* The field name you want your remote endpoint accessible under. If you have multiple connections then you will need to provide a value for at least one of them. string wagtail
typeName N* The remote schema’s internal type name. When you have multiple connections, you will need to provide a value (just copy fieldName). string wagtail
isDefault N* A settings that tells the plugin which Wagtail GraphQL endpoint is the primary/default one. Used for preview and page generation. If you have multiple connections, you must choose which one you will generate pages from. Multiple site page generation is planned for future development. string true

Page Router

This source plugin provides a simple router that maps a Django model to a specific Gatsby template. Pass a JSON map to the function in your gatsby-node.js. The router also adds Wagtail Preview to your Gatsby site automagically! Now point your backend to the Gatsby site and everything will work: [How to link Wagtail & Gatsby](LINK TO BACKEND DOCS).

To map a Django model with the home.BlogPage ContentType to a template located at ./src/templates/blog.js

const { createWagtailPages } = require("@p.boiko/gatsby-source-wagtail/pages.js")

exports.createPages = ({ graphql, actions }) => {
  return createWagtailPages({
      "home.BlogPage": "templates/blog.js",
  }, graphql, actions, [])

The example template:


export default ({ data }) => {
  const { page } = data.wagtail

  return (
      <h1>{ page.title }</h1>

export const query = graphql`
  query($slug: String) {
    wagtail {
      page(slug: $slug) {
        ...on BlogPage {

Some page specific information is passed to page through the Gatsby context prop. The following variables are passed, thus are available in templates:

  • $id: Int
  • $slug: String
  • $url: String
  • $contentType: String


The plugin queries your Wagtail endpoint for any defined redirects and pass them to the Gatsby createRedirect function.

Image Fragments

You can take advantage of the Gatsby Image processing abilites by allowing Gatsby to download your images and progressively enhance them on the page.

import React from "react"
import { graphql } from "gatsby"
import Img from "gatsby-image"

export default function BlogTemplate({ data }) {
    const page = data.wagtail.page
    return (
            <Img fixed={page?.cover?.imageFile?.childImageSharp.square} />

export const query = graphql`
  query BlogIndexQuery($slug: String) {
    wagtail {
        page(slug: $slug) {
            ...on BlogPage {
                cover {
                    imageFile {
                        childImageSharp {
                            square: fixed(width: 300, height: 300) {

gatsby-transformer-sharp and gatsby-plugin-sharp are required for local image processing.

The following fragments work with @p.boiko/gatsby-source-wagtail:

  • GatsbyImageSharpFixed
  • GatsbyImageSharpFixed_noBase64
  • GatsbyImageSharpFixed_tracedSVG
  • GatsbyImageSharpFixed_withWebp
  • GatsbyImageSharpFixed_withWebp_noBase64
  • GatsbyImageSharpFixed_withWebp_tracedSVG
  • GatsbyImageSharpFluid
  • GatsbyImageSharpFluid_noBase64
  • GatsbyImageSharpFluid_tracedSVG
  • GatsbyImageSharpFluid_withWebp
  • GatsbyImageSharpFluid_withWebp_noBase64
  • GatsbyImageSharpFluid_withWebp_tracedSVG
  • GatsbyImageSharpFluidLimitPresentationSize

When previewing the page using Wagtail Preview, the image processing is mocked and the plugin will use the raw source files from your Wagtail’s media host. It should, however, respect the image dimension constraints.

© 2023 Gatsby, Inc.