Next.js 16 + Tailwind v4로 정적 블로그 만들기

이 블로그는 서버 없이 돌아가요. Next.js 16 App Router로 빌드한 뒤 정적 파일만 뽑아 Cloudflare Pages에 올렸어요. 무인으로 자동 발행할 계획이라, 서버를 운영하지 않고 파일을 푸시하면 끝나는 구조가 잘 맞았어요.

글은 파일로 둬요

글은 데이터베이스가 아니라 content/<카테고리>/<슬러그>.mdx 파일로 둬요. MDX라서 마크다운 안에 컴포넌트를 섞을 수 있고, 빌드할 때 정적 HTML로 변환돼요. 글의 메타데이터(제목·카테고리·날짜·요약·태그)는 frontmatter에 적고, 스키마로 검증해서 형식이 어긋나면 빌드가 멈추게 했어요.

정적 export에서 걸린 두 가지

output: 'export'를 쓰면 두 군데서 막히기 쉬워요. 첫째는 이미지예요. 정적 export에서는 Next.js의 이미지 최적화를 쓸 수 없어서, 설정에 images.unoptimized를 켜지 않으면 빌드가 실패해요.

둘째는 robots와 sitemap이에요. App Router에서 이 둘을 파일로 만들면 기본적으로 동적으로 취급되는데, 정적 export에서는 export const dynamic = 'force-static'을 붙여줘야 해요. 이게 없으면 타입 체크는 통과하는데 빌드에서만 실패해서, 처음엔 원인을 찾기 어려웠어요.

Tailwind v4

Tailwind는 v4를 썼어요. v4부터는 설정이 PostCSS 플러그인 중심으로 단순해졌고, 디자인 토큰을 CSS 변수로 다루기 편해요. 이 블로그는 색을 oklch 기반의 따뜻한 중립 톤으로 잡았는데, 토큰을 한곳에 정의해두고 컴포넌트는 그 변수만 쓰게 했어요. 그래야 글이 자동으로 쌓여도 톤이 흔들리지 않아요.

코드 블록은 빌드 시점에 하이라이트를 입혔어요. 런타임에 자바스크립트로 처리하지 않으니 정적 사이트에 잘 맞고, 페이지가 가벼워요.

정리하면, "서버 없이 / 글은 파일로 / 토큰은 한곳에"라는 세 가지가 1인 운영에 부담을 크게 줄여줬어요. 비슷한 블로그를 만든다면 정적 export의 두 함정만 미리 알고 가시면 한결 수월할 거예요.