노션에서 작성한 글을 실시간으로 웹사이트에 연동하기

자주 업데이트되는 정보 페이지(공지, FAQ, 문서)를 개발자가 매번 코드로 고치는 것은 비효율적입니다. 노션(Notion)에서 글을 작성하면 웹사이트에 실시간으로 반영되게 하면, 비개발자도 노션만 수정해 콘텐츠를 관리할 수 있습니다. React에서 react-notion으로 이를 구현하는 방법을 정리합니다.

1. 노션 페이지 웹 공유 + API 확인

1. 노션 페이지 우측 상단 공유 → 웹에서 공유를 켭니다.
2. 생성된 URL의 마지막 부분(페이지 ID)을 복사합니다.
3. 아래 주소에 그 ID를 붙여 JSON이 잘 나오는지 확인합니다.

https://notion-api.splitbee.io/v1/page/{공유주소의_마지막_페이지ID}

splitbee가 제공하는 이 공개 API가 노션의 비공식 데이터를 JSON으로 변환해 줍니다.

2. react-notion 설치

yarn add react-notion
# 또는
npm install react-notion

GitHub - splitbee/react-notion: A fast React renderer for Notion pages

3. 코드 — 노션 페이지 렌더링

페이지 ID로 API를 호출해 받은 blockMap을 NotionRenderer에 넘기면, 노션 페이지가 그대로 렌더링됩니다.

import "react-notion/src/styles.css";
import "prismjs/themes/prism-tomorrow.css";  // 코드블록 하이라이트
import { NotionRenderer } from "react-notion";
import React, { useState, useEffect } from "react";

function App() {
  const [response, setResponse] = useState({});

  useEffect(() => {
    const NOTION_PAGE_ID = "연동할 notion 페이지 ID";
    fetch(`https://notion-api.splitbee.io/v1/page/${NOTION_PAGE_ID}`)
      .then(res => res.json())
      .then(resJson => setResponse(resJson));
  }, []);

  return (

 

  );
}

export default App;

이제 노션에서 글을 수정하면 페이지 새로고침 시 바로 반영됩니다. 노션이 사실상 헤드리스 CMS가 되는 셈입니다.

유의점

• 비공식 API 의존 — splitbee API는 노션의 비공식 엔드포인트를 사용합니다. 노션이 내부 구조를 바꾸면 동작이 깨질 수 있으니, 미션 크리티컬한 서비스에는 공식 Notion API + 자체 캐싱을 권장합니다.
• 실시간성의 한계 — "실시간"이라 해도 fetch 시점에 가져오는 것이라, 캐싱을 두면 지연이 생깁니다. 반대로 매 요청마다 호출하면 느리므로 ISR(Next.js) 등으로 균형을 잡는 것이 좋습니다.
• 스타일 — react-notion/src/styles.css를 꼭 임포트해야 노션과 유사한 모양이 나옵니다. 최신 대안으로는 react-notion-x가 더 많은 블록 타입을 지원합니다.

react-notion으로 노션 페이지를 서비스에 임베드하기