DEV Community: Henrik Wirth

Introducing MobileUI

Henrik Wirth — Wed, 27 May 2020 16:58:06 +0000

After almost 10 years of research and 1.5 years of development, our team is proud to announce our first public release of MobileUI (0.4.1), a new software framework for cross-platform app development. 🍾🍾🍾

At NeverNull, we have more than 20 years experience as app developers, software engineers, consultants, software lecturers and trainers. During this time, we have learned a lot about the good and the bad parts of cross-platform app development with a huge variety of frameworks and programming languages.

We think, the time has come to take these findings and build a product that combines the good parts leaving out the bad ones. Our vision for MobileUI is to become the number one solution for cross-platform app development with Java and/or Kotlin. One codebase, a unique developer experience, a great toolchain and the full native app experience.

We are very excited about the outcome - and hope you are too! The following article gives you some details about the product. Get your own copy here: www.mobileui.dev

What is MobileUI?

Java-Based Cross-Platform Apps with Native Experience

MobileUI is a Java-based cross-platform framework that offers a native UI component library and unique layout system for iOS and Android.

MobileUI allows you to write fully native apps in Java and Kotlin, without touching languages like Objective-C or Swift. Why Java? Java is a great way to combine easy development and a huge ecosystem of libraries and tools with fulfilling maybe the number one requirements on mobile: Performance. With MobileUI's system, all Java code is ahead-of-time compiled which brings huge benefits in regard to execution time and memory consumption.

While you can rely on Java's cross-platform APIs, you can also access all native SDKs for Android and iOS from the same codebase. This is thanks to the availability of the Android Runtime SDK and the RoboVM Native Bridge (Bro). It is great for all cases, where our cross-platform framework does not (yet) contain an abstraction or plugin for a platform-specific function. You don't have to switch IDEs, tools or programming language to add a new feature. In our experience, the latter happens a lot with cross-platform frameworks like React Native, Flutter or Ionic, that only give you SDK access through native plugins.

Layouting and Styling with Ease

MobileUI uses Android's Layout System to arrange platform-native widgets on the screen. We have ported Android Views to iOS from Android's original source code (Following a hint by Chuck Norris, who already ran Android apps on iOS in 2005. Thanks Chuck! 💪). And with a big smile, we recognized that this approach is amazingly 🚀fast 🚀! Because Android layouts have been optimized to support devices with many different form factors, building iOS apps with it works like a charm.

Have you ever understood Android's style system in depth? No? We neither 😬! That's why

MobileUI XML layout files are styled with CSS. Just as in HTML, you can include .css files or write style directly to the layout. Checkout this code snippet. It should be very familiar to everyone who has ever built an HTML page:

<Layout xmlns="urn:nevernull:mobileui:layout">
    <style href="style.css"/>
    <style>
        .CustomButton {
            textColor: white;
            backgroundColor: #6111B1;
        }
    </style>
    <LinearLayout width="fill_parent"
                  height="fill_parent"
                  orientation="vertical">
        <Button class="CustomButton"
                onClick="#{onOpenUrlClicked()}"
                text="Yeah, take me to the candy shop"
        />
    </LinearLayout>
</Layout>

There is also the possibility of using dynamic CSS and variables through MobileUI's super-fast template engine. You can implement rich design systems and custom themes - from dark to light to super-awesome!

And did we mention MobileUI's Data Binding? Glue Java code and layout together with expressions #{justLikeThis}. Or simply start with your layout and later add the bindings. With this separation of concerns when building your apps, you can present high-fidelity prototypes early in the development process. This is super-valuable when talking to customers and product owners 😎.

Extensibility is key

Since you have access to all native SDKs, you are not constrained to the components we offer. Build, share and reuse your own abstractions and improve your developer experience.

We know that it is a good idea to use component systems as soon as your apps become more complex. That is, why we ship MobileUI's Purple Edition with a dependency injection framework that is a perfect fit for mobile. It is based on Micronaut and makes extending your app with platform-specific components super-easy. MobileUI Inject is used as the basis for our Plugin System which allows you to integrate plugins into your app with a few lines of code. Read more on this in coming blog posts.

Instant Live Preview

Let's face it: Slow build cycles thwart you when developing your apps ⌛. One of the most stressful things is restarting the whole app only to see a few pixels more padding in your layout or the UI being rendered on a second device.

While we cannot completely eliminate build cycles – especially for Java compilation on iOS – we do our best to make them unnecessary or much faster.

That is why we provide you with the Live Preview feature that comes with the MobileUI Plugin for Android Studio. The Live Preview pushes layout changes to your app in real-time. With this approach, you can modify the layout while the app is running (and keeping state). This allows fast iteration cycles, increases productivity and safes a lot of time. Don't believe it works? Watch and try!

Extensive Documentation & Support

Diving into app development with a new framework is difficult without an excellent documentation. One of our main goals is to bring you high quality tutorials, how-tos and references for all MobileUI features on docs.mobileui.dev. And if you are stuck, we assist you on our Spectrum Channel.

It is great that MobileUI apps are actually native apps with full SDK access. You find a huge amount of examples for solutions on Android and iOS on the Internet. You can easily apply them in your MobileUI apps without reinventing wheels. We help you, if something should not work out as expected.

Try it out with our MobileUI Gallery

That's it for now. Are you curious, if this works? Try MobileUI today and find out! Get MobileUI Free at

www.mobileui.dev

... and let us know what you think! We appreciate your feedback!

PageBuilder with ACF Flexible Content - Guide to Gatsby WordPress Starter Advanced with Previews, i18n and more

Henrik Wirth — Thu, 19 Dec 2019 13:38:05 +0000

If you are still following this series, you learned a lot of basics in the previous parts and are pretty well informed about the creation of Gatsby sites with WordPress.

This part will introduce a lot of new functionality, ideas and concepts. Therefore, I decided to make a video, where I will talk you through all the steps mentioned in this written tutorial. I hope this will help you to understand what is happening and why.

Note: We don't have any proper styling in place yet. So I will keep things as simple as possible. I want to refactor everything later on with theme-ui and emotion.

Now let's move forward and build a page builder with Advanced Custom Field's Flexible Content field.

Install WordPress Plugins 💾
Create ACF fields and Content ✏️
- 1.) Create Flexible Content field
- 2.) Create Layouts inside the Flexible Content field
- 3.) Update your Pages
- 4.) Checkout the Schema
Add layouts to Gatsby 📰
- 1.) Add Hero layout
- 2.) Add TextBlock layout
- 3.) Add data to our page queries
  - Update pages data.js
  - Update createPages.js
  - Create utility function getAllLayoutsData
- 4.) Add AllLayouts component
- 5.) Update Page template
Improve performance through Template-String technique 🎩
- 1.) Add more utiliy functions
- 2.) Add lodash.uniqby and lodash.isempty
- 3.) Add/update createPages.js
- 4.) Add string based template
Explanation Video 🎥
Final Thoughts 🏁
What's Next ➡️

Install WordPress Plugins 💾

1.) Install Advanced Custom Fields PRO and activate your license. We need the PRO version if we want to use the flexible content field.

2.) Install and activate Classic Editor editor from the plugin admin interface. It will help you to only show the page builder fields and hide the content editor where we don't need it.

3.) You can download the .zip files of the wp-graphql-acf repository and install it through WP-Admin or just navigate to your plugin folder and do a git clone like so:

git clone https://github.com/wp-graphql/wp-graphql-acf

The WPGraphQL for Advanced Custom Fields is the plugin, that exposes the ACF fields to the GraphQL Schema. There is some good documentation of it here.

Create ACF fields and Content ✏️

We will add a flexible content field and 2 layouts to start with.

Note: If you want to skip this parts 1.) and 2.), I prepared a .json export for the 2 layouts. Find it right here.

1.) Create Flexible Content field

As you can see we called the field group Page Builder
We added one field of type Flexible Content with the name layouts
In the Location settings we add the rule Post type is equal to Page, so the page builder will be only visible for our pages, but not our posts.

At Hide on screen make sure you selected Content Editor. This will hide the default editor on the pages where we use the page builder.
When you scroll down you see GraphQL Field Name in the Settings tab. Make sure to give it a camelCase name. This will be the field name for the GraphQL schema.
- We call it pageBuilder

2.) Create Layouts inside the Flexible Content field

Always make sure to have Show in GraphQL to be turned on.
Inside the flexible content field we add layouts with some fields like in the picture above. We add two for now: Hero and TextBlock
The name of the layout usually is something with underscore, like text_block. This will then transform into textBlock in your GraphQL schema.

3.) Update your Pages

Now that we have the ACF fields setup, we need to update our pages.

Delete the content in the normal Gutenberg blocks, if there has been content before.
At the bottom open the Page Builder tab and Add Row
- Add your blocks and fill in some data.
I'm using the image for the Hero block and still leave it in thew featuredImage. This will give me the option to use a different featuredImage for social previews if I want to do so, later on.

4.) Checkout the Schema

Run your Gatsby with yarn clean && yarn develop and got to http://localhost:8000/___graphql to see what happend int the schema.

If you are using the same ACF layouts like me, you should be able to query the following:

query GET_LAYOUTS {
  wpgraphql {
    pages {
      nodes {
        pageBuilder {
          layouts {
            ... on WPGraphQL_Page_Pagebuilder_Layouts_Hero {
              text
              fieldGroupName
              textColor
              image {
                sourceUrl
              }
            }
            ... on WPGraphQL_Page_Pagebuilder_Layouts_TextBlock {
              backgroundColor
              fieldGroupName
              textColor
              text
            }
          }
        }
      }
    }
  }
}

Check the results and get familiar with your schema.

Add layouts to Gatsby 📰

Let's start by adding our layout components. The folder structure for our layouts will look like so:

1.) Add Hero layout

// src/layouts/Hero/Hero.js

import React from "react"
import FluidImage from "../../components/FluidImage"

const Hero = ({ image, text, textColor }) => {

  return (
    <section style={{ position: "relative" }}>
      <FluidImage image={image} style={{marginBottom: '15px'}}/>
      <p style={{
        color: textColor,
        position: "absolute",
        top: "50%",
        left: "50%",
        transform: "translate(-50%, -50%)",
        fontSize: '40px',
        textAlign: 'center',
        paddingTop:'80px',
        lineHeight: 1,
      }}>{text}</p>

    </section>
  )
}

export default Hero

A simple React component with some styling.

// src/layouts/Hero/Hero.data.js

module.exports = () => {
  return `
      ... on WPGraphQL_Page_Pagebuilder_Layouts_Hero {
          fieldGroupName
          image {
              sourceUrl
              altText
              imageFile {
                  childImageSharp {
                      fluid(maxHeight: 400, quality: 90, cropFocus: CENTER) {
                          ...GatsbyImageSharpFluid_tracedSVG
                      }
                  }
            }
          }
          text
          textColor
      }
  `
}

WPGraphQL_Page_Pagebuilder_Layouts_Hero is the UnionType name of this layout. As we can have multiple layouts, GraphQL union types (more here), help us to say: "If the data is of a certain type, then query with the following fields".
As you can see this time we use a function to export the data. This will come in handy later, if we need to adjust the query, based on certain variables.

// src/layouts/Hero/index.js

export { default } from './Hero';

This simply helps us to make our component call a bit more elegant.
Instead of importing like import Hero from "../layouts/Hero/Hero", we can omit the last /Hero and do import Hero from "../layouts/Hero instead.

2.) Add TextBlock layout

// src/layouts/TextBlock/TextBlock.js

import React from "react"

const TextBlock = ({ text, textColor, backgroundColor }) => {

  return (
    <section style={{backgroundColor: backgroundColor}}>
      <div style={{
        color: textColor,
        padding: '30px'
      }}>
        <div style={{
          color: textColor,
          textAlign: 'left',
        }} dangerouslySetInnerHTML={{__html: text}} />
      </div>

    </section>
  )
}

