New plugin: Live Preview with Craft CMS and Gridsome

OUTDATED ARTICLE
NOGN offers a set of plugins to help pair Craft & Gridsome. See nogn.io for more.

JAMstack is Awesome! Headless CMS is awesome! Static sites are awesome!

Except for that big clunky elephant sitting awkwardly in the corner of the room. A deal breaker for many. Whenever a content manager updates something, they have to wait for some build process to run before seeing the changes. Ain't nobody got time for that!

With Gridsome and Craft CMS, this pain is gone!*

I've been searching for a golden static path for a long time, so am pretty excited to have cracked a solution with this mean combo. To make it easier for everyone, I made a plugin - @bhws/gridsome-source-craft-graphql.

Plugin key features

• Stitches your Craft GraphQL into Gridsome's GraphQL layer.
• Setup the template and routing config for your Craft content in Gridsome.
• Use the live preview panel of Craft CMS to preview updates. It won't feel like two separate systems to content managers. 🔥
• Preview links can also show the content updates in different contexts across the site (e.g a title change to a blog article can be seen when navigating to the blog listing page as well)
• This preview runs on the static build of the Gridsome site! So there's no need for setting up a node server just for a client previewing changes! That's geekily cool 😎(and cheap).

Enough chatter. Let's do this.

Gridsome

Install Gridsome

Install the Gridsome CLI, if you haven't already:

• YARN yarn global add @gridsome/cli
• or, NPM npm install --global @gridsome/cli

Create a gridsome project:

• gridsome create your-chosen-folder-name
• cd your-chosen-folder-name

Install the Craft source plugin

You'll need Gridsome on at least v0.7.12

• YARN yarn add @bhws/gridsome-source-craft-graphql
• or, NPM npm install @bhws/gridsome-source-craft-graphql

Setup the plugin config in your gridsome.config.js file:

module.exports = { 
    //...
    plugins: [
        {
          use: '@bhws/gridsome-source-craft-graphql',
          options: {
            url: 'https://example.com/api',
            fieldName: 'craft',
            typeName: 'craft',
            livePreview: true, // Use an .env setting to disable this in production            
          }
        }
    ]
    //...
}

Override Gridsome's App.vue

<template>
  <!-- ... -->
  <CraftLivePreview endpoint="https://example.com/api" />
  <!-- ... -->
</template>

<script>
export default {
  //...
  components: {
    CraftLivePreview: () => import ('@bhws/gridsome-source-craft-graphql/CraftLivePreview')
  }
  //...
}
</script>

Alternatively, you could put this component in a layout or template file. But overriding App.vue file is fairly common practice and well documented.

And, that's it!* 🎉

*Warning! This is still early days and a beta release. I'll be amazed if there aren't bumps ahead, so if you hit a problem, make an issue on GitHub. (or find me on twitter: @bhws).

From here you should be able to see the data from Craft in Gridsome's GraphQL explorer.

Craft Setup

Setup the GraphQL API on Craft (if you didn't already!)

Setup the Craft preview targets to point to the Gridsome build, with ?CraftPreviewSlug={slug} at the end. (This target can be your local version or a remote build).

Some extra tips for your Gridsome development

To setup your templates for the different Craft element types create files in the gridsome template directory(src/templates/) following the formats:

• Entries: ${fieldName}Entry${sectionHandle}${typeHandle}.vue
  Example - craftEntryNewsArticle.vue
• Categories: ${fieldName}Category${groupHandle}.vue
  Example: craftCategoryStatus.vue
• Tags: ${fieldName}Tag${groupHandle}.vue
  Example - craftTagCountries.vue

In the <page-query> of your template use the slug to reference the post. e.g:

<page-query>
query CraftEntry ($slug: [String] ) {
  craft {
    entries (slug: $slug)  {
      id
      title
    	... on craft_blog_article_Entry {
        text
      }
    }
  }
}
</page-query>

I'm looking to eventually get id/uid working, but for now slug is your best bet.

If you're already familiar with building a site with Gridsome, that's hopefully enough to get you up and running.

I'll be posting more articles on Gridsome (with Craft) in the near future. So, if you're new to Gridsome or even JAMstack, stayed tuned as there will be better starting points to get you up and running.