What problems does NotionCMS solve?

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.
  1. query database (1x)
  2. query each individual page for its content
  3. parse all page content blocks and transform each into desired format
  4. 🔁 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 NotionCMSworks

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.