export default TextBlock

// src/layouts/TextBlock/TextBlock.data.js

module.exports = () => {
  return `
      ... on WPGraphQL_Page_Pagebuilder_Layouts_TextBlock {
          fieldGroupName
          text
          textColor
          backgroundColor
      }
  `
}

// src/layouts/TextBlock/index.js

export { default } from './TextBlock';

TextBlock should be self-explanatory.

3.) Add data to our page queries

Now that we defined the data for the different layouts, we need to add it to our main query.

Update pages data.js

// src/templates/page/data.js

const PageTemplateFragment = (layouts) => `
    fragment PageTemplateFragment on WPGraphQL_Page {
        id
        title
        pageId
        content
        uri
        slug
        isFrontPage
        featuredImage {
            sourceUrl
            altText
            imageFile {
                childImageSharp {
                    fluid(maxHeight: 400, maxWidth: 800, quality: 90, cropFocus: CENTER) {
                        ...GatsbyImageSharpFluid_tracedSVG
                    }
                }
            }
        }
        pageBuilder {
            layouts {
                ${layouts}
            }
        }
    }
`

module.exports.PageTemplateFragment = PageTemplateFragment

We update our data to be a function and pass it the layouts strings.
This helps us to dynamically render all the queries into our main query.

Update createPages.js

// create/createPages.js

const { getAllLayouts } = require("./utils")

... 1.)

const GET_PAGES = (layouts) => `
    ${FluidImageFragment}
    ${PageTemplateFragment(layouts)}

    query GET_PAGES($first:Int $after:String) {
        wpgraphql {
            pages(
                first: $first
                after: $after
                # This will make sure to only get the parent nodes and no children
                where: {
                    parent: null
                }
            ) {
                pageInfo {
                    hasNextPage
                    endCursor
                }
                nodes {                
                  ...PageTemplateFragment
                }
            }
        }
    }
`

... 2.)

module.exports = async ({ actions, graphql, reporter }, options) => {

  /**
   * Get all layouts data as a concatenated string
   */
  const layoutsData = getAllLayoutsData()

... 3.)

  const fetchPages = async (variables) =>
    /**
     * Fetch pages using the GET_PAGES query and the variables passed in.
     */
    await graphql(GET_PAGES(layoutsData), variables).then(({ data }) => {

...

This snippet is not complete. Refer to this file (createPages.js), if you want to see the whole file.

I divided the file in 3 parts, where changes take place.

We rewrite GET_PAGES to be a function and pass it layouts. Then we pass layouts further down to our template fragment like: PageTemplateFragment(layouts).
In the second part we call our utility function getAllLayoutsData(). We will add this utility function in the next step.
In part 3 we change the GET_PAGES call to GET_PAGES(layoutsData) to pass down the layout data string.

Create utility function getAllLayoutsData

While we could import all the layouts data by hand and then combine the string before we pass it to our query, I wanted a way to automate/abstract the creation of the query string. Therefore this function uses the glob pattern to get all layouts/**/*.data.js and combines them to have a query ready string.

First, add the glob module:

yarn add glob

Then add utils.js to our create folder:

// create/utils.js

const path = require("path")

module.exports.getAllLayoutsData = () => {
  const glob = require("glob")

  let allLayoutsString = ""

  const fileArray = glob.sync("./src/layouts/**/*.data.js")

  fileArray.forEach(function(file) {
    let queryStringFunction = require(path.resolve(file))
    allLayoutsString = allLayoutsString + " \n " + queryStringFunction()
  })

  return allLayoutsString
}

So we create a file array with the glob.sync call at first.
Then, for each file, we require the file which essentially is an exported function (our *.data.js).
At last, we concatenate all the strings and return allLayoutsString. This will hold all our layouts data query strings.

I find, this comes in so handy!!!

4.) Add AllLayouts component

Now we need a way to decide, which component should be rendered. To make this simple first, we introduce an AllLayouts component, that depending on the fieldGroupName (type) of the layout, decides what to render.

// src/components/AllLayouts.js

import React from "react"
import Hero from "../layouts/Hero"
import TextBlock from "../layouts/TextBlock"

const AllLayouts = ({ layoutData }) => {

  const layoutType = layoutData.fieldGroupName

  /**
   * Default component
   */
  const Default = () => <div>In AllLayouts the mapping of this component is missing: {layoutType}</div>

  /**
   * Mapping the fieldGroupName(s) to our components
   */
  const layouts = {
    page_Pagebuilder_Layouts_Hero: Hero,
    page_Pagebuilder_Layouts_TextBlock: TextBlock,
    page_default: Default
  }

  /**
   * If layout type is not existing in our mapping, it shows our Default instead.
   */
  const ComponentTag = layouts[layoutType] ? layouts[layoutType] : layouts['page_default']

  return (
    <ComponentTag {...layoutData} />
  )
}

export default AllLayouts

This component simply takes in the layoutData and depending on the fieldGroupName renders the component, that we have assigned in the mapping.
Note: The fieldGroupName starts with a lowercase letter.

5.) Update Page template

Now that our data pipeline has been handled and we have a component, that dynamically renders the right component, we only need to add it to our template.

// src/templates/page/index.js

import React from "react"

import Layout from "../../components/Layout"
import SEO from "../../components/SEO"
import AllLayouts from "../AllLayouts"


const Page = ({ pageContext }) => {
const {
  page: { title, pageBuilder },
} = pageContext

const layouts = pageBuilder.layouts || []

return (
  <Layout>
    <SEO title={title}/>
    <h1> {title} </h1>

    {
      layouts.map((layout, index) => {
        return <AllLayouts key={index} layoutData={layout} />
      })
    }

  </Layout>
)
}

export default Page

We simply add the AllLayouts component and add the variable pageBuilder coming from our pageContext.
const layouts = pageBuilder.layouts || [] helps to have a fallback array, if there are no layouts defined. Then our mapping we just render to nothing and we don't end up with errors.
Then we only need to map through our layouts and render the AllLayouts component, passing down the layoutData.

Eh voilà, we have a page builder. We can define layouts/components in our WordPress backend with ACF and dynamically render React components, depending on the type.

Improve performance through Template-String technique 🎩

I won't explain too much detail in this written part. Please watch the video for it.

One problem with our AllLayouts component we have, is, that the way we implemented it now, on every page, we import all layout components we have, even if we don't need them.

This is fine if we have just a few components, but imagine with have 50 different layouts in our page builder. We don't want them all imported on every page.

For that we will use a little hacky, but in my opinion efficient way to generate templates out of template strings.

1.) Add more utility functions

// create/utils.js

/**
 * Creates files based on a template string.
 *
 * @param {string} templateCacheFolderPath - Path where the temporary files should be saved.
 * @param {string} templatePath - Path to the file holding the template string.
 * @param {string} templateName - Name of the temporary created file.
 * @param {object[]} imports - An array of objects, that define the layoutType, componentName and filePath.
 * @returns {Promise<>}
 */
module.exports.createTemplate = ({ templateCacheFolderPath, templatePath, templateName, imports }) => {
  return new Promise((resolve) => {
    const fs = require("fs")

    const template = require(templatePath)
    const contents = template(imports)

    fs.mkdir(templateCacheFolderPath, { recursive: true }, (err) => {
      if (err) throw "Error creating template-cache folder: " + err

      const filePath = templateCacheFolderPath + "/" + ((templateName === "/" || templateName === "") ? "home" : templateName) + ".js"

      fs.writeFile(filePath, contents, "utf8", err => {
        if (err) throw "Error writing " + templateName + " template: " + err

        console.log("Successfully created " + templateName + " template.")
        resolve()
      })
    })
  })
}

/**
 * Creates pages out of the temporary created templates.
 */
module.exports.createPageWithTemplate = ({ createTemplate, templateCacheFolder, pageTemplate, page, pagePath, mappedLayouts, createPage, reporter }) => {

  /**
   * First we create a new template file for each page.
   */
  createTemplate(
    {
      templateCacheFolderPath: templateCacheFolder,
      templatePath: pageTemplate,
      templateName: "tmp-" + page.slug,
      imports: mappedLayouts,
    }).then(() => {

    /**
     * Then, we create a gatsby page with the just created template file.
     */
    createPage({
      path: pagePath,
      component: path.resolve(templateCacheFolder + "/" + "tmp-" + page.slug + ".js"),
      context: {
        page: page,
      },
    })

    reporter.info(`page created: ${pagePath}`)
  })
}

Most of the things should be explained with the comments I added. Basically we create new template files based on a template-string file.
Then we create the pages, based on that generated file.

2.) Add layoutMapping.js

module.exports = {
  page_Pagebuilder_Layouts_Hero: "Hero",
  page_Pagebuilder_Layouts_TextBlock: "TextBlock",
}

3.) Add `lodash.uniqby` and `lodash.isempty`

yarn add lodash.uniqby lodash.isempty

4.) Add/update createPages.js

First the top part:

// create/createPages.js

const _uniqBy = require("lodash.uniqby")
const _isEmpty = require("lodash.isempty")

const { getAllLayoutsData, createTemplate, createPageWithTemplate } = require("./utils")

const filePathToComponents = "../src/layouts/"
const templateCacheFolder = ".template-cache"
const layoutMapping = require("./layouts")
const pageTemplate = require.resolve("../src/templates/page/template.js")

Then further down:

// create/createPages.js

wpPages && wpPages.map((page) => {
      let pagePath = `${page.uri}`

      /**
       * If the page is the front page, the page path should not be the uri,
       * but the root path '/'.
       */
      if (page.isFrontPage) {
        pagePath = "/"
      }

      /**
       * Filter out empty objects. This can happen, if for some reason you
       * don't query for a specific layout (UnionType), that is potentially
       * there.
       */
      const layouts = page.pageBuilder.layouts.filter(el => {
        return !_isEmpty(el)
      })

      let mappedLayouts = []

      if (layouts && layouts.length > 0) {
        /**
         * Removes all duplicates, as we only need to import each layout once
         */
        const UniqueLayouts = _uniqBy(layouts, "fieldGroupName")

        /**
         * Maps data and prepares object for our template generation.
         */
        mappedLayouts = UniqueLayouts.map((layout) => {
          return {
            layoutType: layout.fieldGroupName,
            componentName: layoutMapping[layout.fieldGroupName],
            filePath: filePathToComponents + layoutMapping[layout.fieldGroupName],
          }
        })
      }

      createPageWithTemplate({
        createTemplate: createTemplate,
        templateCacheFolder: templateCacheFolder,
        pageTemplate: pageTemplate,
        page: page,
        pagePath: pagePath,
        mappedLayouts: mappedLayouts,
        createPage: createPage,
        reporter: reporter,
      })
    })

5.) Add string based template

In JavaScript you can use template strings to pass down arguments or logic in general to your string. We make use of that to literally create a template based on our src/templates/page/index.js component.

module.exports = (imports) => {
  return`
// This is a temporary generated file. Changes to this file will be overwritten eventually!
import React from "react"

import Layout from "../src/components/Layout"
import SEO from "../src/components/SEO"

// Sections
${imports.map(({ componentName, filePath }) => `import ${componentName} from '${filePath}';`).join('\n')}

const Page = ({ pageContext }) => {
  const {
    page: { title, pageBuilder },
  } = pageContext

  const layouts = pageBuilder.layouts || []

  return (
    <Layout>
      <SEO title={title}/>
      <h1> {title} </h1>

      {
        layouts.map((layout, index) => {
          ${imports.map(({ componentName, layoutType }) => {
            return `
              if (layout.fieldGroupName === '${layoutType}') {
                  return <${componentName} {...layout} key={index} />;
              }
            `
          }).join('\n')}
        })
      }

    </Layout>
  )
}

export default Page
  `
}

What we do here, is to decide what components actually get imported. We only want to import components, that are part of the created page. Not more not less.

Explanation Video 🎥

