Notion API로 만드는 나만의 기술 블로그

2025. 01. 30.

들어가며 - 왜 블로그를 만들게 되었나요?

개발자로서 학습 내용을 기록하고 공유하는 것은 매우 중요한 일입니다. 저는 그동안 Notion에 개발 학습 내용을 기록해왔는데, 이를 블로그 형태로 공유하고 싶다는 생각이 들었습니다. 그러나 velog나 tistory 등 블로그 플랫폼으로 마이그레이션하기에는 많은 시간이 필요했습니다. 노션의 이미지는 aws s3로 저장되는데, 이 데이터를 옮기는 작업이 번거로웠기 때문입니다. 그리고 가장 큰 이유로, 익숙한 Notion으로 계속 글을 작성하고 싶었습니다. 그래서 Notion API를 활용해 직접 블로그를 구축하기로 결정했습니다.

Notion API로 블로그 만들기

Next.js + Notion API

블로그 구축을 위해 Next.js를 선택했습니다. SSG(Static Site Generation)를 활용하면 빌드 타임에 Notion의 컨텐츠를 가져와서 정적 페이지를 생성할 수 있기 때문입니다.

export const notion = new Client({
  auth: process.env.NOTION_API_KEY,
});

export async function getPage(pageId: string) {
  const page = await notion.pages.retrieve({ page_id: pageId });
  const blocks = await notion.blocks.children.list({ block_id: pageId });

  return {
    page,
    blocks: blocks.results,
  };
}

Notion API를 사용하기 위해서는 인증키가 필요합니다. 인증키는 환경변수로 관리해주었습니다. 위 코드는 페이지 ID를 받아 해당 페이지의 정보와 하위 블록들을 가져오는 함수입니다.

Notion Block 렌더링 구현

가장 핵심적인 부분은 Notion의 각 블록을 React 컴포넌트로 변환하는 작업이었습니다. 제목, 단락, 코드 블록, 이미지 등 Notion의 다양한 블록 타입을 처리하기 위해 다음과 같은 컴포넌트를 구현했습니다.

export default function Block({ block }: { block: BlockObjectResponse }) {
  switch (block.type) {
    case 'paragraph':
      return <p>...</p>;
    case 'heading_1':
      return <h1>...</h1>;
    case 'code':
      return <Highlight theme={themes.github}>...</Highlight>;
    // ... 기타 블록 타입들
  }
}

Notion API는 각 블록의 타입에 따라 다른 데이터 구조를 반환합니다. 이를 적절한 React 컴포넌트로 변환하는 것이 핵심 작업이었습니다. 특히 코드 블록의 경우 prism-react-renderer를 사용하여 구문 강조 기능을 구현했습니다.

SSG를 활용한 빌드 타임 데이터 페칭

Next.js의 SSG를 활용해 빌드 타임에 모든 페이지를 생성하도록 구현했습니다.

export const dynamic = 'force-static';

export async function generateStaticParams() {
  const postsPages = await getAllPosts(PAGE_ROUTES.POSTS.id);
  const notesPages = await getAllPosts(PAGE_ROUTES.NOTES.id);

  return [...postsPages, ...notesPages].map((page) => ({
    slug: page.id,
  }));
}

이렇게 generateStaticParams를 설정해주고 force-static 으로 설정해주면, 해당 페이지들을 빌드타임에 페칭하여 준비합니다. 빌드 로그에는 아래와 같이 나오게 됩니다.

이 방법의 단점으로는 빌드에 시간이 더 많이 소요된다는 것과, 글을 작성하고 다시 한번 빌드를 돌려주어야 한다는 점이 있습니다. 그러나 빌드에 시간은 5분이면 충분하고, 이 마저도 Vercel에 레포를 연동하면 main에 push 시에 CI/CD가 되기 때문에 긴 시간은 아니었습니다. 또한 글을 작성하는 도중에는 보여주고 싶지 않았고, 글 작성 후 작성 완료를 누르듯이 재배포를 돌려주면 새로운 게시글이 업로드 된다는 점에서 오히려 좋았습니다.

이미지 최적화

Notion의 이미지 URL은 일정 시간이 지나면 만료되는 문제가 있었습니다. 이를 해결하기 위해 빌드 시점에 모든 이미지를 다운로드하고 최적화하는 방식을 구현했습니다. sharp 라이브러리를 사용하면 이미지를 webp로 변환하여 저장하면서 용량을 최적화할 수 있었습니다.

async function downloadImage(imageUrl: string, fileName: string) {
  const response = await axios.get(imageUrl, { responseType: 'arraybuffer' });
  await sharp(Buffer.from(response.data))
    .webp({ quality: 80 })
    .toFile(filePath);
}

해당 함수를 통해 빌드 타임에 모든 이미지를 다운로드하면서, WebP 포맷으로 최적화할 수 있었습니다. 이미지 사이즈는 5~10%로 줄어들었고, 빌드 타임 이후 이미지 URL이 만료되는 문제를 비용 없이 해결했습니다. 해당 스크립트를 빌드 전에 실행해주기 위해 pakage.json 도 수정해주었습니다.

"build": "npm run download-images && next build",

사실 모든 페이지의 이미지를 새로 불러오는 것은 아닙니다. 이는 Notion API가 한번에 불러올 수 있는 최대 블록이 100개이기 때문인데요, 제 블로그에는 100개 블록이 넘는 페이지들이 꽤 있었기 때문에 이러한 페이지 같은 경우 무한스크롤을 이용해서 다시 블록들을 불러오도록 했습니다.

  useEffect(() => {
    const observer = new IntersectionObserver(
      async (entries) => {
        if (entries[0].isIntersecting && hasMore && !isLoading) {
          setIsLoading(true);
          try {
            const data = await fetchBlocks(pageId, cursor || '');

            setBlocks((prev) => [...prev, ...data.blocks]);
            setCursor(data.next_cursor);
            setHasMore(data.has_more);
          } catch (error) {
            console.error(error);
          } finally {
            setIsLoading(false);
          }
        }
      },
      { threshold: 1.0 },
    );

    if (observerTarget.current) {
      observer.observe(observerTarget.current);
    }

    return () => observer.disconnect();
  }, [cursor, hasMore, isLoading, pageId]);

여기에서 react-query와 같은 라이브러리를 사용하지 않은 이유는, Notion API를 클라이언트에서 호출하면 CORS 문제가 발생했기 때문입니다. 따라서 저 fetchBlocks 함수를 next의 use server 를 활용해서 서버에서 페칭하도록 만들었습니다.

'use server';

import { getPage } from './notion';

export async function fetchBlocks(pageId: string, cursor?: string) {
  try {
    const response = await getPage(pageId, cursor);
    return response;
  } catch (error) {
    throw new Error('Failed to fetch blocks');
  }
}

마치며

이 프로젝트를 통해 Notion API를 활용한 블로그 시스템을 성공적으로 구축할 수 있었습니다. 특히 이미지 최적화와 SSG를 통한 성능 개선은 사용자 경험을 크게 향상시켰습니다.

앞으로도 지속적인 개선을 통해 더 나은 블로그 경험, 좋은 인사이트를 제공하도록 하겠습니다.