Gatsby integration

Gatsby is a powerful static site generator, and integrating it with your CMS allows you to leverage your existing content and build blazing-fast websites. The gatsby-source-decoupla plugin provides a seamless way to fetch data from your Decoupla CMS and use it within your Gatsby project.

This article will guide you through the process of setting up and using gatsby-source-decoupla to pull content from your Decoupla CMS into your Gatsby site.

Prerequisites

• A Gatsby project (if you don't have one, you can create one using gatsby new my-site)
• A Decoupla CMS account with a workspace and content
• Your Decoupla Workspace ID and API tokens (Live and Preview)

Installation

1. Install the plugin:

   npm install gatsby-source-decoupla
   

Configuration

1. Configure gatsby-config.js:

   Open your gatsby-config.js file and add the gatsby-source-decoupla plugin to the plugins array. You'll need to provide your Decoupla Workspace ID and API token in the options object.

   module.exports = {
     plugins: [
       {
         resolve: `gatsby-source-decoupla`,
         options: {
           workspace: `your_workspace_id`,
           token: `your_token`, // Use your Live or Preview Token.
         },
       },
     ],
   };
   

   Important:

   • Replace your_workspace_id with your actual Workspace ID.
   • Replace your_token with your Live API token for production builds or your Preview API token for development and preview builds. You can find these tokens in the API settings of your Decoupla dashboard.
   • It is highly recommended to store your API tokens as environment variables rather than directly in your gatsby-config.js file for security reasons.

   Example using environment variables:

   require("dotenv").config({
     path: `.env.${process.env.NODE_ENV}`,
   })
   
   module.exports = {
     plugins: [
       {
         resolve: `gatsby-source-decoupla`,
         options: {
           workspace: process.env.DECOUPLA_WORKSPACE_ID,
           token: process.env.DECOUPLA_API_TOKEN,
         },
       },
     ],
   };
   

   Then create .env.development and/or .env.production files and add your variables.

   DECOUPLA_WORKSPACE_ID=your_workspace_id
   DECOUPLA_API_TOKEN=your_token
   

2. Restart the development server:

   If you're running gatsby develop, stop the server and restart it to apply the changes.

Querying Data with GraphQL

Once the plugin is configured, you can query your Decoupla CMS data using Gatsby's GraphQL API.

1. Open the GraphiQL explorer:

   In your browser, navigate to http://localhost:8000/___graphql. This is the GraphiQL interface, which allows you to explore your GraphQL schema and test queries.

2. Explore the schema:

   In the GraphiQL explorer, you'll find your Decoupla data available under the Decoupla root query. Your content types will be available directly under the Decoupla root, and will require a first argument to retrieve the content. Explore the available types and fields to understand the structure of your data.

3. Write a GraphQL query:

   Here's an example query to fetch all posts from your Decoupla CMS:

   query {
     Decoupla {
       allPost(first: 100) { # Adjust 'first' as needed.
         edges {
           node {
             title
             slug
             content
           }
         }
       }
     }
   }
   

   Replace Post with the name of your content type in Decoupla. The first: 100 argument specifies the number of items to retrieve. Adjust this value as needed.

   Note: All the generated GraphQL Types in the Gatsby integration are prefixed with Decoupla_, e.g: The Content Type Post will become Decoupla_Post. And all the available queries are under the Decoupla { ... } root field, the name of the queries and their arguments will remain the same as in our GraphQL API.

4. Use the query in your Gatsby components:

   You can use the useStaticQuery hook or the StaticQuery component to fetch data in your Gatsby components.

   Example using useStaticQuery in a page component:

   import React from "react";
   import { graphql, useStaticQuery } from "gatsby";
   
   const PostsPage = () => {
     const data = useStaticQuery(graphql`
       query {
         Decoupla {
           allPost(first: 100) {
             edges {
               node {
                 title
                 slug
                 content
               }
             }
           }
         }
       }
     `);
   
     const posts = data.Decoupla.allPost.edges;
   
     return (
       <div>
         <h1>Posts</h1>
         {posts.map((postEdge) => (
           <div key={postEdge.node.slug}>
             <h2>{postEdge.node.title}</h2>
             <p>{postEdge.node.content}</p>
           </div>
         ))}
       </div>
     );
   };
   
   export default PostsPage;
   

Previewing Content

To preview content from your Decoupla CMS, use your Preview API token in your gatsby-config.js or .env file. This will allow you to see draft and unpublished content in your development environment.