This tutorial can be a lot to take in and it is hard for me to write a super detailed explanation of everything down. So I decided to record a video, where I would go through the steps mentioned in this tutorial and verbally explain what my thoughts to the implementation choices are.

I hope I find the time to finish the video soon. Stay tuned.

-> Video - Coming soon <-

Final Thoughts 🏁

Boom, now we have a way to dynamically render blocks created through ACF flexible content layouts. Surely this is not a full-fledged page builder yet, as we we can't use layouts inside layouts. But, we can add and order section by section, which for most use-cases, should be more than enough. This approach would now allow you to create reusable layouts and therefore is a powerful way to create your pages.

There is also a way to use the Gutenberg blocks with the wp-graphql-gutenberg plugin created by Peter Pristas. While this is a valid way to work with WordPress, I'm not the biggest fan of how to implement Gutenberg blocks and work with the editor. This might change though, with how things develop.

Checkout how the site looks now here: https://gatsby-starter-wordpress-advanced.netlify.com/

Find the code base here: https://github.com/henrikwirth/gatsby-starter-wordpress-advanced/tree/tutorial/part-7

What's Next ➡️

Coming up soon: Part 8 - Internationalization

How to handle Images and make use of gatsby-image - Guide to Gatsby WordPress Starter Advanced with Previews, i18n and more

Henrik Wirth — Sat, 07 Dec 2019 13:01:04 +0000

After the previous part we have a blog ready with featured images. Now, how do we get these images to be local and do some more magic with them? Gatsby comes with a super helpful plugin called gatsby-image for image processing at build time.

In this part I will show you, how you can make use of gatsby-images superpowers and deliver your images in a static fashion.

Add Images to WordPress pages 💻
Make use of gatsbyimage 📷
- 1.) Add Resolver to Gatsby
- 2.) Add fluid Image fragment
- 3.) Add fragment to createPages.js and createPosts.js
  - Update createPages.js
  - Add PageTemplateFragment
  - Update createPosts.js
  - Update PostTemplateFragment and BlogPreviewFragment
- 4.) Update Image.js to FluidImage.js
- 5.) Update page, blog and post template
Post Inline images 📝
Final Thoughts 🏁
What's Next ➡️

Add Images to WordPress pages 💻

After adding images to the posts, let's also add some featured images to our pages.

Now run gatsby develop and checkout http://localhost:8000/___graphql.

Run:

query GETPAGES {
  wpgraphql {
    pages {
      nodes {
        title
        uri
        featuredImage {
          sourceUrl
        }
      }
    }
  }
}

You should see something like this:

As you can see we get an absolute path to the featured images with sourceUrl. What we want instead though, is a local image, with the abilities to use gatsby-image's filters.

I already wrote an article about this, but for the sake of integrity of the tutorial series, I gonna add the information here too.

Make use of gatsby-image 📷

We gonna make use of Gatsby's abilities to add custom resolvers, to customize the schema, so that WordPress images get handled as local Files. Gatsby will then automatically treat the images as files, that are getting processed by gatsby-image.

1.) Add Resolver to Gatsby

// gatsby-node.js

const { createRemoteFileNode } = require(`gatsby-source-filesystem`)

exports.createResolvers = async (
  {
    actions,
    cache,
    createNodeId,
    createResolvers,
    store,
    reporter,
  },
) => {
  const { createNode } = actions

  await createResolvers({
    WPGraphQL_MediaItem: {
      imageFile: {
        type: "File",
        async resolve(source) {
          let sourceUrl = source.sourceUrl

          if (source.mediaItemUrl !== undefined) {
            sourceUrl = source.mediaItemUrl
          }

          return await createRemoteFileNode({
            url: encodeURI(sourceUrl),
            store,
            cache,
            createNode,
            createNodeId,
            reporter,
          })
        },
      },
    },
  })
}

WPGraphQL_MediaItem: This depends on your config. It starts with the typeName of your gatsby-source-graphql.
createRemoteFileNode gives you the ability to pull in remote files and automatically adds them to your schema.
imageFile: will be the type you can query (see below).
type: 'File': will add the MediaItems as Files, which is great, because now gatsby-image can make use of it.
url: encodeURI(sourceUrl): Here we encode the Url coming from WordPress, to make sure it is parsed correctly even if the image paths include umlauts.

2.) Add fluid Image fragment

As in the previous part. We will add some fragments, to our queries. First let's add a fragment.js inside our template folder like this:

// src/templates/fragments.js

const FluidImageFragment = `
    fragment GatsbyImageSharpFluid_tracedSVG on ImageSharpFluid {
        tracedSVG
        aspectRatio
        src
        srcSet
        sizes
    }
`

module.exports.FluidImageFragment = FluidImageFragment

This fragment will serve for our fluid images with traced SVG abilities.

3.) Add fragment to createPages.js and createPosts.js

We need to add these fragments to our page and post queries.

Update createPages.js

// create/createPages.js

const pageTemplate = require.resolve("../src/templates/page/index.js")

const {FluidImageFragment} = require("../src/templates/fragments")
const {PageTemplateFragment} = require("../src/templates/page/data")

const GET_PAGES = `
    ${FluidImageFragment}
    ${PageTemplateFragment}

    query GET_PAGES($first:Int $after:String) {
        wpgraphql {
            pages(
                first: $first
                after: $after
                # This will make sure to only get the parent nodes and no children
                where: {
                    parent: null
                }
            ) {
                pageInfo {
                    hasNextPage
                    endCursor
                }
                nodes {                
                  ...PageTemplateFragment
                }
            }
        }
    }
`

// This file has more content. Check the repo for the rest of the code.

As you can see we add our FluidImageFragment and then parse it inside our query string.
Also new is the PageTemplateFragment. We will add that fragment now.

Add PageTemplateFragment

In the last tutorial part we already added the posts data.js. Now we also do the same for pages with the addition of our image fragment.

// src/templates/page/data.js

const PageTemplateFragment = `
    fragment PageTemplateFragment on WPGraphQL_Page {
        id
        title
        pageId
        content
        uri
        isFrontPage
        featuredImage {
            sourceUrl
            altText
            imageFile {
                childImageSharp {
                    fluid(maxHeight: 400, maxWidth: 800, quality: 90, cropFocus: CENTER) {
                        ...GatsbyImageSharpFluid_tracedSVG
                    }
                }
            }
        }
    }
`

module.exports.PageTemplateFragment = PageTemplateFragment

featuredImage now has the imageFile field added, thats coming form our gatsby-image implementation with the resolver.
We can make use of our GatsbyImageSharpFluid_tracedSVG fragment, as we added it before.

Note: Usually gatsby-image would add these fragments already, but not in our build scripts. If you would only use the fragments inside page or static queries, you would already have these fragments available.

Update createPosts.js

// create/createPosts.js

const {
  PostTemplateFragment,
  BlogPreviewFragment,
} = require("../src/templates/post/data.js")

const {FluidImageFragment} = require("../src/templates/fragments")

const { blogURI } = require("../globals")

const postTemplate = require.resolve("../src/templates/post/index.js")
const blogTemplate = require.resolve("../src/templates/post/blog.js")

const GET_POSTS = `
    # Here we make use of the imported fragments which are referenced above
    ${FluidImageFragment}
    ${PostTemplateFragment}
    ${BlogPreviewFragment}

    query GET_POSTS($first:Int $after:String) {
        wpgraphql {
            posts(
                first: $first
                after: $after
                # This will make sure to only get the parent nodes and no children
                where: {
                    parent: null
                }
            ) {
                pageInfo {
                    hasNextPage
                    endCursor
                }
                nodes {           
                    uri     

                    # This is the fragment used for the Post Template
                    ...PostTemplateFragment

                    #This is the fragment used for the blog preview on archive pages
                    ...BlogPreviewFragment
                }
            }
        }
    }
`

// This file has more content. Check the repo for the rest of the code.

Same as above. We add the FluidImageFragment to our query.

Update PostTemplateFragment and BlogPreviewFragment

// src/templates/post/data.js

const PostTemplateFragment = `
    fragment PostTemplateFragment on WPGraphQL_Post {
        id
        postId
        title
        content
        link
        featuredImage {
            sourceUrl
            altText
            imageFile {
                childImageSharp {
                    fluid(maxHeight: 400, maxWidth: 800, quality: 90, cropFocus: CENTER) {
                        ...GatsbyImageSharpFluid_tracedSVG
                    }
                }
            }
        }
        categories {
            nodes {
                name
                slug
                id
            }
        }
        tags {
            nodes {
                slug
                name
                id
            }
        }
        author {
            name
            slug
        }
    }
`

const BlogPreviewFragment = `
    fragment BlogPreviewFragment on WPGraphQL_Post {
        id
        postId
        title
        uri
        date
        slug
        excerpt
        content
        featuredImage {
            sourceUrl
            altText
            imageFile {
                childImageSharp {
                    fluid(maxHeight: 400, maxWidth: 800, quality: 90, cropFocus: CENTER) {
                        ...GatsbyImageSharpFluid_tracedSVG
                    }
                }
            }
        }
        author {
            name
            slug
        }
    }
`

module.exports.PostTemplateFragment = PostTemplateFragment
module.exports.BlogPreviewFragment = BlogPreviewFragment

You might notice, that there is potential of abstraction here. For simplicity I'll leave it like this for now.

4.) Update Image.js to FluidImage.js

Now we will need to update our image component. For now we are only using fluid images and therefore we gonna rename our Image.js to FluidImage.js and update it like so:

// src/components/FluidImage.js

const FluidImage = ({ image, withFallback = false, ...props }) => {
  const data = useStaticQuery(graphql`
      query {
          fallbackImage: file(relativePath: { eq: "fallback.svg" }) {
              publicURL
          }
      }
  `)

  /**
   * Return fallback Image, if no Image is given.
   */
  if (!image) {
    return withFallback ? <img src={data.fallBackImage.publicURL} alt={"Fallback"} {...props}/> : null
  }

  if (image && image.imageFile) {
    return <GatsbyImage fluid={image.imageFile.childImageSharp.fluid} alt={image.altText} {...props}/>
  }

  return <img src={image.sourceUrl} alt={image.altText} {...props}/>
}

export default FluidImage

If now image, we show a fallBackImage or render no element at all.
If we do have an image and it has the imageFile field, we know it has been processed by our resolver and therfore we can use GatsbyImage to handle it.
If we do have an image, but no imageFile, then it will default to using a normal img tag with the sourceUrl as source.

This will guarantee us, that if for some reason, we are using dynamic queries and don't have the preprocessing abilities, that we will still have a valid output of the images. This will come in handy, if we are creating previews later on.

5.) Update page, blog and post template

// src/templates/page/index.js

import React from "react"

import Layout from "../../components/Layout"
import SEO from "../../components/SEO"
import FluidImage from "../../components/FluidImage"


const Page = ({ pageContext }) => {
  const {
    page: { title, content, featuredImage },
  } = pageContext

  return (
    <Layout>
      <SEO title={title}/>

      <FluidImage image={featuredImage} style={{ marginBottom: "15px" }}/>

      <h1> {title} </h1>
      <div dangerouslySetInnerHTML={{ __html: content }}/>
    </Layout>
  )
}

export default Page

// src/templates/post/blog.js

import React from "react"
import Layout from "../../components/Layout"
import PostEntry from "../../components/PostEntry"
import Pagination from "../../components/Pagination"
import SEO from "../../components/SEO"

const Blog = ({ pageContext }) => {
  const { nodes, pageNumber, hasNextPage, itemsPerPage, allPosts } = pageContext

  return (
    <Layout>
      <SEO
        title="Blog"
        description="Blog posts"
        keywords={[`blog`]}
      />

      {nodes && nodes.map(post => <PostEntry key={post.postId} post={post}/>)}

      <Pagination
        pageNumber={pageNumber}
        hasNextPage={hasNextPage}
        allPosts={allPosts}
        itemsPerPage={itemsPerPage}
      />
    </Layout>
  )
}

