본문으로 건너뛰기

Build Logs · EP 01

기술 블로그를 Nextra에서 Astro 5로 갈아엎은 기록 — 16,659줄을 지우며

Next.js 16 + Nextra로 돌리던 블로그를 Astro 5 정적 빌드로 전면 재구축했습니다. 153개 파일, 마이너스 1만 줄의 실제 수치와 함께 — 왜 옮겼고, 무엇이 깨졌고, 무엇이 좋아졌는지 정리합니다.

· 3분 읽기

기술 블로그를 Nextra에서 Astro 5로 갈아엎은 기록 — 16,659줄을 지우며

블로그를 갈아엎었다. Next.js 16 + Nextra에서 Astro 5로. 결과부터 숫자로:

153 files changed
+6,224 insertions
-16,659 deletions   → 네트 마이너스 10,435줄
빌드 산출물: 정적 HTML 256페이지 / 24MB

1만 줄을 지웠는데 기능은 그대로다. 이 글은 왜 옮겼는지, 무엇이 깨졌는지, 무엇이 좋아졌는지의 기록이다. 마이그레이션 글은 늘 남의 결정을 검증하는 재료가 되니, 내 것도 공개해둔다.

왜 Nextra를 버렸나

Nextra는 좋은 도구다. 문서 사이트라면 여전히 최선의 선택지 중 하나다. 문제는 내 블로그가 문서가 아니라 잡지라는 것이었다.

구체적인 불만 세 가지:

  1. 블로그에 필요 없는 것들의 무게. React 런타임, 클라이언트 라우팅, 폰트 파이프라인. 글 하나 읽는데 들어가는 자바스크립트가 아까웠다.
  2. 콘텐츠와 프레임워크의 결합. MDX가 Next.js 생태계 관례에 묶이면서, 콘텐츠(자산)가 프레임워크(도구)를 따라가는 구조가 됐다. 도구는 바뀔 것이다. 콘텐츠는 남아야 한다.
  3. 빌드 시간과 배포 단순성. 글 하나 고치면 전체 앱이 다시 빌드되는 구조보다, 정적 HTML이 툭 떨어지는 구조가 내 운영 리듬(작게 자주 배포)에 맞았다.

Astro 5를 고른 이유는 한 줐다: 콘텐츠 컬렉션이 1급 시민이고, 기본적으로 자바스크립트가 0인 정적 HTML을 뱉는다.

이관 설계 — 콘텐츠는 자산, 프레임워크는 소모품

이관의 원칙을 먼저 세웠다.

src/content/posts/*.mdx   ← 콘텐츠. 프론트매터 스키마로 계약화. 건드리지 않는다.
src/pages/**              ← 라우팅. 전부 새로 쓴다.
src/components/**         ← UI. 전부 새로 쓴다.

Astro의 Content Collections가 이 원칙을 코드로 강제한다. frontmatter를 zod 스키마로 검증하니, 옮기며 글 63편의 메타데이터가 전부 계약 아래로 들어왔다:

const posts = defineCollection({
  loader: glob({ pattern: '**/*.mdx', base: './src/content/posts' }),
  schema: z.object({
    title: z.string(),
    description: z.string().default(''),
    date: z.coerce.date(),
    tags: z.array(z.string()).default([]),
  }),
})

스키마 검증만으로 옮기는 동안 발견한 메타데이터 불일치들이 몇 개 있었다. 마이그레이션의 숨은 보상이다.

깨진 것들 — 이관 체크리스트

이관은 “되는 것”보다 “깨지는 것” 목록이 실무다. 실제로 다뤄야 했던 것들:

항목깨진 내용대응
검색자체 검색 없음astro-pagefind로 Full-text 검색 + ⌘K 팔레트
댓글Giscus 재설정pathname 매핑 유지해 기존 스레드 보존
OG 이미지정적 생성 로직 이식satori + sharp로 동적 생성 라우트 재구축
RSS/사이트맵재구성@astrojs/rss, sitemap 통합
코드 하이라이팅테마 재지정Shiki 듀얼 테마(라이트/다크) 설정
내부 링크경로 규칙 상이슬러그 체계 유지해 404 방지

여기서 중요한 정책 하나: URL은 절대 바꾸지 않았다. 글의 슬러그가 곧 자산이다. 검색 유입과 RSS 구독자를 지키는 건 마이그레이션의 최우선 제약였다.

좋아진 것

  1. 자바스크립트 예산. 본문 페이지의 클라이언트 JS는 팔레트·테마 토글 수준으로 줄었다. 뷰 트랜지션 같은 인터랙션은 브라우저 네이티브(View Transitions API)로 해결.
  2. 빌드의 예측 가능성. 256페이지 전부 정적 HTML. 배포는 파일 복사고, CDN 캐시는 영원하다.
  3. 디자인 시스템의 자유. 프레임워크 규약(React 컴포넌트 관례)에서 벗어나니 종이 위의 문집 같은 과감한 재설계가 가능했다. 글 목록은 CSS만으로 바꿀 수 있게 됐다.
  4. 의존성 다이어트. 런타임 의존성이 두 자릿수로 줄었다. 고칠 곳이 적다는 건 그 자체로 기능이다.

아쉬운 것과 남은 것

  • MDX 컴포넌트 주입 방식이 달라져, 글 안에 인터랙티브 데모를 심는 패턴은 다시 설계해야 한다.
  • Astro 생태계의 관례(슬롯, 아일랜드)를 팀에 설명하는 비용이 새로 생겼다.

하지만 트레이드옵을 후회하지 않는다. 이 블로그의 본질은 읽히는 글이고, 그 목적에 가장 가까운 도구로 옮긴 것뿐이다.

마이그레이션을 앞둔 사람에게

  • 콘텐츠와 프레임워크를 물리적으로 분리된 구조로 먼저 만들어라. 이관의 절반은 여기서 끝난다.
  • URL과 메타데이터 계약을 먼저 고정하고, 깨지는 것(검색/댓글/OG/RSS) 목록을 먼저 만들어라.
  • 마지막에 후회할 결정은 대부분 “옮기면서 개선하려다 생긴 것”이다. 이관은 이관만. 개선은 도착한 다음에.

1만 줄을 지우는 데 들어간 시간보다, 지운 뒤의 운영이 얼마나 단순해졌는가가 훨씬 크다. 블로그를 소유한다는 건 결국 이런 거다 — 도구가 아니라 구조를.

Related

· 10 min read

Next.js 기반 문서화 프레임워크 Nextra 완벽 가이드

Nextra는 Next.js를 기반으로 한 문서화 사이트 생성 프레임워크입니다. MDX로 콘텐츠를 작성하면 자동으로 아름답고 기능적인 문서 사이트를 생성합니다. 이 가이드에서 Nextra의 핵심 개념과 실전 활용법을 알아봅니다.

Next.jsAstro
→
· 2 min read

AI-assisted 프론트엔드 PR workflow 사례 정리

AI 코딩 에이전트를 프론트엔드 PR workflow에 붙일 때 필요한 입력 계약, 변경 범위 제한, 검증 명령, 리뷰 로그를 하나의 사례로 정리했습니다.

프론트엔드AI
→