gatsby-source-microcms

Source plugin for Gatsby from microCMS.

Install

# npm
$ npm install gatsby-source-microcms

# or yarn
$ yarn add gatsby-source-microcms

How to use

gatsby-config.js

First, to fetch contents from microCMS, you need setting options in gatsby-config.js.

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-microcms',
      options: {
        apiKey: 'MICROCMS_API_KEY',
        serviceId: 'myblog',
        apis: [
          {
            endpoint: 'posts',
          },
        ],
      },
    },
  ],
};

gatsby-node.js

You can query like the following. Gatsby create Pages based on microCMS contents.

exports.createPages = async ({ graphql, actions }) => {
  const { createPage } = actions;

  const result = await graphql(
    `
      {
        allMicrocmsPost(sort: { fields: [createdAt], order: DESC }) {
          edges {
            node {
              id
              createdAt
            }
          }
        }
      }
    `
  );

  if (result.errors) {
    throw result.errors;
  }

  result.data.allMicrocmsPost.edges.forEach((post, index) => {
    createPage({
      path: post.node.id,
      component: path.resolve('./src/templates/blog-post.js'),
      context: {
        slug: post.node.id,
      },
    });
  });
};

Options

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-microcms',
      options: {
        /**
         * The authentication key required for API requests. (Required)
         *
         * Type: string.
         **/
        apiKey: '11111111-2222-3333-4444-555555555555',

        /**
         * Service information. (Required)
         * xxxx.microcms.io
         *
         * Type: string.
         **/
        serviceId: 'xxxx',

        /**
         * API information. (Required)
         * Multiple APIs can be specified.
         *
         * Type: array.
         **/
        apis: [
          {
            /**
             * API endpoint name. (Required)
             * https://xxxx.microcms.io/api/v1/posts
             *
             * Type: string.
             **/
            endpoint: 'posts',

            /**
             * Graphql type. (Optional)
             * This is used in GraphQL queries.
             * If type = 'post', the GraphQL types are named 'microcmsPost' and 'allMicrocmsPost'.
             *
             * Type: string.
             * Default: endpoint value.
             **/
            type: 'post',

            /**
             * microCMS's content type('list' or 'object'). (Optional)
             * if format is 'list', read all contents by fetching multiple times.
             *
             * Type: string.
             * Default: 'list'.
             **/
            format: 'object',

            /**
             * API request query options. (Optional)
             *
             * Type:
             *   draftKey: string.
             *   limit: number.
             *   offset: number.
             *   fields: string.
             *   filters: string.
             *   depth: number.
             * Default: {}.
             **/
            query: {
              draftKey: 'DRAFT_KEY',
              limit: 100,
              offset: 40,
              fields: ['id', 'title', 'body'].join(','),
              filters: 'tag[exists]',
              depth: 2,
            },
          },
        ],
      },
    },
  ],
};

filters

This plugin provides filters query building helper.

// gatsby-config.js
const {
  and,
  contains,
  exists,
} = require('gatsby-source-microcms/src/query-builder');

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-microcms',
      options: {
        apis: [
          {
            query: {
              filters: and(contains('title', 'sale'), exists('tag')),
              //=> `title[contains]sale[and]tag[exists]`
            },
          },
        ],
      },
    },
  ],
};

Helper list:

• equals (alias: eq)

equals('gender', 'women');
//=> gender[equals]women

• notEquals (alias: neq)

notEquals('gender', 'women');
//=> gender[not_equals]women

• lessThan (alias: lg)

lessThan('createdAt', '2019-11');
//=> createdAt[less_than]2019-11

• greaterThan (alias: gt)

greaterThan('createdAt', '2019-11');
//=> createdAt[greater_than]2019-11

• contains

contains('title', 'sale');
//=> title[contains]sale

• exists

exists('nextLink');
//=> nextLink[exists]

• notExists

notExists('nextLink');
//=> nextLink[not_exists]

• beginsWith

beginsWith('publishedAt', '2019-11');
//=> publishedAt[begins_with]2019-11

• and

and('filter1', 'filter2', ..., 'filter10')
//=> filter1[and]filter2[and]...[and]filter10

• or

or('filter1', 'filter2', ..., 'filter10')
//=> filter1[or]filter2[or]...[or]filter10

Contributing

日本語歓迎 🇯🇵 Pull Request, Issue お気軽にどうぞ。