export default Blog

// src/templates/post/index.js

import React from "react"

import Layout from "../../components/Layout"
import SEO from "../../components/SEO"
import FluidImage from "../../components/FluidImage"


const Post = ({ pageContext }) => {
  const {
    post: { title, content, featuredImage },
  } = pageContext

  return (
    <Layout>
      <SEO title={title}/>

      <FluidImage image={featuredImage} style={{ marginBottom: "15px" }}/>

      <h1> {title} </h1>
      <div dangerouslySetInnerHTML={{ __html: content }}/>
    </Layout>
  )
}

export default Post

Post Inline images 📝

One thing I wanted to mention shortly, that there is a nice plugin, that can help you to get inline images as local static images. So for example you are using the normal Gutenberg in your posts, then you want images, that you included in the post also to be downloaded at build time and stored locally.

I won't implement this here, as I won't rely on Gutenberg and rather use Advanced Custom Fields - Flexible Content field in the upcoming parts.

But checkout gatsby-wpgraphql-inline-images if you need this functionality.

Final Thoughts 🏁

Checkout how the site looks now:

PS: That's actually me walking on a highline (slackline) in this picture 😱. Such a fun sport.

With this part I would say, we have a very solid base for everything that is coming next. The basic functionalities of a WordPress site are implemented and we can now start think about how we dynamically design our content.

Find the code base here: https://github.com/henrikwirth/gatsby-starter-wordpress-advanced/tree/tutorial/part-6

What's Next ➡️

We'll dive into Advanced Custom Fields Flexible Content field and create a page-builder like experience with it. This will open us the doors, to dynamically create UI elements filled with content.

Part 7 - PageBuilder with ACF Flexible Content

Blog with Pagination - Guide to Gatsby WordPress Starter Advanced with Previews, i18n and more

Henrik Wirth — Fri, 06 Dec 2019 21:04:40 +0000

I figured, for further parts of the tutorial, it will make sense to implement the Blog now. So this part will show you how to create a Blog (post overview) with pagination.

I renamed all components to start with a capital letter. Checkout this commit to see the refactoring I did and what changed. Or, just dive into the tutorial first and compare later.

Add content to WordPress 💻
- 1.) Create posts
- 2.) Add Menu Link
Implement Blog components 💾
- 1.) Add globals.js
- 2.) Create blog.js
- 3.) Create PostEntry.js
- 4.) Create Image.js
- 5.) Create Pagination.js
Adjust Post/Blog Creation 📓
- 1.) Add data.js
- 2.) Adjust createPosts.js
Final Thoughts 🏁
What's Next ➡️

Add content to WordPress 💻

1.) Create posts

Let's add some posts. Preferably more than 10, so that we can see our pagination in action later on. Make sure to have some posts with featured images.

2.) Add Menu Link

Now add a custom link to the Menu with /blog/

Implement Blog components 💾

Now, let's create the Blog page to preview all our posts.

1.) Add globals.js

First of all I added a file called globals.js to the root of the project. It will serve as our "options" for the project. Like what we later might wanna use if we use this starter as a theme.

// globals.js
const Globals = {
  blogURI: 'blog'
}

module.exports = Globals

2.) Create blog.js

Now, create blog.js inside the templates/post folder:

// src/templates/post/blog.js

import React from "react"
import Layout from "../../components/Layout"
import PostEntry from "../../components/PostEntry"
import Pagination from "../../components/Pagination"
import SEO from "../../components/SEO"

const Blog = ({ pageContext }) => {
  const { nodes, pageNumber, hasNextPage, itemsPerPage, allPosts } = pageContext

  return (
    <Layout>
      <SEO
        title="Blog"
        description="Blog posts"
        keywords={[`blog`]}
      />

      {nodes && nodes.map(post => <PostEntry key={post.postId} post={post}/>)}

      <Pagination
        pageNumber={pageNumber}
        hasNextPage={hasNextPage}
        allPosts={allPosts}
        itemsPerPage={itemsPerPage}
      />
    </Layout>
  )
}

export default Blog

As you can see I already made use of some components we will create in the upcoming steps.

3.) Create PostEntry.js

// src/components/PostEntry.js

import React from "react"
import { Link } from "gatsby"
import Image from "./Image"
import { blogURI } from "../../globals"

const PostEntry = ({ post }) => {

  const { uri, title, featuredImage, excerpt } = post

  return (
    <div style={{ marginBottom: "30px" }}>
      <header>
        <Link to={`${blogURI}/${uri}/`}>
          <h2 style={{ marginBottom: "5px" }}>{title}</h2>
          <Image image={featuredImage} style={{ margin: 0 }}/>
        </Link>

      </header>

      <div dangerouslySetInnerHTML={{ __html: excerpt }}/>
    </div>
  )
}

export default PostEntry

4.) Create Image.js

// src/components/Image.js

import React from "react"
import { useStaticQuery, graphql } from "gatsby"

const Image = ({ image, withFallback = false, ...props }) => {
  const data = useStaticQuery(graphql`
      query {
          fallBackImage: file(relativePath: { eq: "fallback.svg" }) {
              publicURL
          }
      }
  `)

  /**
   * Return fallback Image, if no Image is given.
   */
  if (!image) {
    return withFallback ? <img src={data.fallBackImage.publicURL} alt={"Fallback"} {...props}/> : null
  }

  return <img src={image.sourceUrl} alt={image.altText} {...props}/>
}

export default Image

The image component for now works simply with the absolute path to your WordPress installation. We will get more into image-processing in the next part of the tutotorial.

withFallback gives you the option to show a fallback image if there is no image passed down. If withFallback is false, like in the default, then it will simply not render any dom element.
Place the fallback.svg image inside your images folder. (Find my fallback image here)

5.) Create Pagination.js

Now if we want to only show a certain number of post previews on one page, we need to implement pagination.

// src/components/Pagination.js

import React from "react"
import { Link } from "gatsby"
import { blogURI } from "../../globals"

const Pagination = ({ pageNumber, hasNextPage }) => {

  if (pageNumber === 1 && !hasNextPage) return null

  return (
    <div style={{ margin: "60px auto", textAlign: "center" }}>
      <h2>Posts navigation</h2>
      <div>
        {
          pageNumber > 1 && (
            <Link
              className="prev page-numbers"
              style={{
                padding: "4px 8px 5px 8px",
                backgroundColor: "rgba(0,0,0,.05)",
                borderRadius: "3px",
              }}
              to={pageNumber > 2 ? `${blogURI}/page/${pageNumber - 1}` : `${blogURI}/`}
            >
              <span>Previous page</span>
            </Link>
          )
        }
        <span aria-current="page" className="page-numbers current" style={{ padding: "5px 10px" }}>
          <span className="meta-nav screen-reader-text">Page </span>
          {pageNumber}
        </span>

        {
          hasNextPage && (
            <Link
              style={{
                padding: "4px 8px 5px 8px",
                backgroundColor: "rgba(0,0,0,.05)",
                borderRadius: "3px",
              }}
              className="next page-numbers"
              to={`${blogURI}/page/${pageNumber + 1}`
              }
            >
              <span>Next page </span>
            </Link>
          )
        }
      </div>
    </div>
  )
}

export default Pagination

If pageNumber === 1 && !hasNextPage we can return null, as we only have one page and don't need any pagination.
If the current pageNumber is more than 1, we show a Previous Page Link/Button
If the current page hasNextPage, we show a Link/Button to the Next page

Adjust Post/Blog Creation 📓

We have to adjust a couple of things in createPosts.js. I'll introduce a new concept of GraphQL fragments, that live in data.js files. This will help us to separate some concerns and make our code structure more structured.

1.) Add data.js

Let's add one fragment for the Post and one for the Blog-Preview.

If you are unfamiliar with the concepts of fragments in GraphQL checkout this link.

// src/templates/post/data.js

const PostTemplateFragment = `
  fragment PostTemplateFragment on WPGraphQL_Post {
    id
    postId
    title
    content
    link
    featuredImage {
      sourceUrl
    }
    categories {
      nodes {
        name
        slug
        id
      }
    }
    tags {
      nodes {
        slug
        name
        id
      }
    }
    author {
      name
      slug
    }
  }
`

const BlogPreviewFragment = `
  fragment BlogPreviewFragment on WPGraphQL_Post {
    id
    postId
    title
    uri
    date
    slug
    excerpt
    content
    featuredImage {
      sourceUrl
    }
    author {
      name
      slug
    }
  }
`

module.exports.PostTemplateFragment = PostTemplateFragment
module.exports.BlogPreviewFragment = BlogPreviewFragment

Notice how we are using only strings that get exported?
- We will use these strings inside the createPagesStatefully and not directly inside our React components. This gives us the freedom to define queries before the build starts and therefore we are able to concat multiple strings to one query string in the end.
- This wouldn't be possible inside the components, when used with page queries or static queries.

2.) Adjust createPosts.js

First part

// create/createPosts.js

const {
  PostTemplateFragment,
  BlogPreviewFragment,
} = require("../src/templates/post/data.js")

const { blogURI } = require("../globals")

const postTemplate = require.resolve("../src/templates/post/index.js")
const blogTemplate = require.resolve("../src/templates/post/blog.js")

const GET_POSTS = `
    # Here we make use of the imported fragments which are referenced above
    ${PostTemplateFragment}
    ${BlogPreviewFragment}

    query GET_POSTS($first:Int $after:String) {
        wpgraphql {
            posts(
                first: $first
                after: $after
                # This will make sure to only get the parent nodes and no children
                where: {
                    parent: null
                }
            ) {
                pageInfo {
                    hasNextPage
                    endCursor
                }
                nodes {           
                    uri     

                    # This is the fragment used for the Post Template
                    ...PostTemplateFragment

                    #This is the fragment used for the blog preview on archive pages
                    ...BlogPreviewFragment
                }
            }
        }
    }
`

// continues with second part

We import the fragment strings and place them inside the GET_PAGES query string, but outside the actual query GET_POSTS($first:Int $after:String) {...}.
- This will register the fragments, so they can be used in the upcoming query.
Inside the query, you finally can make use of the standard ... fragment syntax.

Second Part

// create/createPosts.js

// Make sure to add the first part above

const allPosts = []
const blogPages = [];
let pageNumber = 0;
const itemsPerPage = 10;


/**
 * This is the export which Gatbsy will use to process.
 *
 * @param { actions, graphql }
 * @returns {Promise<void>}
 */
