Nifty Pony Merchandise

    notion-compat
    TypeScript icon, indicating that this package has built-in type declarations

    6.15.6 • Public • Published

    React Notion X

    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 '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 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

    Blocks that are WIP 🚧

    • child_database (collection_view and collection_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 twitter

    Keywords

    none

    Install

    npm i notion-compat

    DownloadsWeekly Downloads

    1,300

    Version

    6.15.6

    License

    MIT

    Unpacked Size

    65.5 kB

    Total Files

    5

    Last publish

    Collaborators

    • fisch0920
    • noahbragg