🧑🏼‍🏭 Don't mind us, we are still working on this site using NotionCMS! Like this project? Sponsor us on GitHub: ⚡️⚡️⚡️ Get Started ⚡️⚡️⚡️
⏳: ~3 min read.
🗺️: current location: /notion-cms/guide/api

API Reference

const myAdvancedCMS = new NotionCMS({
  databaseId: 'e4fcd5b3-1d6a-4afd-b951-10d56ce436ad',
  notionAPIKey: process.env.NOTION,
  rootAlias: '/my-top-most-post', // replaces key with '/' for lookups
  rootUrl: 'https://mycoolsite.com',
  localCacheDirectory: './localcache/',
  refreshTimeout: 'one hour', // Or a number, 60 * 1000 * 60
  plugins: [customPlugin()],

// Then use NotionCMS
await myAdvancedCMS.pull()

We’ll go through all the available options here. You don’t need anything besides the databaseId and the notionAPIKey to get started right away, but using these other options grants you some major flexibility in using NotionCMS.

rootUrl: string

default: ''

This sets the actual url for your site that your are building. Setting this option lets you set the full urls for any path in case you want to use those in templates or for some SEO wizardry.

localCacheDirectory: string

default: node_modules/@agency-kit

This option lets you manually set the NotionCMS cache location. By default it will live deep within your node_modules folder, out of sight and doing its job keeping you blissfully unaware. There might be a couple of reasons you would want to set the location though - if you want to commit the cache to git for some reason, or if you clear it often, maybe you want quicker access. Its not recommended that you use this for inspection though as the cache is optimized in a way that makes it difficult to read. If you need to inspect NotionCMS output, use the export({pretty: true}) helper.

refreshTimeout: number | string

default: 0

This gives you control over how often the cache will be reset and fresh content from Notion API will be fetched. If you are developing and not changing content frequently, a longer timeout is better. If you find yourself updating content constantly alongside development as your process, then you probably want a shorter timeout or perhaps no timeout at all, which will force a fresh pull of all pages in your database every time NotionCMS fetch is run. With larger databases this can take a long time! If you want to type a “human readable” interval of time (e.g. “one hour”, “forty-five seconds”, “6 days”, these are all valid) you can!

draftMode: boolean

default: false

By default NotionCMS will only pull content that is set to published in the Publish property in the database. If you want to pull everything, including drafts, set draftMode to true.

debug: boolean

default: false

Setting this to true will just force a log out of certain information along the way. Useful for development.

plugins: array

Provide a list of plugins to run. See our in depth documentation on plugins.

rootAlias: string

default: ''

The root alias is a string should be equivalent to one of the Page’s route (so like /my-route-with-slugs when the page’s title is ‘My Route with Slugs’) from your Notion db, most likely the one on the top most level, e.g. the ancestor of all pages. When you assign a root alias, NotionCMS replaces that page’s identifier in the ncms tree with / so that you can match against the root route like you normally would in a router without having to define the match explicitly in the router code. The original title and slugs are still available in the page’s object.

autoUpdate: boolean

Default: true

This is a powerful default setting that turns on optimization of when we pull all the page content from Notion, which can save a lot of time when you are working with medium or large projects. When this is turned on, only pages that were updated since the last pull are requested and updated in your data tree.

we make notionware. 2023 \c\