module.exports = async ({ actions, graphql, reporter }, options) => {

  /**
   * This is the method from Gatsby that we're going
   * to use to create posts in our static site.
   */
  const { createPage } = actions

  /**
   * Fetch posts method. This accepts variables to alter
   * the query. The variable `first` controls how many items to
   * request per fetch and the `after` controls where to start in
   * the dataset.
   *
   * @param variables
   * @returns {Promise<*>}
   */
  const fetchPosts = async (variables) =>
    /**
     * Fetch posts using the GET_POSTS query and the variables passed in.
     */
    await graphql(GET_POSTS, variables).then(({ data }) => {
      /**
       * Extract the data from the GraphQL query results
       */
      const {
        wpgraphql: {
          posts: {
            nodes,
            pageInfo: { hasNextPage, endCursor },
          },
        },
      } = data

      /**
       * Define the path for the paginated blog page.
       * This is the url the page will live at
       * @type {string}
       */
      const blogPagePath = !variables.after
        ? `${blogURI}/`
        : `${blogURI}/page/${pageNumber + 1}`

      /**
       * Add config for the blogPage to the blogPage array
       * for creating later
       *
       * @type {{
       *   path: string,
       *   component: string,
       *   context: {nodes: *, pageNumber: number, hasNextPage: *}
       * }}
       */
      blogPages[pageNumber] = {
        path: blogPagePath,
        component: blogTemplate,
        context: {
          nodes,
          pageNumber: pageNumber + 1,
          hasNextPage,
          itemsPerPage,
          allPosts,
        },
      }

      /**
       * Map over the posts for later creation
       */
      nodes
      && nodes.map((posts) => {
        allPosts.push(posts)
      })

      /**
       * If there's another post, fetch more
       * so we can have all the data we need.
       */
      if (hasNextPage) {
        pageNumber++
        reporter.info(`fetch post ${pageNumber} of posts...`)
        return fetchPosts({ first: itemsPerPage, after: endCursor })
      }

      /**
       * Once we're done, return all the posts
       * so we can create the necessary posts with
       * all the data on hand.
       */
      return allPosts
    })

  /**
   * Kick off our `fetchPosts` method which will get us all
   * the posts we need to create individual posts.
   */
  await fetchPosts({ first: itemsPerPage, after: null }).then((wpPosts) => {

    wpPosts && wpPosts.map((post) => {
      /**
       * Build post path based of theme blogURI setting.
       */
      const path = `${blogURI}/${post.uri}/`

      createPage({
        path: path,
        component: postTemplate,
        context: {
          post: post,
        },
      })

      reporter.info(`post created:  ${post.uri}`)
    })

    reporter.info(`# -----> POSTS TOTAL: ${wpPosts.length}`)

    /**
     * Map over the `blogPages` array to create the
     * paginated blog pages
     */
    blogPages
    && blogPages.map((blogPage) => {
      if (blogPage.context.pageNumber === 1) {
        blogPage.context.publisher = true;
        blogPage.context.label = blogPage.path.replace('/', '');
      }
      createPage(blogPage);
      reporter.info(`created blog archive page ${blogPage.context.pageNumber}`);
    });
  })
}

Compared to the version from our previous parts, I did some constant name refactoring and added the blogURI coming from our globals file.

Final Thoughts 🏁

Noooow, I hope I didn't miss anything. This part was a bit tricky, as I had to do some refactoring. I hope this did not mess up your setup. If so, please feel free to ask questions here or just clone this part of the tutorial to have a clean base for the next part.

Find the code base here: https://github.com/henrikwirth/gatsby-starter-wordpress-advanced/tree/tutorial/part-5

What's Next ➡️

In the next part of the series, we will discover how to fetch images from WordPress in a way, that makes it possible to use the powerful gatsby-image plugin.

Part 6 - How to handle Images and make use of gatsby-image

Deployment - Guide to Gatsby WordPress Starter Advanced with Previews, i18n and more

Henrik Wirth — Wed, 27 Nov 2019 15:23:53 +0000

Finally we have the basics and it's time to see what we've done in production. I'll quickly go through some ways to deploy your site. I will mainly focus on Netlify for this, but also give an example for GitLab pages.

Netlify Setup ⚡
WordPress Plugin 💾
GitLab Setup 🐱
- Gatsby Prefix Configuration
- GitLab CI Configuration
Final Thoughts 🏁
What's Next ➡️

Netlify Setup ⚡

First of all, make sure you have a repository, with all your work so far pushed to master. Preferably on GitHub. Now get yourself a Netlify account and connect it with your GitHub repository. I won't go into details for that. There is plenty of documentation out there.
If you create a project from your Gatsby repository, Netlify should recognize, that it is a Gatsby project and you should see something like this:
Now go to the Build & Deploy settings and add a build hook.
Copy the build hook URL for later use.
By the time you got your build hook, Netlify should already be finished building your site. Checkout your Netlify domain.

WordPress Plugin 💾

We will setup a WordPress plugin, to be able to make use of the build hook. With this, we can decide when to trigger a build. For example, you can build only when pressing the build button, or after every post/page update. There is plenty more options.

WP JAMstack Deployments - To add your Netlify (or other webhook) build and to show a build status badge.
- Also available in the WordPress Plugin registry: here

While I would suggest this plugin. There is also other plugins out there.

You can download the .zip files of these repositories and install them through WP-Admin or just navigate to your plugin folder and do a git clone like so:

git clone https://github.com/crgeary/wp-jamstack-deployments

Activate the plugin.
Now go to Settings->Deployments and fill in the form:
- Build Hook URL: The Netlify build hook we created before.
- Badge Image URL: We can find the badge URL in the General->Status badges settings of Netlify. It consists of 2 URLs. The first one is the one we need for the status badge.
- Badge Link: When you click on the Netlify badge, the link you set here will open. You can either set it to your Netlify site domain, or you use the second URL from the status badge, which will link to your Netlify deploy status page.
Save Settings and Test Deployment. We should see the badge in the admin toolbar being in Building mode.

Now we can trigger our rebuilds with the Deploy Website button in the admin toolbar. I like to only rebuild when I changed more then just a post, especially if there is not incremental builds in place (yet), so I'll leave all the checkboxes blank and rebuild my site as I see fit.

☑️ Easy deployments done

GitLab Setup 🐱

We really like working with GitLab on our client projects. With GitLab Pages you can have an easy way to setup a preview page, that is only accessible for authorized users, that are part of the project. you can also make it public if you want so.

Checkout the docs on GitLab Pages for some more insight.

Gatsby Prefix Configuration

Go to your gatsby-config.js and add the following line inside module.exorts = {...}:

  pathPrefix: `${process.env.PATH_PREFIX}`,

Now this way we can define the path prefix either in our .env files, our we use GitLab Page environment variables for it. Let's use the latter, to be as flexible as possible.

GitLab CI Configuration

Depending on where your project is placed, GitLab will host your page on a domain, that will look like so:

Checkout: GitLab Page Domain Naming

As you can see, you will have /projectname in your URL. Therefore, we need to tell Gatsby to prefix your routing.

1.) Head over to your GitLab project, go to Settings->CI/CD->Variables and add your PATH_PREFIX like so:

Now the only thing missing is the CI config file inside your Gatsby projects root.

2.) Add following snippet to your .gitlab-ci.yml:

# .gitlab-ci.yml

image: node:12.13.0

pages:
  script:
    - npm install
    - npm install gatsby-cli
    - ./node_modules/.bin/gatsby build --prefix-paths
  artifacts:
    paths:
      - public
  cache:
    paths:
      - node_modules
  only:
    - master

As you can see in the third line under script:, we call Gatsby like ./node_modules/.bin/gatsby build --prefix-paths. This will make sure, that Gatsby is actually using the prefix in the build.

Thats it. You should be able to find your page under the domain as described above. Sometimes it needs a few minutes, if it is the first time you deploy the page. Be patient. 😉

Final Thoughts 🏁

Yaaah, our site is online now! 🚀 There is many more ways to deploy your site. But I guess you get a good idea of how things can work with the example of these two common approaches.

Find the code base here: https://github.com/henrikwirth/gatsby-starter-wordpress-advanced/tree/tutorial/part-4

Find the GitLab code base in this extra branch: https://github.com/henrikwirth/gatsby-starter-wordpress-advanced/tree/tutorial/part-4-gitlab

What's Next ➡️

In the upcoming part we will introduce a blog page with pagination, which will serve as overview for our blog post previews.

Part 5 - Blog with Pagination

Setup Menu Navigation - Guide to Gatsby WordPress Starter Advanced with Previews, i18n and more

Henrik Wirth — Tue, 26 Nov 2019 13:34:03 +0000

In this part we will create some navigation based on a WordPress Menu, to reference our pages and posts, that we generated in the previous part.

Create WordPress Menu 🌐
Create Components in Gatsby 💻
Menu Child Items 🚸
Support External Links 🔗
Final Thoughts 🏁
What's Next ➡️

Create WordPress Menu 🌐

Let's get started by creating content in WordPress.

Before creating a menu, make sure you have some example pages like so:
Create the Main Menu with the pages you want to add. Assign the page to the primary location.
Play around in the GraphiQL explorer:
- If you use the WordPress Twenty Twenty Theme and set your menu to the primary position, you have to set the where->location to PRIMARY. Play around with the explorer to see what options you have in the location drop-down.
- As you can see, the URL we get is not relative and there is now slug. We could extend the WPGraphQL schema to add another field for that. We will do this later. For now we just gonna strip the domain from the URL in the frontend (quick and dirty).

Create Components in Gatsby 💻

Now, let's add some code to render our menu in Gatsby.

1.) Creating a utils function to create relative URLs:

// src/utils/index.js

/**
 * Parses a menu item object and returns Gatsby-field URI.
 *
 * @param {object} menuItem a single menu item
 * @param wordPressUrl
 * @param blogURI
 */
export const CreateLocalLink = (menuItem, wordPressUrl, blogURI='blog/') => {
  const { url, connectedObject } = menuItem;

  if (url === '#') {
    return null;
  }
  /**
   * Always want to pull of our API URL.
   */
  let newUri = url.replace(wordPressUrl, '');

  /**
   * If it's a blog link, respect the users blogURI setting.
   */
  if (connectedObject && connectedObject.__typename === 'WPGraphQL_Post') {
    newUri = blogURI + newUri;
  }

  return newUri;
};

The GraphQL endpoint is serving us with absolute URLs to the WordPress instance. Therefore, we have to do some magic to workaround this and get relative URLs.

While this is an easy fix for the frontend, you can also add another field to the schema and do it in the backend. Then you don't need extra logic and client computation in the frontend. See this docs on how to add custom fields to WPGraphQL.

2.) Creating MenuItem component, that uses our util function:

// src/components/MenuItem.js

import React from "react"
import { CreateLocalLink } from "../utils"
import { Link } from "gatsby"

const MenuItem = ({ menuItem, wordPressUrl }) => {
  return (
    <Link style={{marginRight: '20px' }} to={CreateLocalLink(menuItem, wordPressUrl)}>{menuItem.label}</Link>
  )
}

export default MenuItem

3.) Creating Menu component, that uses our MenuItem component:

// src/components/Menu.js

import React from "react"
import { StaticQuery, graphql } from "gatsby"

import MenuItem from "./MenuItem"

/**
 * Define MenuItem fragment and get all primary menu items.
 */
const MENU_QUERY = graphql`

    fragment MenuItem on WPGraphQL_MenuItem {
        id
        label
        url
        title
        target
    }

    query GETMAINMENU {
        wpgraphql {
            menuItems(where: {location: PRIMARY}) {
                nodes {
                    ...MenuItem
                }
            }
            generalSettings {
                url
            }
        }
    }
`

const Menu = () => {
  return (
    <StaticQuery
      query={MENU_QUERY}
      render={(data) => {
        if (data.wpgraphql.menuItems) {
          const menuItems = data.wpgraphql.menuItems.nodes
          const wordPressUrl = data.wpgraphql.generalSettings.url

          return (
            <div style={{ marginBottom: "20px" }}>
              {
                menuItems &&
                menuItems.map((menuItem) => (
                  <MenuItem key={menuItem.id} menuItem={menuItem} wordPressUrl={wordPressUrl}/>
                ))
              }
            </div>
          )
        }
        return null
      }}
    />
  )
}

export default Menu

Here we are using Gatsby's StaticQuery to get all the MenuItems. Also, we are making use of fragments to be able to reuse the query fields later on.

4.) And finally adding the Menu to layout.js:

// src/components/layout.js

/**
 * Layout component that queries for data
 * with Gatsby's useStaticQuery component
 *
 * See: https://www.gatsbyjs.org/docs/use-static-query/
 */

import React from "react"
import PropTypes from "prop-types"
import { useStaticQuery, graphql } from "gatsby"

import Header from "./header"
import "./layout.css"
import Menu from "./Menu"

