@onnimonni/notion-compat
v6.17.0-alpha.1
Published
Compatibility layer between the official Notion API and unofficial private API.
Downloads
205
Readme
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
import { Client } from '@notionhq/client'
import { NotionCompatAPI } from '@onnimonni/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
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
andtransclusion_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
Blocks that are WIP 🚧
- child_database (
collection_view
andcollection_view_page
blocks)
Blocks that are Not Supported 🔴
- external_object_instance
Blocks that I'm not sure how to handle
- breadcrumb
- template
- unsupported
License
MIT © Travis Fischer
Support my OSS work by following me on twitter