Using the Notion API for SSG is simple right?

Notion is great. It provides a very solid API but it isn’t super easy to use for SSG.
It’s designed to be broadly applicable, following Notion philosophy.

📢

Sidebar: Why pre-render your website? SEO & Performance. When you have a lot of content, pre-rendering is even more important (the ROI is higher).

Notion API is powerful, but not easy to use for this case.

An example:

Many API calls are required.

query database (1x)
query each individual page for its content
parse all page content blocks and transform each into desired format
🔁 repeat for each page

When a project is spread over many Notion pages getting fresh content when developing can take long!
Wait, can’t we use concurrency to make # of pages irrelevant?
- rate limits. p-map makes sure you don’t get 429s but makes fetching all data take longer.
- pages with lots of blocks (or dbs with lots of pages) use pagination and require sequential requests
Technical overhead of implementing a custom solution.

Existing Solutions

Notion-client and React-Notion-X

Notion-X

React only
1-to-1 block to component mapping
unofficial API (reverse engineered)
Mature, robust, well tested
fast out of the box (tip: unofficial API is more performant)

NotionCMS

Agnostic
custom per block renderers
official API - versioned, stable, no breaking changes
new, not all blocks have renders (but just build one!)

Different approaches.

NotionCMS generates a data object that holds static content. You can feed this into your reactivity framework but the blocks are not “components” like react-notion-x is.

This makes NotionCMS more flexible.

How `NotionCMS`works

routes = [
  '/about',
  '/team',
  '/team/jacob',
  '/team/mordecai',
  '/pricing',
  '/posts',
  '/posts/how-to-use-notion-cms',
  '/posts/how-to-build-a-blog-with-notion'
]

NotionCMS reigns in the power of Notion API by trading off flexibility for a defined handshake with the API.
We do this is to require the use of a DB structured in a specific way.
It’s explicit, but also generic enough to meet most “webby” use cases (that require DAGs).
This structure lets us apply patterns that make accessing Notion data very easy via NotionCMS API.

Slides