const Layout = ({ children }) => {
  const data = useStaticQuery(graphql`
    query SiteTitleQuery {
      site {
        siteMetadata {
          title
        }
      }
    }
  `)

  return (
    <>
      <Header siteTitle={data.site.siteMetadata.title} />
      <div
        style={{
          margin: `0 auto`,
          maxWidth: 960,
          padding: `0px 1.0875rem 1.45rem`,
          paddingTop: 0,
        }}
      >
        <Menu />
        <main>{children}</main>
        <footer>
          © {new Date().getFullYear()}, Built with
          {` `}
          <a href="https://www.gatsbyjs.org">Gatsby</a>
        </footer>
      </div>
    </>
  )
}

Layout.propTypes = {
  children: PropTypes.node.isRequired,
}

export default Layout

Menu Child Items 🚸

This won't be part of our code-base for now, but in case you need the childItems of a MenuItem to create a multi-level navigation, you can do so, by adjusting the query like so:

const MENU_QUERY_WITH_CHILDREN = graphql`

  fragment MenuItem on WPGraphQL_MenuItem {
    id
    label
    url
    title
    target
  }

  query GETMAINMENU {
    wpgraphql {
      menuItems(where: {location: PRIMARY}) {
        nodes {
          ...MenuItem
          childItems {
            nodes {
              ...MenuItem
              childItems {
                nodes {
                  ...MenuItem
                }
              }
            }
          }
        }
      }
      generalSettings {
        url
      }
    }
  }
`

This will get 3 levels of menuItems. You will need to add child items to the WordPress menu to see any results. Also, you would need to adjust your component, to support the extra 2 levels in a recursive manner.

Support External Links 🔗

Gatsby's Link component doesn't support the use of external links. We want to be able to add external Links to our menu and therefore have to do a little extra work as shown in the Gatsby docs.

1.) Create UniversalLink component:

// src/components/UniversalLink.js

import React from "react"
import { Link as GatsbyLink } from "gatsby"
// Since DOM elements <a> cannot receive activeClassName
// and partiallyActive, destructure the prop here and
// pass it only to GatsbyLink
const UniversalLink = ({ children, to, activeClassName, partiallyActive, ...other }) => {
  // Tailor the following test to your environment.
  // This example assumes that any internal link (intended for Gatsby)
  // will start with exactly one slash, and that anything else is external.
  const internal = /^\/(?!\/)/.test(to)
  // Use Gatsby Link for internal links, and <a> for others
  if (internal) {
    return (
      <GatsbyLink
        to={to}
        activeClassName={activeClassName}
        partiallyActive={partiallyActive}
        {...other}
      >
        {children}
      </GatsbyLink>
    )
  }
  return (
    <a href={to} {...other} target="_blank" rel="noopener noreferrer">
      {children}
    </a>
  )
}
export default UniversalLink

2.) Update MenuItem.js:

// src/components/MenuItem.js

import React from "react"
import { CreateLocalLink } from "../utils"
import UniversalLink from "./UniversalLink"

const MenuItem = ({ menuItem, wordPressUrl }) => {
  return (
    <UniversalLink style={{ marginRight: "20px" }}
                   to={CreateLocalLink(menuItem, wordPressUrl)}>
      {menuItem.label}
    </UniversalLink>
  )
}

export default MenuItem

Final Thoughts 🏁

If you run gatsby develop now, you should see a Navigation with your menu items navigating to you relative page paths.

Find the code here: https://github.com/henrikwirth/gatsby-starter-wordpress-advanced/tree/tutorial/part-3

What's Next ➡️

Next we'll build our navigation based on a WordPress menu.

Part 4 - Deployment

Basic WordPress & Gatsby Setup - Guide to Gatsby WordPress Starter Advanced with Previews, i18n and more

Henrik Wirth — Mon, 25 Nov 2019 13:54:09 +0000

Hooking up our WordPress with a Gatsby generated site, will be the first steps we are talking on our journey towards a client-ready static-dynamic site.

Install WordPress and Plugins 💾
- Plugins
Create initial Gatsby site 💻
- Plugins
- Configuration
- Create Pages & Posts
  - Page Template
  - Post Template
  - Gatsby Node
  - Create Pages
  - Create Posts
Final Thoughts 🏁
Credits ❤️
What's Next ➡️

Install WordPress and Plugins 💾

Okay, so let's start by installing WordPress. Use whatever you want for that, either local or online. I'll be using Local by Flywheel.

Plugins

WPGraphQL (Documentation) - This will create your GraphQL endpoint.
WPGraphiQL - Adds a GraphiQL to your WP-Admin, which helps to see changes quickly and figure out what to query.

You can download the .zip files of these repositories and install them through WP-Admin or just navigate to your plugin folder and do a git clone like so:

git clone https://github.com/wp-graphql/wp-graphql
git clone https://github.com/wp-graphql/wp-graphiql

Now make sure to activate all the plugins.

To check out if everything works, head over to the GraphiQL explorer inside your WordPress Admin area and start playing around with it:

Create initial Gatsby site 💻

First of all create a Gatsby project with:

gatsby new gatsby-starter-wordpress-advanced

After that let's install the first couple of plugins we will use for this part of the tutorial:

Plugins

dotenv - For loading environment variables.
gatsby-source-graphql - Helps to source the data from our WordPress GraphQL endpoint.

yarn add dotenv gatsby-source-graphql

Configuration

We will use dotenv to have two different files for environment variables. Create .env.development and .env.production in the root of your gatsby site's folder. The development one will be called when gatsby develop is used and production is for gatsby build.

Add .env.development to .gitignore:

# .gitignore
.env.development

# .env.development
# This is in gitignore and should not be pushed to the repository.

WORDPRESS_URL=http://gatsby-starter-wordpress-advanced.local

If you use a local WordPress instance, then replace http://gatsby-starter-wordpress-advanced.local with the URL to your local installation. If you just use a online WordPress instance, then use the URL to that.

# .env.production
# Don't put any sensible data here!!!

WORDPRESS_URL=https://your-online-wordpress-instance.dev

Replace https://your-online-wordpress-instance.dev with the URL to your online WordPress instance. In Netlify you also can use environment variables and combine them with what is in this file.

If you use Local By Flywheel, you can expose your local site by enabling Live Link. You will get an ngrok.io URL, which you can use for the production WORDPRESS_URL.

Now in your gatsby-config.js add this to the top before the module.exports:

let activeEnv =
  process.env.GATSBY_ACTIVE_ENV || process.env.NODE_ENV || "development"

console.log(`Using environment config: '${activeEnv}'`)

require("dotenv").config({
  path: `.env.${activeEnv}`,
})

console.log(`This WordPress Endpoint is used: '${process.env.WORDPRESS_URL}'`)

The snippet above will help to require the right .env file.

Add the following to your configs module.exports inside plugins:[...]:

    {
      resolve: "gatsby-source-graphql",
      options: {
        typeName: "WPGraphQL",
        fieldName: "wpgraphql",
        url: `${process.env.WORDPRESS_URL}/graphql`,
      },
    },

This will hook up your Gatsby with the WordPress instance. And expose this data under wpgraphql. Note: This makes your schema different to the one that is exposed in you WordPress GraphQL endpoint. As soon as you are using it with Gatsby, you now have to wrap your queries with wpgraphql{...}.

Try running gatsby develop and navigate to http://localhost:8000/___graphql. You will see something like this. Play around with the GraphiQL-Explorer to get familiar with the WPGraphQL schema.

Create Pages & Posts

Now let's see, how we can create pages and posts, based on the WordPress data. First remove the index.js and page-2.js in your pages folder. Then, we start with some very simple templates.

Page Template

// src/templates/page/index.js

import React  from "react"

import Layout from "../../components/layout"
import SEO from "../../components/seo"


const Page = ({ pageContext }) => {

  const page = pageContext.page

  return (
    <Layout>
      <SEO title={page.title} />

      <h1>{page.title}</h1>
      <div dangerouslySetInnerHTML={{__html: page.content}} />

    </Layout>
  )
}

export default Page

Post Template

// src/templates/post/index.js

import React  from "react"

import Layout from "../../components/layout"
import SEO from "../../components/seo"


const Post = ({ pageContext }) => {

  const post = pageContext.post

  return (
    <Layout>
      <SEO title={post.title} />

      <h1> {post.title} </h1>
      <div dangerouslySetInnerHTML={{__html: post.content}} />

    </Layout>
  )
}

export default Post

Gatsby Node

In your Gatsby node, add these lines:

// gatsby-node.js

const createPages = require("./create/createPages")
const createPosts = require("./create/createPosts")

exports.createPagesStatefully = async ({ graphql, actions, reporter }, options) => {
  await createPages({ actions, graphql, reporter }, options)
  await createPosts({ actions, graphql, reporter }, options)
}

To separate their concerns, we split up the creation of posts and pages in different files. Create a folder called create in the root directory.

Create Pages

First we add some requires and define our GraphQL query.

// create/createPages.js

const pageTemplate = require.resolve('../src/templates/page/index.js');

const GET_PAGES = `
    query GET_PAGES($first:Int $after:String) {
        wpgraphql {
            pages(
                first: $first
                after: $after
                # This will make sure to only get the parent nodes and no children
                where: {
                    parent: null
                }
            ) {
                pageInfo {
                    hasNextPage
                    endCursor
                }
                nodes {                
                    id
                    title
                    pageId
                    content
                    uri
                    isFrontPage
                }
            }
        }
    }
`

You can see some variables are passed down the query. Refer to the GraphQL Docs for more information on GraphQL query variables. Also, you can see pageInfo with hasNextPage and endCursor. This will help for pagination, as we should not query for all pages/posts together, but rather do 10 at a time. This will ensure, that we don't put too much pressure on our WordPress backend.

// create/createPages.js

const allPages = []
let pageNumber = 0
const itemsPerPage = 10

/**
 * This is the export which Gatbsy will use to process.
 *
 * @param { actions, graphql }
 * @returns {Promise<void>}
 */
module.exports = async ({ actions, graphql, reporter }, options) => {

  /**
   * This is the method from Gatsby that we're going
   * to use to create pages in our static site.
   */
  const { createPage } = actions
  /**
   * Fetch pages method. This accepts variables to alter
   * the query. The variable `first` controls how many items to
   * request per fetch and the `after` controls where to start in
   * the dataset.
   *
   * @param variables
   * @returns {Promise<*>}
   */
  const fetchPages = async (variables) =>
    /**
     * Fetch pages using the GET_PAGES query and the variables passed in.
     */
    await graphql(GET_PAGES, variables).then(({ data }) => {
      /**
       * Extract the data from the GraphQL query results
       */
      const {
        wpgraphql: {
          pages: {
            nodes,
            pageInfo: { hasNextPage, endCursor },
          },
        },
      } = data

      /**
       * Map over the pages for later creation
       */
      nodes
      && nodes.map((pages) => {
        allPages.push(pages)
      })

      /**
       * If there's another page, fetch more
       * so we can have all the data we need.
       */
      if (hasNextPage) {
        pageNumber++
        reporter.info(`fetch page ${pageNumber} of pages...`)
        return fetchPages({ first: itemsPerPage, after: endCursor })
      }

      /**
       * Once we're done, return all the pages
       * so we can create the necessary pages with
       * all the data on hand.
       */
      return allPages
    })

  /**
   * Kick off our `fetchPages` method which will get us all
   * the pages we need to create individual pages.
   */
  await fetchPages({ first: itemsPerPage, after: null }).then((wpPages) => {

    wpPages && wpPages.map((page) => {
      let pagePath = `${page.uri}`

      /**
       * If the page is the front page, the page path should not be the uri,
       * but the root path '/'.
       */
      if(page.isFrontPage) {
        pagePath = '/'
      }

      createPage({
        path: pagePath,
        component: pageTemplate,
        context: {
          page: page,
        },
      })

      reporter.info(`page created: ${page.uri}`)
    })

    reporter.info(`# -----> PAGES TOTAL: ${wpPages.length}`)
  })
}

