适用于 Notion 的快速、准确的 React 渲染器。包含 TS 电池。 ⚡️
# React Notion X > Fast and accurate React renderer for Notion. TS batteries included. ⚡️ [](https://github.com/NotionX/react-notion-x/actions/workflows/test.yml) [](https://oxc.rs) ## Contents - [Contents](#contents) - [Advice](#advice) - [Features](#features) - [Usage](#usage) - [Styles](#styles) - [Optional Components](#optional-components) - [Private Pages](#private-pages) - [Next.js Examples](#nextjs-examples) - [Packages](#packages) - [Supported Blocks](#supported-blocks) - [Performance](#performance) - [Related](#related) - [Contributing](#contributing) - [License](#license) ## Advice If you want more control over your website via React, then we recommend checking out the accompanying [Next.js starter kit](https://github.com/transitive-bullshit/nextjs-notion-starter-kit), which is free and uses `react-notion-x` under the hood. And if you want even more control, then you're in the right place! ## Features - **Simple** - TypeScript + React - ⚡ **Fast** - 10-100x faster than Notion - 95-100% Lighthouse scores - Heavier components can be loaded lazily via `next/dynamic` - **Tests** - Comes with a comprehensive [test suite](https://www.notion.so/Notion-Test-Suite-067dd719a912471ea9a3ac10710e7fdf) covering most of Notion's functionality - **Solid** - Used in production by tens of thousands of websites - **Smooth** - Supports `next/image` along with LQIP preview images ([demo](https://react-notion-x-demo.transitivebullsh.it/3492bd6dbaf44fe7a5cac62c5d402f06)) - Framework agnostic - Use with next.js, vite, remix, etc ## Usage First you'll want to fetch the content for a Notion page: ```ts import { NotionAPI } from 'notion-client' const notion = new NotionAPI() const recordMap = await notion.getPage('067dd719a912471ea9a3ac10710e7fdf') ``` Once you have the data for a Notion page, you can render it via React: ```tsx import React from 'react' import { NotionRenderer } from 'react-notion-x' export default ({ recordMap }) => ( ) ``` Note: for heavier blocks, you'll have to opt into using them via `NotionRenderer.components`. These are not included in the default `NotionRenderer` export because they're too heavyweight for many use cases. ## Styles You'll need to import some CSS styles as well. If you're using Next.js, we recommend you place these imports at the top of `pages/_app.js`: ```ts // core styles shared by all of react-notion-x (required) import 'react-notion-x/styles.css' // used for code syntax highlighting (optional) import 'prismjs/themes/prism-tomorrow.css' // used for rendering equations (optional) import 'katex/dist/katex.min.css' ``` ## Optional Components The default imports from `react-notion-x` strive to be as lightweight as possible. Most blocks will render just fine, but some larger blocks like PDFs and collection views (database views) are not included by default. To use them, you'll need to import the ones you want from `react-notion-x/third-party/*`: ```tsx import { Code } from 'react-notion-x/third-party/code' import { Collection } from 'react-notion-x/third-party/collection' import { Equation } from 'react-notion-x/third-party/equation' import { Modal } from 'react-notion-x/third-party/modal' import { Pdf } from 'react-notion-x/third-party/pdf' ``` Note that we strongly recommend lazy-loading these components unless you know you'll need them up front for your use case. If you're using Next.js, you can use [next/dynamic](https://nextjs.org/docs/advanced-features/dynamic-import) to lazily load them. If your notion content doesn't use one of these heavyweight components, then it won't get loaded into your page. This keeps the initial page bundle small and your website feeling snappy. ```tsx import dynamic from 'next/dynamic' const Code = dynamic(() => import('react-notion-x/third-party/code').then((m) => m.Code) ) const Collection = dynamic(() => import('react-notion-x/third-party/collection').then((m) => m.Collection) ) const Equation = dynamic(() => import('react-notion-x/third-party/equation').then((m) => m.Equation) ) const Pdf = dynamic( () => import('react-notion-x/third-party/pdf').then((m) => m.Pdf), { ssr: false } ) const Modal = dynamic( () => import('react-notion-x/third-party/modal').then((m) => m.Modal), { ssr: false } ) ``` You'll need to enable them by passing them to the `components` prop of `NotionRenderer`. ```tsx export default ({ recordMap }) => ( ) ``` The `Code` component uses [Prism](https://prismjs.com) under the hood. It comes bundled with support for JavaScript, TypeScript, and CSS by default. To add support for additional language syntaxes, follow the example in [`components/NotionPage.tsx`](./examples/full/components/NotionPage.tsx) which lazily loads Prism components at runtime. You will likely want to add `prismjs` to your project as a dependency when using the `Code` component so TypeScript doesn't complain. For `Equation` support, you'll need to import the katex CSS styles. For each of these optional components, make sure you're also importing the relevant third-party CSS if needed ([above](#Styles)). ## Private Pages You may optionally pass an `authToken` and `activeUser` to the API if you want to access private Notion pages. Both can be retrieved from your web browser. Once you are viewing your workpace, open your Development Tools > Application > Cookie > and Copy the `token_v2` and `notion_user_id`. Respectively, activeUser: notion_user_id, authToken: token_v2. We recommend storing these as environment variables and passing them into the `NotionAPI` constructor as follows: ```tsx const notion = new NotionAPI({ activeUser: process.env.NOTION_ACTIVE_USER, authToken: process.env.NOTION_TOKEN_V2 }) ``` Note that this is not the same as the API token provided by the official Notion API since `notion-client` uses the unofficial Notion API (which is what all Notion apps use). ## Next.js Examples Here's a [minimal Next.js example project](./examples/minimal) with the most important code in [`pages/[pageId].tsx`](./examples/minimal/pages/%5BpageId%5D.tsx) and [`components/NotionPage.tsx`](./examples/minimal/components/NotionPage.tsx). You can view this example [live on Vercel](https://react-notion-x-minimal-demo.transitivebullsh.it). Here's a more [full-featured Next.js example project](./examples/full) with the most important code in [`pages/[pageId].tsx`](./examples/full/pages/%5BpageId%5D.tsx) and [`components/NotionPage.tsx`](./examples/full/components/NotionPage.tsx). You can view this example [live on Vercel](https://react-notion-x-demo.transitivebullsh.it). The full-featured demo adds a few nice features: - Uses [next/image](https://nextjs.org/docs/app/api-reference/components/image) to serve optimal images - Uses preview images generated via [lqip-modern](https://github.com/transitive-bullshit/lqip-modern) - Lazily bundles larger optional components via [next/dynamic](https://nextjs.org/docs/advanced-features/dynamic-import) - Code - Equation - Pdf - Modal - Collection (e.g., notion databases including table and gallery views) For a production example, check out the [Next.js Notion Starter Kit](https://github.com/transitive-bullshit/nextjs-notion-starter-kit), which uses `react-notion-x` under the hood. ## Packages | Package | NPM | Environment | Description | | --- | --- | --- | --- | | [react-notion-x](./packages/react-notion-x) | [](https://www.npmjs.com/package/react-notion-x) | Browser + SSR | Fast React renderer for Notion. | | [notion-client](./packages/notion-client) | [](https://www.npmjs.com/package/notion-client) | Server-side\* | Robust TypeScript client for the Notion API. | | [notion-types](./packages/notion-types) | [](https://www.npmjs.com/package/notion-types) | Universal | Core Notion TypeScript types. | | [notion-utils](./packages/notion-utils) | [](https://www.npmjs.com/package/notion-utils) | Universal | Useful utilities for working with Notion data. | | [notion-compat](./packages/notion-compat) | [](https://www.npmjs.com/package/notion-utils) | Server-side | Compatibility layer between the official Notion API and unofficial private API. | | [notion-x-to-md](./packages/notion-x-to-md) | [](https://www.npmjs.com/package/notion-x-to-md) | Universal | Converts a Notion page to Markdown. Very useful for LLMs. | \* Notion's API should not be called from client-side browsers due to CORS restrictions. `notion-client` is compatible with Node.js, Bun, Deno, CF workers, etc. ## Supported Blocks The majority of Notion blocks and collection views are fully supported. | Block Type | Supported | Block Type Enum | Notes | | --- | --- | --- | --- | | Page | ✅ Yes | `page` | | Text | ✅ Yes | `text` | Supports all known text formatting options | | Bookmark | ✅ Yes | `bookmark` | Embedded preview of external URL | | Bulleted List | ✅ Yes | `bulleted_list` | `
暂无开放 Issues，或尚未同步最近议题。