[React] Notion API 연동해보기

https://about-home.net/

우리집은 안전할까? 우리집 정보 확인하기

이번에 친구와 사이드 프로젝트를 진행했던 어바웃홈입니다.

기본적인 기능 구현은 다되어 있고 공지사항을 어떻게 구현할지에 대한 고민이 있었습니다.

친구와 말한 기존안은 어드민 페이지를 만들어서 거기에 공지사항 CRUD 페이지를 만들고 클라이언트에서 DB에 저장되어 있는 공지사항을 호출하는 방식을 생각했는데....

 

친구도 이직을 하고 시간도 많이 없어 일단 노션 API를 통해 공지사항을 구현하기로 했습니다.

많은 레퍼런스들이 많지만 구현시 어려웠던 부분만 정리해보았습니다.

 

1. 사용 라이브러리 

"dependencies": {
    "@notionhq/client": "^2.2.5",
    "notion-client": "^6.16.0",
    "react-notion-x": "^6.16.0",
    "notion-to-md": "^3.1.0",
  },

@notionhq/client와 notion-client

어떤 분은 notionhq/client를 쓰고 다른 분은 notion-client 쓰는 사람도 있고 둘 다 같은거 같은데 찾아보니 아래와 같은 차이를 가지고 있습니다.

 

notionhq/client와 notion-client는 Notion API를 사용하기 위한 두 가지 서드파티 라이브러리입니다. 이 라이브러리들은 Notion API를 호출하고 데이터를 가져오거나 업데이트하는 등의 작업을 수행할 수 있습니다.

 

notionhq/client는 Notion의 공식 클라이언트 라이브러리로, Notion에서 직접 유지보수하고 지원합니다. 이 라이브러리는 Node.js 및 브라우저 환경에서 사용할 수 있으며, Notion API의 다양한 기능을 활용할 수 있는 많은 메서드와 도우미 함수를 제공합니다.

notionhq/client는 안정적이고 문서화가 잘 되어 있으며, 공식 지원을 받기 때문에 업데이트 및 버그 수정이 빠르게 이루어집니다.

 

반면에 notion-client는 notionhq/client와는 별개의 개발자에 의해 만들어진 라이브러리입니다. 이 라이브러리도 Notion API와 상호작용할 수 있지만, 공식적인 Notion 지원이 아니므로 업데이트나 버그 수정이 느리게 이루어질 수 있습니다.

또한, notionhq/client보다는 기능이 제한적일 수도 있습니다. 따라서, Notion API를 사용하여 개발을 진행할 때는 공식 지원을 받는 notionhq/client를 사용하는 것이 가장 좋습니다. 이는 안정성과 업데이트, 지원 측면에서 더 많은 혜택을 받을 수 있기 때문입니다.

 

저는 둘 다 써봤지만 공식문서가 잘되어 있는 notionhq/client를 사용했습니다.

 

react-notion-x

react-notion-x는 Notion의 블록 구조와 일치하는 컴포넌트 구조를 가지고 있어, Notion 페이지의 구조를 정확하게 재현할 수 있습니다. 또한, Notion의 스타일과 테마를 적용하여 일관된 뷰를 제공할 수 있습니다. 라이브러리는 다양한 커스터마이징 옵션과 플러그인을 제공하므로, Notion 페이지를 개발자의 필요에 맞게 조정하고 확장할 수 있습니다.

 

해당 라이브러리는 notionhq/client가 아닌 notion-client를 사용해야 해서 사용하지는 않았습니다.

아래 블로그는 react-notion-x를 통해서 구현 예시를 잘보여줘 참고바랍니다.

https://enfp-jake.tistory.com/214

[React][NextJS][Notion] React에 Notion페이지를 가져오는 방법

 

notion-to-md

notion-to-md는 Notion 페이지를 Markdown 형식으로 변환하는 도구나 라이브러리입니다. 이 라이브러리를 사용하면 Notion에서 작성한 콘텐츠를 Markdown 파일로 내보낼 수 있습니다.

 

 

2. notion api와 block 이해

이번 기능을 구현하면서 개인적으로 notion api를 이해하는 부분이 가장 어려웠습니다.

노션 데이터베이스라는 개념이 있고 해당 데이터베이스를 호출하고 response 값을 아래처럼 받아왔습니다.

저는 해당 하위 프로퍼티에 접근할 수 있을줄 알았는데 그렇지 못 했습니다.

더 찾아보니 공식notion api를 통해서는 제가 원하는 content에 접근할 수 있는 방법은 없더라구요.

notion block

노션(Notion)의 API를 사용할 때 "block"은 중요한 개념입니다. 노션은 다양한 유형의 콘텐츠를 블록(block) 단위로 구성합니다. 블록은 텍스트, 이미지, 목록, 코드 등 다양한 형태의 콘텐츠를 나타내며, 이러한 블록들이 모여서 페이지를 구성합니다.

노션의 블록 구조는 트리 형태로 되어 있습니다. 페이지는 최상위 블록이며, 이 아래에 다양한 블록 유형이 포함될 수 있습니다. 블록은 부모-자식 관계를 가지며, 자식 블록은 부모 블록에 속합니다. 이러한 구조를 통해 복잡한 콘텐츠 구성을 가능하게 합니다.

 

그래서 너는 구현 어떻게 했는데??

저는 저희 홈페이지 내에서 마크다운된 content를 보여주고 싶었습니다.

notionhq/client를 통해 page_id를 가져오고 그 아이디를 notion-to-md를 통해 마크다운하기를 하고 싶었으나 렌더링 문제, fetch 문제로 인해서 아래처럼 구현했습니다.

notionhq/client를 통해 title과 created_date, 해당 page_id를 가져올 수 있었습니다. 

그래서 공지사항 list를 구현하고 해당 상세 페이지는 page_id를 통해 해당 페이지로 이동할 수 있게 하였습니다.

그래서 해당 상세 페이지를 클릭하면 해당 페이지로 이동하게 하였습니다.

아무래도 노션 page로 이동하는 문제가 있다보니 해당 페이지 내에 "공지사항 돌아가기", "어바웃홈 돌아가기" url을 삽입해서 사용자 편의성을 높이려고 했습니다.

 

결론

노션을 통해 채용페이지나 많은 페이지를 만드는걸 볼 수 있었는데 이건 notion-client와 react-notion-x을 통해 구현했겠구나 라는 생각이 들었습니다. 저는 제가 만든 페이지 내에서 해당 페이지 내에서 notion api를 호출한 데이터로 이리저리 사용하다보니 렌더링 문제, 성능 문제 외에도 많은 문제가 있었지만 다음에 노션 api를 사용해 페이지를 만든다면 notion-client / react-notion-x 조합이나 notionhq/client / notion-to-md 조합을 이용해서 구현해볼 생각입니다.

 

해당 기능 구현에 화해 블로그의 도움을 많이 받았습니다.

https://blog.hwahae.co.kr/all/tech/10960

Notion API와 함께 정적 페이지로의 여정 – 화해 블로그 | 기술 블로그