So here we first define our fetchPages() function, that will recursively keep on fetching pages (10 at a time) until there is no more to fetch. It adds them to the allPages array.
Then, we map over wpPages and call createPage(). An action passed down by the createPagesStatefully() function given by the Gatsby API (See docs here).
We use page.isFrontPage to check if we need to adjust the path. For the home page we want the path to be the root path / instead of /home/.
In createPage() we set the path equal to the uri. This will be creating the slug for the individual page. The component gets our pageTemplate assigned and finally, we pass the pages data to the context.

-> See the complete file here: createPages.js

Create Posts

createPosts is basically the same with the exception of prefixing the path with blog/.

-> See the complete file here: createPosts.js

Final Thoughts 🏁

If you run gatsby develop now, you should be able to see your pages under http://localhost:8000/sample-page/. If you are not sure what pages got created. Just type in some random slug like http://localhost:8000/asdf/ and you will get an overview of all the pages there are.

This will give you the basic setup we need for the upcoming parts of this tutorial.

Find the code here: https://github.com/henrikwirth/gatsby-starter-wordpress-advanced/tree/tutorial/part-2

Credits ❤️

This part is highly inspired by staticfuse's (gatsby-theme-publisher). You should check it out!

What's Next ➡️

Next we'll build our navigation based on a WordPress menu.

Part 3 - Setup Menu Navigation

Overview - Guide to Gatsby WordPress Starter Advanced with Previews, i18n and more

Henrik Wirth — Mon, 25 Nov 2019 13:54:09 +0000

Tutorial Outline

Overview
Basic WordPress & Gatsby Setup
Setup Menu Navigation
Deployment
Blog with Pagination
How to handle Images and make use of gatsby-image
PageBuilder with ACF Flexible Content
Internationalization - i18n
Dynamic Previews
...

Depending on time and upcoming discussions, this outline might change. I might add some more parts, if I discover other topics, that could be of interest.

Find the latest version here: https://gatsby-starter-wordpress-advanced.netlify.com

Who is this tutorial for? 👥

For people who want to get started with Gatsby in combination with WordPress and create a production ready client-site or personal sites with lots of nice features. You should have a basic understanding of WordPress and JavaScript. The tutorial will get more advanced and into edge-cases, the further you go.

Feel free to use the comments if something doesn't make sense to you. I'll try my best to help out for any level of experience.

Requirements used for the project 📋

CMS
- Highly Customizable
- Easy to use
Secure
Translatable (Multi-Language)
Low Frequency Updates
Responsive Design
Good performance (SEO and site speed)
Scale: ~100 Pages

So in short: A modern extensible multi-language site.

What will you learn? 🎓

Obviously this depends on your knowledge. The first parts (1-3) of the tutorial, will be more basic things, while from the middle onwards it will get more advanced, more specific to use cases and more edge-case.

I just worked on a client project, that had all the above requirements and there is not many tutorials out there, which in depth, explain how to implement a full-fledged production ready site with i18n, previews and the ability to have some sort of page builder ability.

You will learn about:

The basic setup and deployment.
How to make use of ACF flexible content field
- How to dynamically render your components depending on which components are in use.
How WPGraphQl works and how you can extend it to your needs.
How to implement your multi-language setup with Polylang.
How you get Previews to work with dynamic data. Without the need of rebuilds.

Repository

Here is the code used in the tutorial. Checkout the branches for the different parts.

henrikwirth / gatsby-starter-wordpress-advanced

Gatsby WordPress Starter Advanced - Tutorial

Credits ❤️

I want to thank some people, who helped me out a lot while working with those technologies. First of all thanks to all peeps on the WPGraphQL Slack Chat. Especially Jason Bahl, Peter Pristas, Justin W Hall, Esa-Matti Suuronen, and all the others there I probably forgot about. If you ever need help, this is a great place to get well treated and sorted out. Thanks to NeverNull for letting me work in this.

Cover-Image vector art from rawpixel

You might wanna checkout our huge list of resources for this subject:

henrikwirth / awesome-wordpress-gatsby

An awesome list of resources about WordPress as a headless CMS with Gatsby

Questions & Constructive Criticism 💭

I'd love to have discussions about my approaches. If you have any questions, or want to point out any mistakes. It is more than welcome. I'm new to writing tutorials and therefore am happy to improve in any way.

Let's dive in ➡️

We will create our basic setup with WordPress & Gatsby.

Part 2 - Basic WordPress & Gatsby Setup

An awesome list of WordPress-Gatsby resources.

Henrik Wirth — Sun, 10 Nov 2019 12:39:57 +0000

Here is a list I created in an attempt to gather all the helpful resources there are about how to work with Gatsby in combination with WordPress. Happy to add new resources, if someone has some awesome suggestions. Please feel free to contribute :)

henrikwirth / awesome-wordpress-gatsby

An awesome list of resources about WordPress as a headless CMS with Gatsby

A curated list of resources about WordPress as a headless CMS with Gatsby as a Static Site Generator (SSG)

A headless CMS is a back-end only content management system (CMS). Its purpose is to serve content and make it accessible via an API (e.g. REST or GraphQL).

A Static Site Generator (SSG) is a framework or setup, that helps you to generate static websites (HTML/CSS/JS). The source of your data can be anything from local files (e.g. text files or markdown) to APIs (e.g. REST, GraphQL).

Why Gatsby and WordPress?

View on GitHub

The List

Date: 07.03.21

A headless CMS is a back-end only content management system (CMS). Its purpose is to serve content and make it accessible via an API (e.g. REST or GraphQL).

Why Gatsby and WordPress?

WordPress is one of the most used CMS in the world and therefore many people already know how to work with it. The typical front-end approach with PHP-based templates is getting more and more problematic in an environment where performance is key. The approach to use WordPress as a headless CMS with normal API calls through JavaScript already exists, but also has the downside of having to make requests to the server and rendering depending on the response. This adds time to load. Gatsby instead, pre-renders the whole site at compile time and therefore the user gets a fully prepared static site on their first request, making it one of the best approaches for performance. Another huge benefit is security, as your WordPress instance can be anywhere, even locally and you don't need to expose any of it to the user. The static Gatsby site therefore, is not hackable. Find further arguments for pros and cons in the resources below.

Communities
Articles and Talks
Plugins
- WordPress
- Gatsby
Free Tutorials / Courses
- Written Tutorials
- Video Tutorials
Paid Tutorials / Courses
Starters
Themes

Communities

If you need help with anything, there are some highly active communities.

WPGraphQL

Gatsby

Articles and Talks

List of articles and talks that elaborate on the technology stack in general.

2021.02: Announcing Gatsby’s New WordPress Integration
2021.02: Jason Bahl of WPGraphQL's role in the operating system for the web
2021.02: Torque News Drop: Jason Bahl and WPGraphQL
2021.02: Gatsby Launches New WordPress Integration, Expanding Support for Headless Architecture
2020.11: Announcing WPGraphQL v1.0
2020.07: My Long Journey to a Decoupled WordPress Gatsby Site
2019.06: Modern Web Development on the JAMstack - A report from Netlify about Modern Web Development on the JAMStack, published by O'REILLY.

Plugins

List of useful plugins to make WordPress and Gatsby work together. Ordered alphabetically.

WordPress

Essential Plugins

WPGraphQL - Documentation - WPGraphQL brings the power of GraphQL to your WordPress site.
WPGatsby - This plugin configures your WordPress site to be an optimized source for Gatsby.

WPGraphQL Extensions

WPGraphQL Cors - This FREE plugin from @kidunot89 and @byfunkhaus claims to enable authentication with WPGraphQL to “just work” by allowing you to set CORS headers that GraphQL will accept, which means WordPress default auth cookies can be accepted.
Total Counts for WPGraphQL - This FREE plugin from @builtbycactus exposes total counts to connections in the WPGraphQL Schema.
WPGraphQL Gutenberg - Exposes Gutenberg blocks to the WPGraphQL API.
WPGraphQL JWT Authentication - Extends the WPGraphQL plugin to provide authentication using JWT (JSON Web Tokens).
WPGraphQL Lock - Enables query locking for WPGraphQL by implementing persisted GraphQL queries.
WPGraphQL Meta - This FREE plugin from @robertorourke exposes meta registered via the WordPress register_meta API to WPGraphQL.
WPGraphQL Meta Query - Adds Meta_Query support to the WPGraphQL Plugin for postObject query args.
WPGraphQL Persisted Queries - This FREE plugin from @qz adds the ability to use Persisted Queries with WPGraphQL.
WPGraphQL Offset Pagination - This FREE plugin from @enshrined adds basic offset pagination as opposed to the standard Cursor based pagination that ships with WPGraphQL.
WPGraphQL Send Email - This FREE plugin from @Ash_Hitchcock allows you to send emails via a simple mutation. Includes the abilitty to restrict sending to trusted origins.

Extensions for that use other plugins with WPGraphQL

QL Search - An extension that integrates SearchWP into WPGraphQL.
WPGraphQL Content Blocks - This FREE plugin from the folks at QZ.com exposes a way to query HTML content from WordPress Posts and Pages as “Blocks” (not related to Gutenberg) to bring more structure to your queried content.
WPGraphQL Enable All Post Types (DalkMania) - This FREE plugin from @DalkMania automatically adds ALL registered post types to the WPGraphQL Schema.
WPGraphQL Enable All Post Types (TylerBarnes) - This FREE plugin from @tylbar automatically adds ALL registered post types to the WPGraphQL Schema.
WPGraphQL Google Schema - This FREE plugin from @izzygld261 adds Google Schema support to WPGraphQL.
WPGraphQL Gutenberg ACF - Exposes ACF blocks through GraphQL
WPGraphQL MB (MetaBox) - This FREE plugin from @DalkMania adds all registered metaboxes using metabox.io to the WPGraphQL Schema.
WPGraphQL MetaBox Relationships - This FREE plugin from @hsimah adds support for the metabox.io Relationships field to WPGraphQL (when also using his wp-graphql-metabox plugin).
WPGraphQL Polls - This FREE plugin from @andrenosouza allows you to interact with data from the WP-Polls plugin via GraphQL Queries and Mutations.
WPGraphQL Polylang Extension - Extends WPGraphQL schema with language data from the Polylang plugin.
WPGraphQL Tax Query - Adds Tax_Query support to the WPGraphQL Plugin for postObject query args (WP_Query).
WPGraphQL WPML - This FREE plugin from @rburgst extends the WPGraphQL schema with language data from the WPML plugin. In addition it turns off WPML default filters in order to be able to iterate over all posts regardless of language.
WPGraphQL for Advanced Custom Fields - Exposes Advanced Custom Fields to the WPGraphQL Schema.
WPGraphQL for BuddyPress - This FREE plugin from @RenatoNascAlves exposes BuddyPress data to WPGraphQL.
WPGraphQL for Carbon Fields - This FREE plugin from @matepaiva exposes fields registered using Carbon Fields to the WPGraphQL Schema.
WPGraphQL for Custom Post Type UI - This FREE plugin adds settings to Custom Post Type UI allowing you to set which Post Types and Taxonomies registered by CPTUI should display in the WPGraphQL Schema.
WPGraphQL for FacetWP - This FREE plugin from @hsimah exposes filters on WPGraphQL queries to allow for faceted search with FacetWP.
WPGraphQL for Gravity Forms - This FREE plugin from @kellenmace of @harness_up exposes @gravityforms data to WPGraphQL, allowing you to query for forms, fields, entries, and more.
WPGraphQL for Metabox - This FREE plugin from @hsimah exposes fields registered using the popular http://MetaBox.io to the WPGraphQL Schema.
WPGraphQL for Ninja Forms - This free plugin exposes forms created by the Ninja Forms plugin to the WPGraphQL Schema and allows for the forms to be submitted via GraphQL Mutations.
WPGraphQL for Posts 2 Posts - This FREE plugin from @kellenmace of @harness_up automatically creates GraphQL connections for all of your Posts 2 Posts connections.
WPGraphQL for SEOPress - This FREE plugin from @moon_meister exposes data managed by SEOPress to the WPGraphQL Schema, allowing for SEO data to be used in your headless applications.
WPGraphQL for WooCommerce - This FREE plugin exposes WooCommerce data to WPGraphQL allowing you to interact with your store’s data via GraphQL Queries and mutations.
WPGraphQl Yoast SEO Plugin - Exposes Yoast SEO data to the WPGraphQL Plugin.

