Skip to main content

@gendive/react-notion-renderer

Notion 페이지와 데이터베이스를 React 컴포넌트로 바로 렌더링해주는 라이브러리입니다.

빠른 미리보기​

tip

위는 Notion 데이터베이스를 카드 형태로 렌더링한 예시입니다. 더 많은 데모 보기

이 라이브러리가 뭔가요?​

Notion을 CMS처럼 쓰고 싶을 때가 있죠?
예를 들어:

  • 블로그 글을 Notion에서 작성하고, 내 웹사이트에 보여주고 싶다
  • 프로젝트 목록을 Notion 데이터베이스로 관리하고, 카드 형태로 보여주고 싶다
  • 문서/매뉴얼을 Notion으로 작성하고, 별도 페이지에 임베드하고 싶다

이런 경우에 이 라이브러리를 쓰면 됩니다.

Notion API로 데이터를 가져와서 → React 컴포넌트로 예쁘게 렌더링해줍니다.

주요 기능​

1. 페이지 렌더링​

Notion 페이지의 모든 블록(heading, paragraph, code, image, callout 등)을 그대로 React로 렌더링합니다.

import { NotionPage } from '@gendive/react-notion-renderer';

// Notion 페이지를 그대로 보여줌
<NotionPage pageId="your-page-id" token="your-notion-token" />

2. 데이터베이스 렌더링 (3가지 레이아웃)​

레이아웃설명용도
board-card카드 그리드프로젝트 목록, 포트폴리오
table표 형태데이터 목록
list리스트 형태블로그 글 목록
import { NotionDatabaseById } from '@gendive/react-notion-renderer';

<NotionDatabaseById
  databaseId="your-database-id"
  token="your-notion-token"
  layout="board-card"  // 또는 "table", "list"
/>

3. 고급 기능​

  • 페이지네이션: 카드가 많을 때 페이지 나누기
  • 필터/정렬: Notion API 필터를 그대로 사용
  • 테마: 라이트/다크 모드 지원
  • 커스터마이징: 카드 스타일, 열 개수 등 세부 조정

설치​

npm install @gendive/react-notion-renderer

빠른 시작 (5분)​

1단계: Notion API 토큰 발급​

  1. Notion Integrations 접속
  2. "New integration" 클릭
  3. 이름 입력 후 생성
  4. Internal Integration Token 복사 (이게 API 토큰)

2단계: 페이지/데이터베이스에 Integration 연결​

  1. Notion에서 공유할 페이지 열기
  2. 우측 상단 ... → Connections → 만든 Integration 선택
  3. "Confirm" 클릭

3단계: 코드 작성​

// app/notion-demo/page.tsx (Next.js App Router 예시)
import { NotionPage } from '@gendive/react-notion-renderer';

export default function NotionDemoPage() {
  return (
    <NotionPage
      pageId="2baa76221f408089b1a9cfce9c133621"
      token={process.env.NOTION_TOKEN!}
    />
  );
}

끝! 이제 Notion 페이지가 React 앱에 보입니다.

데모 데이터로 테스트하기​

API 토큰 없이 먼저 테스트해보고 싶다면, 저희가 준비한 공개 데이터를 사용하세요:

종류링크
페이지 데모page-demo
데이터베이스 데모database-demo

Mock JSON 데이터도 /demo/mock-data/ 폴더에 있습니다.

문서 구조​

문서내용
페이지 렌더링페이지 렌더링 + 모달 사용법
보드 카드 레이아웃카드 그리드 + 페이지네이션
리스트/테이블 레이아웃테이블, 리스트 뷰
Embed & Media이미지, 비디오, embed 블록

처음이라면 페이지 렌더링 → 보드 카드 순서로 읽어보세요!