Next.js App Router에서 MDX 파싱 라이브러리를 어떻게 골랐나

블로그를 만들면서 MDX 파싱 라이브러리를 고를 때 잠깐 막혔다. 검색하면 둘 다 나오고, 둘 다 쓸 수 있다고 나온다. 그래서 어떤 기준으로 골라야 하는지 정리해봤다.

후보는 두 가지

• @next/mdx — Next.js 공식 패키지. MDX 파일을 페이지 컴포넌트처럼 직접 쓸 수 있다.
• next-mdx-remote — Hashicorp가 관리하는 커뮤니티 패키지. compileMDX API로 MDX 문자열을 컴파일해서 frontmatter와 컨텐츠를 동시에 돌려준다.

결정을 가른 세 가지 질문

1. 글 목록을 어떻게 만들 거야?

src/content/writing/ 폴더를 fs.readdirSync로 순회해서 모든 .mdx 파일을 읽는 방식으로 가기로 했다. 파일만 추가하면 자동으로 글이 발행되는 구조를 원했기 때문이다.

이 결정이 라이브러리 선택에 직결됐다. @next/mdx는 MDX 파일을 import해서 쓰는 패턴에 최적화되어 있다. 파일 시스템을 순회하면서 동적으로 불러오는 구조와는 잘 맞지 않는다. 반면 next-mdx-remote의 compileMDX(source)는 파일을 읽어서 문자열로 넘기면 되니까 이 흐름과 자연스럽게 맞는다.

2. frontmatter를 어떻게 파싱할 거야?

title, date, tags, draft, description, thumbnail 여섯 개 필드를 쓰기로 했다. 글 목록에 요약과 날짜가 필요했고, 초안 구분도 필요했다.

@next/mdx로 frontmatter를 파싱하려면 gray-matter 같은 별도 패키지가 필요하다. next-mdx-remote는 parseFrontmatter: true 옵션 하나로 해결된다. 패키지 하나 덜 쓰는 게 작은 것 같지만, 파이프라인이 단순해지는 효과가 있다.

const { content, frontmatter } = await compileMDX<PostFrontmatter>({
  source,
  options: { parseFrontmatter: true },
})

3. 신택스 하이라이팅은 어떻게 붙일 거야?

rehype-pretty-code를 쓰기로 했다. Shiki 엔진을 rehype 플러그인으로 감싼 것으로, VS Code 수준의 하이라이팅 품질에 라인 강조, 파일명 표시 같은 블로그 친화 기능이 붙어 있다.

next-mdx-remote의 compileMDX는 mdxOptions.rehypePlugins에 플러그인을 바로 넣을 수 있어서 연결이 깔끔하다.

import rehypePrettyCode from 'rehype-pretty-code'
 
const { content } = await compileMDX({
  source,
  options: {
    mdxOptions: {
      rehypePlugins: [[rehypePrettyCode, { theme: 'github-dark' }]],
    },
  },
})

결론

세 질문에 대한 답이 모두 next-mdx-remote 쪽을 가리켰다.

정리하면, 글 콘텐츠가 어디에 있고 어떻게 불러오느냐가 핵심 기준이다.

• MDX 파일이 app/ 디렉토리 안에 있고, 파일 자체가 페이지가 되는 구조라면 → @next/mdx
• 별도 content/ 폴더를 두고 파일 시스템을 읽어서 동적으로 처리하는 구조라면 → next-mdx-remote

어느 쪽이 낫다기보다, 자신의 콘텐츠 관리 구조에 맞는 걸 고르면 된다.