Other helpful Plugins

Advanced Custom Fields - ACF PRO
Headless Mode - Headless mode sets up a redirect for all users trying to access the site. The only requests that are granted admission are ones that are either trying to access the REST API, the WP GraphQL API, or any logged-in user looking to access the headless install to edit or create posts.
Polylang
WP JAMstack Deployments - WordPress plugin for JAMstack deployments on Netlify (and other platforms).

Gatsby Plugins

Free Tutorials / Courses

Note: Since the release of gatsby-source-wordpress V4, it is the preferred over gatsby-source-graphql and therefore I will only list tutorials related to that approach.

Written Tutorials

2019.11: Guide to Gatsby WordPress Starter Advanced with Previews, i18n and more - A tutorial series starting with the basic setup of WordPress and Gatsby with WPGraphQL and then dives into more advanced subjects like deployments, previews, i18n and a page-builder like setup with ACF flexible cotent fields.
2019.08: Live Previews with WordPress and Gatsby - Tutorial showing how to use the theme’s higher order component to facilitate previews for WordPress posts and custom post types.
2019.08: Gatsby with WPGraphQL, ACF and Gatbsy-Image - A guide, that shows how to implement gatsby-image, so it can be used for WordPress media files.
2018.08: Headless WordPress + Gatsby + Netlify continuous deployment - Guide showing how to create a WordPress + Gatsby + Netlify setup in a few simple steps.

Video Tutorials

2019.11: 25+ Videos - Gatsby + WordPress (2019) Complete Course - The series focuses on how we can use WordPress as a headless CMS with a GraphQL schema to interface with. After setting up our WordPress site and theme, we'll move onto Gatsby and how we can use our new schema to generate content for our Gatsby site, programmatically generating pages, converting Gutenberg blocks to React components and finishing off the chapter with a focus on SEO in Gatsby.
2019.07: Gatsby + WordPress with WPGraphQL (with Jason Bahl) — Learn With Jason - In this stream, Jason Bahl teaches how to use WordPress with Advanced Custom Fields and WPGraphQL to create an powerful, flexible admin dashboard, then query and display that data in a Gatsby site.
2019.07: Crash Course: Headless WordPress with WPGraphQL, ACF, and React - In this video, Alex Young (WPCasts) goes over how to get a simple headless WordPress setup with WPGraphQL and React.
2019.06: Using WordPress with WPGraphQL - In this video you will learn how to use GraphQL with WordPress using an awesome plugin named WPGraphQL and some extra cool stuff like GraphQL + Advanced Custom Fields.
2019.04: WPGraphQL for ACF - Jason Bahl shows how to use WPGraphQL for Advanced Custom Fields.
2018.07: GraphQL with WordPress and Gutenberg - Jason Bahl - 2018 JavaScript for WordPress Conference - In this talk from the 2018 JavaScript for WordPress Conference, the Developer of the WP GraphQL Plugin, Jason Bahl, gives updated examples of how you can use GraphQL with WordPress and Gutenberg.

Paid Tutorials / Courses

List of paid courses.

Please contribute known resources that use the current stack with newest versions.

Starters

List of project starters, that you can clone and start building upon.

Gatsby Starter - WordPress Twenty Twenty - A port of the WordPress Twenty Twenty theme to Gatsby using the new gatsby-source-wordpress@v4.
Gatsby + WPGraphQL Blog Example - Demo showing how to use WPGraphQL as the source for Gatsby Sites.
Gatsby + Headless WordPress + Netlify Starter - A Gatsby + WordPress starter for continuous deployment to Netlify.
Gatsby WordPress Starter Advanced - An advanced Gatsby + WordPress starter, that is built along a tutorial series and works with ACF flexible content fields to create content blocks/layouts.
Gatsby Starter Blog - Blog starter with enough features to be production ready out of the box.

Themes

List of gatsby-themes that work with WordPress as a source, which you can use in your Gatsby setup.

Twenty Nineteen Gatsby Theme - A port of the Twenty Nineteen WordPress Theme over to Gatsby.
Gatsby WordPress Publisher Theme - The Gatsby Publisher Theme allows you to create a headless (or decoupled) WordPress site. This theme will display all of your pages and posts in a static front-end built on React and Gatsby.

Gatsby with WPGraphQL, ACF and Gatbsy-Image

Henrik Wirth — Wed, 07 Aug 2019 18:22:27 +0000

So, there is a lot happening around Gatsby with WordPress and WPGraphQL. At times, it can get confusing and a lot of given functionality is hard to find or figure out. I am working on a client project right now and somehow had to handle images, that I source through my WordPress backend.

After trying out all sorts of solutions and working through the plugin library of Gatsby, I ended up finding a little piece of documentation, that led me to a solution, that works for me. And, because some very helpful people in the WPGraphQL Slack Chat asked me to write about that solution ... here I am.

I simply wanted to have my WordPress Media as static files inside my Gatsby app and work with the gatsby-image plugin for transformation/optimization.

Libraries used

GatsbyJs
- gatsby-source-graphql
- Gatsby-Image
WordPress
- ACF
- WPGraphQL | Docs
- WPGraphQL ACF

Gatsby Config

/* --------- gatsby-config.js --------- */

module.exports = {

  plugins: [

    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `images`,
        path: `${__dirname}/src/assets/images`,
      },
    },
    `gatsby-transformer-sharp`,
    `gatsby-plugin-sharp`,
    {
      resolve: "gatsby-source-graphql",
      options: {
        typeName: "WPGraphQL",
        fieldName: "wpgraphql",
        url: `https://${YOUR_DOMAIN}/graphql`,
      },
    },
  ]
}

Make sure all the plugins are mentioned correctly in your config file
For some reason, it can cause errors not having gatsby-source-filesystem used in the configs. Make sure it resolves to a valid path, even if there are no images inside the folder.

Gatsby Node


/* --------- gatsby-node.js --------- */

const { createRemoteFileNode } = require(`gatsby-source-filesystem`)

exports.createResolvers = async (
  {
    actions,
    cache,
    createNodeId,
    createResolvers,
    store,
    reporter,
  },
) => {
  const { createNode } = actions

  await createResolvers({
    WPGraphQL_MediaItem: {
      imageFile: {
        type: "File",
        async resolve(source) {
          let sourceUrl = source.sourceUrl

          if (source.mediaItemUrl !== undefined) {
            sourceUrl = source.mediaItemUrl
          }

          return await createRemoteFileNode({
            url: encodeURI(sourceUrl),
            store,
            cache,
            createNode,
            createNodeId,
            reporter,
          })
        },
      },
    },
  })
}

That's really all you need. Let's break it down a little:

WPGraphQL_MediaItem: This depends on your config. It starts with the typeName of your gatsby-source-graphql.
createRemoteFileNode gives you the ability to pull in remote files and automatically adds them to your schema.
imageFile: will be the type you can query (see below).
type: 'File': will add the MediaItems as Files, which is great, because now gatsby-image can make use of it.
url: encodeURI(sourceUrl): Here we encode the Url coming from WordPress, to make sure it is parsed correctly even if the image paths include umlauts.

Pages Query


# page.js

query {
  WPGraphQL {
    pages {
      nodes {
        featuredImage {
          sourceUrl
          imageFile {
            childImageSharp {
              fixed {
              ...GatsbyImageSharpFixed
              }
            }
          }
        }
      }
    }
  }
}

Important: Always query sourceUrl, otherwise it doesn't work, because the resolver would miss that data.

Final thoughts

Thats all there is to it. And it works with ACF Media files too. Same same.

Almost ... I think it is important to mention, that with this method all available Media-Files coming from WordPress will be pulled in the cache. So, if there is, for some reason, a clear of the cache happening, it would need to pull them in again I guess. For performance, it could still be more useful to somehow fetch all the Media-Files apart from the Gatbsy-Cache. That would mean though, you have to do the hard work of creating the schema yourself. I'm sure there will be great solutions for that too. Would be happy if someone has some experience with that and would share their thoughts :)

Caching

If your server doesn't support etags, the default caching of the gatsby-source-filsystem won't work.

You can checkout the custom solution by Robert Marshall here, which should be slightly faster and doesn't rely on etags: https://thoughtsandstuff.com/gatsby-with-wordpress-caching-downloaded-media-images-to-reduce-build-time/

Coming Up

I plan on writing up a big article about setting up Gatbsy + WordPress + ACF + Polylang for a client ready project with Multilanguage-Support and dynamic content creation through ACF's flexible content fields. I wonder if that would be of interest. Any thoughts and suggestions are highly appreciated.

References

See the Gatsby documentation of it here: https://www.gatsbyjs.org/docs/schema-customization/#feeding-remote-images-into-gatsby-image

DEV Community: Henrik Wirth

Introducing MobileUI

What is MobileUI?

Java-Based Cross-Platform Apps with Native Experience

Layouting and Styling with Ease

Extensibility is key

Instant Live Preview

Extensive Documentation & Support

Try it out with our MobileUI Gallery

PageBuilder with ACF Flexible Content - Guide to Gatsby WordPress Starter Advanced with Previews, i18n and more

Table of Contents

Install WordPress Plugins 💾

Create ACF fields and Content ✏️

1.) Create Flexible Content field

2.) Create Layouts inside the Flexible Content field

3.) Update your Pages

4.) Checkout the Schema

Add layouts to Gatsby 📰

1.) Add Hero layout

2.) Add TextBlock layout

3.) Add data to our page queries

Update pages data.js

Update createPages.js

Create utility function getAllLayoutsData

4.) Add AllLayouts component

5.) Update Page template

Improve performance through Template-String technique 🎩

1.) Add more utility functions

2.) Add layoutMapping.js

3.) Add lodash.uniqby and lodash.isempty

4.) Add/update createPages.js

5.) Add string based template

Explanation Video 🎥

Final Thoughts 🏁

What's Next ➡️

How to handle Images and make use of gatsby-image - Guide to Gatsby WordPress Starter Advanced with Previews, i18n and more

Table of Contents

Add Images to WordPress pages 💻

Make use of gatsby-image 📷

1.) Add Resolver to Gatsby

2.) Add fluid Image fragment

3.) Add fragment to createPages.js and createPosts.js

Update createPages.js

Add PageTemplateFragment

Update createPosts.js

Update PostTemplateFragment and BlogPreviewFragment

4.) Update Image.js to FluidImage.js

5.) Update page, blog and post template

Post Inline images 📝

Final Thoughts 🏁

What's Next ➡️

Blog with Pagination - Guide to Gatsby WordPress Starter Advanced with Previews, i18n and more

Table of Contents

Add content to WordPress 💻

1.) Create posts

2.) Add Menu Link

Implement Blog components 💾

1.) Add globals.js

2.) Create blog.js

3.) Create PostEntry.js

4.) Create Image.js

5.) Create Pagination.js

Adjust Post/Blog Creation 📓

1.) Add data.js

2.) Adjust createPosts.js

Final Thoughts 🏁

What's Next ➡️

Deployment - Guide to Gatsby WordPress Starter Advanced with Previews, i18n and more

Table of Contents

Netlify Setup ⚡

WordPress Plugin 💾

GitLab Setup 🐱

Gatsby Prefix Configuration

GitLab CI Configuration

Final Thoughts 🏁

What's Next ➡️

Setup Menu Navigation - Guide to Gatsby WordPress Starter Advanced with Previews, i18n and more

Table of Contents

Create WordPress Menu 🌐

Create Components in Gatsby 💻

3.) Add `lodash.uniqby` and `lodash.isempty`