notion-compat

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

Features

- fully compatible with react-notion-x
- backwards compatible with notion-client and the unofficial notion API

Usage

``ts
import { Client } from '@notionhq/client'
import { NotionCompatAPI } from 'notion-compat'

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 react-notion-x.

Demo

You can preview react-notion-x using the official client and compatibility layer here: https://react-notion-x-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 notion-compat demo side-by-side with the normal react-notion-x demo (which uses the unofficial Notion API via notion-client) and the equivalent public notion page.

Note that using the official API with notion-compat is significantly slower than using the unofficial API via notion-client because of reasons.

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

Block Compatibility

$3

- 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

$3

- 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

$3

- 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

$3

- child_database (collection_view and collection_view_page` blocks)

$3

- external_object_instance

$3

- breadcrumb
- template
- unsupported

License

MIT © Travis Fischer

Support my OSS work by following me on twitter