@texonom/ncompat NPM

ncompat

A compatibility layer between the official Notion API and the unofficial Notion API

Features

fully compatible with nreact
backwards compatible with nclient and the unofficial notion API

Usage

import { Client } from '@notionhq/client'
import { NotionCompatAPI } from '@texonom/ncompat'

const notion = new NotionCompatAPI(new Client({ auth: process.env.NOTION_TOKEN }))

const recordMap = await notion.getPage(pageId)

The resulting recordMap is compatible with notion's unofficial API and nreact.

Demo

You can preview nreact using the official client and compatibility layer here: https://nreact-official-api-demo.transitivebullsh.it/

Status

Currently, ~20 blocks have full compatibility and 8 have partial compatibility (sometimes in subtle ways) due Notion's official API not returning enough info for us to faithfully render them in all cases. See the block-by-block compatibility notes below for more info.

I recommend checking out the ncompat demo side-by-side with the normal nreact demo (which uses the unofficial Notion API via nclient) and the equivalent public notion page.

Note that using the official API with ncompat is significantly slower than using the unofficial API via nclient because of reasons.

The main feature missing from ncompat right now is collection (database) support. PRs welcome 😃

Block Compatibility

Summary of Known Issues 🔴

image, video, and embed blocks are missing format for proper sizing and layout
- 3492bd6dbaf44fe7a5cac62c5d402f06
- 5d4e290ca4604d8fb809af806a6c1749
image, video, and embed blocks are missing caption
- 912379b0c54440a286619f76446cd753
embed blocks don't contain enough info for proper embedding
- have to write custom embedding logic for iframe urls
- same with some video blocks
- 5d4e290ca4604d8fb809af806a6c1749
alias blocks fail for links pointing to other workspaces
- this happens even if the linked page is publicly readable
- 034119d20132420abe8e9863bbe91e9d
rich text mentions fail for links to pages and databases in other workspaces
- if API integration doesn't have access to the workspace
- this happens even if the linked page is publicly readable
- 52353862df0f48ba85648db7d0acd1dd
format toggleable is missing
- no toggle headers
- 5995506f2c564d81956aa38711e12337

Blocks with Full Compatibility 🟢

paragraph (text block)
heading_1 (header block)
heading_2 (sub_header block)
heading_3 (sub_sub_header block)
bulleted_list_item (bulleted_list block)
numbered_list_item (numbered_list block)
quote
to_do
toggle
code
callout
file
divider
table_of_contents
column_list
column
equation (block and inline)
synced_block (transclusion_container and transclusion_reference)
audio
tweet

Blocks with Partial Compatibility 🟡

bookmark
- images and content are missing
- 0be6efce9daf42688f65c76b89f8eb27
image
- missing caption
- missing format so sizing and layout aren't always handled properly
- 912379b0c54440a286619f76446cd753
video
- missing caption
- missing format so sizing and layout aren't always handled properly
- missing embedding logic in some cases (original URL must be transformed for embedding in many cases)
- 5d4e290ca4604d8fb809af806a6c1749
embed
- missing caption
- missing format so sizing and layout aren't always handled properly
- missing embedding logic
  - original URL must be transformed for embedding in many cases
  - missing embeding display size hints from embedly
- 5d4e290ca4604d8fb809af806a6c1749
- this goes for custom embed blocks as well
  - maps
  - figma
  - typeform
  - codepen
  - excalidraw
  - gist
  - loom
  - drive
  - ...
child_page (page block)
- page format missing entirely
- no full width, fonts, font size, etc
  - 72c5d33ca46642feaee06852cc57c588
  - 3702a5d6403d4d58b8a944a77ca26c70
- page cover missing page_cover_position
  - 067dd719a912471ea9a3ac10710e7fdf
link_to_page (alias block)
- missing for links pointing to other workspaces, even if they're publicly readable
- 034119d20132420abe8e9863bbe91e9d
pdf
- missing format so sizing and layout aren't handled properly
table and table_row (simple table blocks)
- missing some formatting info