Astro 5 → 6 마이그레이션, Tailwind, Cloudflare, astro-icon 문제 해결기
Astro 6으로 업그레이드 과정에서 Tailwind CSS, Cloudflare, astro-icon 등 다양한 의존성(Dependency) 문제 발생
Tailwind CSS v4로 업그레이드하고, Cloudflare 어댑터(Adapter) v13의 변경 사항에 맞춰 환경 변수(Environment Variables) 설정 변경
Content Layer API 변경으로 인해 src/content/config.ts 파일 구조 변경 및 코드 수정 필요
astro-icon과 Cloudflare v13의 호환성 문제로 인해 커스텀 SVG 컴포넌트(Custom SVG Component)로 대체
Astro 6으로의 마이그레이션은 핵심 기능 외에도 다양한 서드파티(3rd Party) 라이브러리 및 어댑터(Adapter) 업그레이드를 동반함
Tailwind CSS v4 업그레이드 및 설정
Astro 6으로 업그레이드 후, Tailwind CSS 관련 문제 발생 시 Tailwind CSS v4로 업그레이드하거나 기존 Tailwind 3을 유지하는 두 가지 선택지가 있다.
Tailwind 4: @tailwindcss/vite를 사용하며, `npx astro add tailwind` 명령어를 통해 설정
Tailwind 3: 기존 설정을 유지하고, `tailwindcss@3`을 추가 설치
저자는 Tailwind 4를 선택하고, CSS 기반 설정 방식으로 마이그레이션하여 `tailwind.config.mjs` 파일 제거
@theme 블록**을 사용하여 커스텀 테마를 정의하고, CSS 변수를 활용하여 스타일 관리.
Content Layer API 마이그레이션
Astro 6에서 Content Layer API가 변경됨에 따라, 기존 `src/content/config.ts` 파일을 `src/content.config.ts`로 이동하고, 로더(Loader)를 명시적으로 정의해야 한다.
파일 위치 변경: `src/content/config.ts` → `src/content.config.ts` (프로젝트 루트 내)
`z` import: `astro:content` → `astro/zod`로 변경
`type` 제거: `type: 'content'` 또는 `type: 'data'` 제거 후, `glob()` 또는 `file()` 로더 명시
데이터 컬렉션(Data Collection): `type: 'data'` 사용 시, `file()` 로더는 최상위 객체당 하나의 항목을 반환하며, 스키마(Schema)는 `z.object(...)` 사용
URL 생성 방식 변경**에 따른 코드 수정 필요.
Cloudflare 어댑터(Adapter) v13 마이그레이션
Cloudflare 어댑터 v13에서 `Astro.locals.runtime`이 제거됨에 따라, 환경 변수(Environment Variables) 접근 방식이 변경되었다.
변경 전: `const { env } = Astro.locals.runtime;`
변경 후: `import { env } from 'cloudflare:workers';`
`import { env } from 'cloudflare:workers'`**를 사용하여 환경 변수에 접근하도록 코드 수정
`wrangler.toml` 파일**의 `main` 항목을 `@astrojs/cloudflare/entrypoints/server`로 업데이트
`src/env.d.ts` 파일**에서 Cloudflare.Env 인터페이스를 확장하여, `wrangler types` 명령어로 생성되지 않는 시크릿(Secret) 타입 정의.
astro-icon 호환성 문제 해결
Cloudflare v13의 workerd 환경에서 astro-icon과 호환성 문제가 발생하여, 개발 서버(Dev Server) 실행 시 오류 발생.
문제 원인: astro-icon의 컴포넌트 렌더링 시 workerd 모듈 런너(Module Runner) 충돌
해결 방법: astro-icon을 제거하고, 커스텀 SVG 컴포넌트를 직접 구현하여 대체
커스텀 컴포넌트 구현: @iconify-json/mdi에서 SVG 경로를 가져와 30줄 이내의 코드로 구현
workerd 환경과의 호환성 문제**를 해결하고, 개발 환경의 안정성을 확보.
Astro 6 업그레이드 시 고려사항
Astro 6으로의 업그레이드는 코어(Core) 업데이트 외에도, 다양한 서드파티(3rd Party) 라이브러리 및 어댑터(Adapter)의 호환성 문제를 동반한다.
의존성(Dependency) 관리: 업그레이드 후, `npm ls` 명령어를 통해 peer dependency 경고 확인
Content Layer API 마이그레이션: Astro 5에서 유예 기간이 있었지만, Astro 6에서는 필수
Cloudflare 어댑터: v13에서 dev server 동작 방식 변경으로 인해, workerd 환경에서 발생하는 문제에 유의
AI 에이전트 활용: AI 에이전트는 유용하지만, 결과를 맹신하지 않고 직접 검증해야 함
업그레이드 전, 테스트 환경 구축 및 꼼꼼한 검증**을 통해 안정적인 마이그레이션 수행.
