Astro로 포트폴리오 사이트 만들기

왜 Astro인가

포트폴리오 사이트에 React가 필요할까? 대부분의 포트폴리오는 정적 콘텐츠다. 인터랙션이라고 해봐야 네비게이션, 스크롤 애니메이션, 다크모드 토글 정도다.

React로 만들면:

• 번들 사이즈 100KB+ (React + ReactDOM만)
• 하이드레이션 비용
• SEO를 위해 SSR/SSG 설정 필요

Astro로 만들면:

• JavaScript 0KB (필요한 곳에만 선택적으로 추가)
• 빌드 시 HTML로 렌더링
• SEO 기본 내장

Karnel Labs 사이트는 Astro로 만들었다. 빌드 결과물은 순수 HTML + CSS다.

프로젝트 구조

karnel-website/
├── src/
│   ├── pages/          # 라우팅 (파일 기반)
│   ├── layouts/        # 공통 레이아웃
│   ├── components/     # 재사용 컴포넌트
│   ├── content/        # MDX 콘텐츠 (포트폴리오, 블로그)
│   ├── i18n/           # 다국어 번역
│   └── styles/         # 글로벌 스타일
├── public/             # 정적 파일
└── astro.config.mjs

Astro의 파일 기반 라우팅은 Next.js와 비슷하다. src/pages/about.astro → /about/.

컴포넌트 작성

Astro 컴포넌트는 .astro 파일이다. frontmatter(---) 안에 서버 로직, 아래에 HTML 템플릿.

---
interface Props {
  title: string;
  description: string;
}

const { title, description } = Astro.props;
---

<div class="card">
  <h3>{title}</h3>
  <p>{description}</p>
</div>

<style>
  .card {
    border: 1px solid var(--color-border);
    border-radius: 12px;
    padding: 1.5rem;
  }
</style>

CSS가 컴포넌트에 스코프된다. 다른 컴포넌트에 영향을 주지 않는다.

Content Collections

포트폴리오 항목은 MDX 파일로 관리한다. Astro의 Content Collections가 타입 안전한 콘텐츠 관리를 제공한다.

// content.config.ts
const portfolioCollection = defineCollection({
  loader: glob({ pattern: '**/*.mdx', base: './src/content/portfolio' }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    category: z.enum(['game', 'web', 'app', 'tool']),
    tags: z.array(z.string()),
    year: z.number(),
  }),
});

Zod 스키마로 frontmatter를 검증하므로, 필수 필드가 빠지면 빌드가 실패한다. 런타임 에러 대신 빌드 타임 에러.

Tailwind CSS 4 통합

Astro + Tailwind 조합은 간단하다.

// astro.config.mjs
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  vite: {
    plugins: [tailwindcss()],
  },
});

/* global.css */
@import 'tailwindcss';

@theme {
  --color-bg-base: #0a0a0b;
  --color-accent-teal: #00D4AA;
}

Tailwind v4의 CSS 기반 설정으로 디자인 토큰을 정의한다. tailwind.config.js가 필요 없다.

성능 결과

Lighthouse 점수:

항목	점수
Performance	100
Accessibility	98
Best Practices	100
SEO	100

JavaScript가 거의 없으니 Performance 100은 자연스러운 결과다. 접근성도 시맨틱 HTML과 skip navigation으로 높은 점수를 받았다.

언제 Astro를 쓰면 안 되는가

• 대시보드: 인터랙션이 많으면 React/Vue가 낫다
• 실시간 앱: WebSocket, 상태 관리가 복잡하면 SPA가 적합
• 복잡한 폼: 멀티스텝 폼, 실시간 검증이 많은 경우

콘텐츠 중심 사이트(블로그, 포트폴리오, 문서, 마케팅 페이지)에서 Astro는 최적의 선택이다.

정리

포트폴리오 사이트에 프레임워크 오버헤드는 필요 없다. Astro는 “서버에서 HTML을 만들고, 클라이언트에 JavaScript를 보내지 않는다”는 단순한 원칙으로 빠르고 SEO 친화적인 사이트를 만들 수 있게 해준다.