기술 블로그를 Nextra에서 Astro 5로 갈아엎은 기록 — 16,659줄을 지우며
Next.js 16 + Nextra로 돌리던 블로그를 Astro 5 정적 빌드로 전면 재구축했습니다. 153개 파일, 마이너스 1만 줄의 실제 수치와 함께 — 왜 옮겼고, 무엇이 깨졌고, 무엇이 좋아졌는지 정리합니다.
기술 블로그를 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는 좋은 도구다. 문서 사이트라면 여전히 최선의 선택지 중 하나다. 문제는 내 블로그가 문서가 아니라 잡지라는 것이었다.
구체적인 불만 세 가지:
- 블로그에 필요 없는 것들의 무게. React 런타임, 클라이언트 라우팅, 폰트 파이프라인. 글 하나 읽는데 들어가는 자바스크립트가 아까웠다.
- 콘텐츠와 프레임워크의 결합. MDX가 Next.js 생태계 관례에 묶이면서, 콘텐츠(자산)가 프레임워크(도구)를 따라가는 구조가 됐다. 도구는 바뀔 것이다. 콘텐츠는 남아야 한다.
- 빌드 시간과 배포 단순성. 글 하나 고치면 전체 앱이 다시 빌드되는 구조보다, 정적 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 구독자를 지키는 건 마이그레이션의 최우선 제약였다.
좋아진 것
- 자바스크립트 예산. 본문 페이지의 클라이언트 JS는 팔레트·테마 토글 수준으로 줄었다. 뷰 트랜지션 같은 인터랙션은 브라우저 네이티브(View Transitions API)로 해결.
- 빌드의 예측 가능성. 256페이지 전부 정적 HTML. 배포는 파일 복사고, CDN 캐시는 영원하다.
- 디자인 시스템의 자유. 프레임워크 규약(React 컴포넌트 관례)에서 벗어나니 종이 위의 문집 같은 과감한 재설계가 가능했다. 글 목록은 CSS만으로 바꿀 수 있게 됐다.
- 의존성 다이어트. 런타임 의존성이 두 자릿수로 줄었다. 고칠 곳이 적다는 건 그 자체로 기능이다.
아쉬운 것과 남은 것
- MDX 컴포넌트 주입 방식이 달라져, 글 안에 인터랙티브 데모를 심는 패턴은 다시 설계해야 한다.
- Astro 생태계의 관례(슬롯, 아일랜드)를 팀에 설명하는 비용이 새로 생겼다.
하지만 트레이드옵을 후회하지 않는다. 이 블로그의 본질은 읽히는 글이고, 그 목적에 가장 가까운 도구로 옮긴 것뿐이다.
마이그레이션을 앞둔 사람에게
- 콘텐츠와 프레임워크를 물리적으로 분리된 구조로 먼저 만들어라. 이관의 절반은 여기서 끝난다.
- URL과 메타데이터 계약을 먼저 고정하고, 깨지는 것(검색/댓글/OG/RSS) 목록을 먼저 만들어라.
- 마지막에 후회할 결정은 대부분 “옮기면서 개선하려다 생긴 것”이다. 이관은 이관만. 개선은 도착한 다음에.
1만 줄을 지우는 데 들어간 시간보다, 지운 뒤의 운영이 얼마나 단순해졌는가가 훨씬 크다. 블로그를 소유한다는 건 결국 이런 거다 — 도구가 아니라 구조를.