gatsby-source-notion-database

0.6.9 verified Fri May 01 auth: no javascript maintenance

A Gatsby source plugin that loads data from Notion databases into Gatsby's GraphQL layer. Version 0.6.9 is the latest stable release; the project has low release cadence (last update in 2021). It supports multiple database sources, optional caching (static vs dynamic), and automatically resolves relation properties. Compared to alternatives like gatsby-source-notion, this plugin offers a simpler configuration and direct table URL input, but has not been actively maintained and may lack support for newer Notion API changes.

Common errors

error Error: "gatsby-source-notion-database" threw an error while running: "Cannot read property 'results' of undefined" ↓

cause Invalid or missing Notion API token (not configured).

fix

Set the environment variable NOTION_TOKEN with a valid integration token.

error TypeError: sourceConfig is not iterable ↓

cause sourceConfig option missing or not an array.

fix

Provide sourceConfig as an array of objects in gatsby-config.js.

error GraphQL Error: Unknown type 'allBooks' ↓

cause The sourceConfig 'name' does not match the query name.

fix

Ensure the name option (e.g., 'books') matches the GraphQL query prefix (allBooks).

Warnings

breaking Plugin uses old Notion API (v1) which may stop working as Notion deprecates v1. ↓

fix Migrate to a plugin that supports Notion API v2 or use official Notion SDK.

deprecated cacheType option is deprecated — 'static' and 'dynamic' no longer have effect. ↓

fix Remove cacheType from sourceConfig or leave as static.

gotcha Table URL must be the full URL including view ID (?v=...). Missing view ID results in empty data. ↓

fix Ensure the table URL includes the '?v=...' query parameter from Notion.

gotcha Relation properties may not resolve correctly if the related database is also not sourced. ↓

fix Source all related databases in the sourceConfig array.

Install

npm install gatsby-source-notion-database

yarn add gatsby-source-notion-database

pnpm add gatsby-source-notion-database

Imports

gatsby-source-notion-database

wrong

import gatsbySourceNotionDatabase from 'gatsby-source-notion-database'

correct

module.exports = { plugins: [{ resolve: `gatsby-source-notion-database`, options: { sourceConfig: [...] } }] }

This is a Gatsby plugin, not a regular npm module; it is configured in gatsby-config.js via resolve, not imported.

all<Name>
wrong
```
query { allNotionPosts { ... } }
```
correct
```
query { allPosts { nodes { name } } }
```
The GraphQL type is auto-generated from the 'name' option in sourceConfig; prefix 'all' is added automatically.

notionDatabase

wrong

import { graphql } from 'gatsby-source-notion-database'

correct

import { useStaticQuery, graphql } from 'gatsby'; const data = useStaticQuery(graphql`{ allBooks { nodes { ... } } }`)

This plugin does not export any functions; use standard Gatsby queries to access data.

Quickstart

Configure the plugin with a Notion database table URL, then query the data in a Gatsby page using GraphQL.

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-notion-database`,
      options: {
        sourceConfig: [
          {
            name: "books",
            table: "https://www.notion.so/workspace/abc123?v=xyz789",
            cacheType: "static"
          }
        ]
      }
    }
  ]
};

// pages/index.js
import React from "react";
import { graphql } from "gatsby";

export const query = graphql`
  query {
    allBooks {
      nodes {
        name
        tags
      }
    }
  }
`;

const IndexPage = ({ data }) => {
  return (
    <ul>
      {data.allBooks.nodes.map(book => (
        <li key={book.name}>{book.name}</li>
      ))}
    </ul>
  );
};

export default IndexPage;