Introduction
Build sites on the official Notion API, rendered with React Server Components.
notion-kit is two small packages for using Notion as the place you write, and your own site as the place you publish.
@yokinist/notion-fetch
Fetch pages and database rows without hitting rate limits, and serve uploaded files from URLs that do not expire. No framework needed.
@yokinist/notion-rsc
Render Notion blocks to HTML on the server, with Shiki, KaTeX and click-to-load embeds. Needs only React 19.
Why
- Official API. Both packages work with an integration token and
@notionhq/client, so they do not break when Notion changes its private API. - Content ships as HTML, not JavaScript. Pages render to plain, semantic HTML on the server, so the renderer never reaches the browser. Code highlighting and math happen at render time, so Shiki and KaTeX stay out of your bundle.
- Static pages that keep working. Files uploaded to Notion get URLs that expire after an hour. notion-fetch serves them from a route that redirects to a fresh URL, so cached and statically generated pages keep their images.
- No third-party cookies. YouTube, Spotify and SoundCloud players show a preview and load only when clicked.
Compared with react-notion-x
react-notion-x is the mature, widely used choice, and the two aim at different things.
- Where the data comes from. react-notion-x reads Notion's private API, the one the Notion app itself uses. That data includes database view settings, so it can render tables, galleries and boards, and it can render public pages without an integration; the trade-off is that the private API can change without notice. notion-kit uses the official API, which is documented and stable but does not expose views, so database views are out of reach.
- Where the code runs. react-notion-x components render on the server and then hydrate in the browser, so they work in any React app. notion-rsc is made of Server Components that never reach the browser, so it needs an RSC framework.
- How pages look. react-notion-x reproduces Notion's own look. notion-rsc outputs plain HTML for your site's typography to style, so posts look like the rest of your site.
| notion-kit | react-notion-x | |
|---|---|---|
| Notion API | Official, with an integration token | Private; official API data only through the notion-compat layer |
| Rendering | Server Components, no hydration | Server-side rendering, then hydration |
| JavaScript for content | Only click-to-load players and parts of posts on X | The renderer (about 31 kB gzipped), plus Prism, KaTeX, react-pdf and others when used |
| Look | Your site's typography | Notion's |
| Database views | No | Table, gallery, board and list |
| Framework | React 19 Server Components (Next.js App Router, Waku, …) | Any React app |
react-notion-x can also render official API data by converting it with notion-compat. As of notion-compat 8.0.8, that path targets @notionhq/client 2.x (the current release is 5.x), has no database view support, and leaves some blocks partial: bookmarks without their image and description, and images, videos and embeds without captions. notion-kit is built for the current official API and fills those gaps.