sj_yoon.log

타입 정의는 열심히 했는데 왜 유지보수는 점점 불편해질까?

Thu, 07 Aug 2025 04:45:45 GMT

요즘 프론트엔드 개발에서 타입스크립트는 선택이 아닌 기본값이죠 . 새로운 요구사항을 구현할 때마다 자연스럽게 type이나 interface를 정의하고, API 응답에 맞춰 타입을 매핑합니다.

하지만 프로젝트가 커지고 일정에 쫓기기 시작하면, 어느 순간부터 이상한 징후들이 생기기 시작합니다.

분명 타입이 있는데도 타입 오류가 납니다.
똑같은 구조의 타입이 여기저기 흩어져 있습니다.
타입 하나 수정했을 뿐인데 여러 파일이 깨집니다.

사실 원인은 명확합니다 . 처음엔 단순하게 출발했던 타입 정의가, 모든 케이스를 한 타입으로 처리하려고 하면서 점점 무거워졌기 때문입니다.

이번 글에서는 코드 예제를 기반으로, 확장 가능한 타입 설계 방식을 소개하려고 합니다 타입을 "에러 안 나게"가 아니라, 명확하게 나누고 조합함으로써 유지보수성과 재사용성을 확보하는 방식을 정리했어요.

📌 게시판 구성

이해를 돕기 위해 게시판 구성을 위한 가상의 상황을 가정하며 설명하겠습니다. 처음에는 간단하게 게시글을 보여주는 것부터 시작했죠.

1주차: 기본 게시글 목록 구현

기본 게시글 API 스펙은 다음과 같았습니다:

{
  "id": 1,
  "title": "첫 번째 게시글",
  "body": "게시글 내용입니다.",
  "userId": 123
}

// types.ts
type Post = {
  id: number;
  title: string;
  body: string;
  userId: number;
};

요구사항에 맞춰 타입을 정의하고 게시글 목록 컴포넌트도 만들었습니다.

// PostList.tsx
export const PostList = ({ posts }: { posts: Post[] }) => {
  return (
    
      {posts.map((post) => (
        
          {post.title}
          {post.body}
        
      ))}
    
  );
};

✅ 1주차 결과: 깔끔하게 구현 완료! 타입 오류도 없고 코드도 간결합니다.

2주차: 기획자의 새로운 요구사항

"각 게시글마다 댓글 개수를 보여주면 좋겠어요. 사용자들이 어떤 글이 인기 있는지 알 수 있도록요."

요구사항 반영을 위해 게시글 목록 API에서 댓글 개수도 함께 내려주기로 했습니다

{
  "id": 1,
  "title": "첫 번째 게시글",
  "body": "게시글 내용입니다.",
  "userId": 123,
  "commentsCount": 5
}

간단히 기존 Post 타입에 필드를 추가했습니다

// ❌ 단순한 해결책
type Post = {
  id: number;
  title: string;
  body: string;
  userId: number;
  commentsCount: number; // ✅ 추가
};

그리고 컴포넌트도 수정했죠

// PostList.tsx
export const PostList = ({ posts }: { posts: Post[] }) => {
  return (
    
      {posts.map((post) => (
        
          {post.title}
          {post.body}
          댓글 {post.commentsCount}개 {/* ✅ 추가 */}
        
      ))}
    
  );
};

✅ 2주차 결과: 문제없이 구현 완료! 타입도 잘 맞고 기획 요구사항도 충족했습니다.

3주차: 상세 페이지 개발 시작

"이제 게시글을 클릭하면 상세 페이지로 이동하도록 해주세요. 상세 페이지에는 게시글 내용과 실제 댓글들이 보여야 해요."

상세 페이지용 API를 따로 추가하고 해당 API는 댓글 정보까지 포함해서 내려줍니다

{
  "id": 1,
  "title": "첫 번째 게시글",
  "body": "게시글 내용입니다.",
  "userId": 123,
  "commentsCount": 2,
  "comments": [
    {
      "id": 101,
      "userId": 456,
      "text": "좋은 글이네요!",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

❌ 문제가 되는 접근 방법

기본 API에서 댓글 정보만 추가됐으니 기존 Post 타입에 comments를 추가하려고 시도합니다

// ❌ 이렇게 하면...
type Post = {
  id: number;
  title: string;
  body: string;
  userId: number;
  commentsCount: number;
  comments: Comment[]; // 추가?
};

하지만 기존 Post type에 comments 추가 후 PostList로 돌아가보면

// PostList.tsx - 목록 페이지
export const PostList = ({ posts }: { posts: Post[] }) => {
  return (
    
      {posts.map((post) => (
        
          {post.title}
          {post.body}
          댓글 {post.commentsCount}개
          {/* ❌ comments 필드는 사용하지 않지만 타입상 필수 */}
        
      ))}
    
  );
};

PostList 페이지에서는 comments 데이터가 실제로 필요하지 않고 API에서도 내려주지 않는데, 타입상으로는 필수가 됩니다. 그렇다고 옵셔널(comments?)로 처리하면, 상세 페이지에서 undefined 체크를 계속 해야 하죠.

✅ 타입 확장성을 고려한 해결책

기본 타입과 확장 타입을 분리해서 처리합니다:

// types.ts - 기본 Post 타입정의
export type Post = {
  id: number;
  title: string;
  body: string;
  userId: number;
};

export type Comment = {
  id: number;
  userId: number;
  text: string;
  createdAt: string;
};

// 상세 페이지 전용 확장 타입
export type PostWithLikeCountAndComments = Post & {
  commentsCount: number;
  comments: Comment[];

};

// PostDetail.tsx - 상세 페이지 컴포넌트
export const PostDetail = ({ post }: { post: PostWithLikeCountAndComments }) => {
  return (
    
      {post.title}
      {post.body}
      
        댓글 ({post.commentsCount}개)
        {post.comments.map((comment) => ( // 타입 보장됨
          
            {comment.text}
            {comment.createdAt}
          
        ))}
      
    
  );
};

4주차: 새로운 요구사항의 등장

"메인 페이지에 인기 게시글 섹션을 만들어주세요. 여기서는 제목만 간단하게 보여주면 되고, 댓글 수는 필요 없어요. 대신 좋아요 수를 보여주면 좋겠어요."

❌ 문제가 되는 접근 방법

여기서도 모든 케이스를 하나의 타입으로 처리하려고 시도하려고 한다면?

// ❌ 모든 케이스를 하나로 처리하려는 시도
type Post = {
  id: number;
  title: string;
  body: string;
  userId: number;
  commentsCount?: number;  // 어떨 때는 있고 어떨 때는 없고...
  comments?: Comment[];    // 상세 페이지에서만 필요
  likesCount?: number;     // 인기 게시글에서만 필요
};

모든 필드가 옵셔널이 되어버리고, 컴포넌트에서는 언제나 undefined 체크를 해야 합니다. 타입을 정의하면서 갖는 장점들이 퇴색되버리죠.

✅ 타입 확장성을 고려한 해결책

각 용도별로 명확한 네이밍과 함께 타입을 정의합니다:

// types.ts - 각 용도별 확장 타입 정의
export type PostList = Post & {
  commentsCount: number;
};

export type PostWithLikeCount = Post & {
  likesCount: number;
};

export type PostWithLikeCountAndComments = Post & {
  commentsCount: number;
  comments: Comment[];
};

// PostList.tsx
export const PostList = ({ posts }: { posts: PostList[] }) => {
  return (
    
      {posts.map((post) => (
        
          {post.title}
          {post.body}
          댓글 {post.commentsCount}개 {
        
      ))}
    
  );
};

// PopularPosts.tsx
export const PopularPosts = ({ posts }: { posts: PostWithLikeCount[] }) => {
  return (
    
      인기 게시글
      {posts.map((post) => (
        
          {post.title}
          ❤️ {post.likesCount} 
        
      ))}
    
  );
};

📈 결과: 타입 안전성과 유지보수성 확보

Before (문제 상황)

// ❌ 모든 필드가 옵셔널인 거대한 타입
type Post = {
  id: number;
  title: string;
  body: string;
  userId: number;
  commentsCount?: number;  // 언제 있는지 불분명
  comments?: Comment[];    // 언제 있는지 불분명
  likesCount?: number;     // 언제 있는지 불분명
};

// ❌ 매번 방어 코드 필요
댓글 {post.commentsCount || 0}개

After (해결책 적용)

// ✅ 목적이 명확한 타입들
export type PostList = Post & { commentsCount: number };
export type PostWithLikeCount = Post & { likesCount: number };
export type PostWithLikeCountAndComments = Post & { commentsCount: number; comments: Comment[] };

// ✅ 타입 안전성 보장
댓글 {post.commentsCount}개 // 항상 존재함이 보장됨

장점 정리

타입 안전성: 각 컴포넌트에서 필요한 필드가 항상 존재함을 타입 레벨에서 보장
명확한 의도: PostWithLikeCount, PostWithLikeCountAndComments 등 이름만 봐도 어디서 사용하는지 알 수 있음
유지보수성: 새로운 요구사항이 생겨도 기존 타입을 건드리지 않고 새로운 조합 타입만 추가
재사용성: 기본 Post 타입을 베이스로 다양한 상황에 맞는 확장 타입 생성 가능
런타임 안전성: undefined 체크나 방어 코드가 불필요

📘 마무리: 타입도 분리와 조합이 필요하다

어찌 보면 당연한 말이죠, 하지만 타입스크립트 사용에 익숙지 않거나 일정에 쫓겨 급박히 개발하다 보면 쉽게 범할 수 있는 실수입니다. 저 역시 “일단 타입부터 맞춰 놓고 나중에 정리하자”는 마음으로, 다양한 케이스를 하나의 거대한 타입에 우겨넣었던 경험이 많습니다.

그렇게 쌓인 타입은 어느새 비대해지고, 변경이 생길 때마다 여기저기서 방어 코드를 쓰게 되며, 결국 타입스크립트의 가장 큰 장점인 ‘컴파일 타임의 안정성’을 스스로 무력화시키는 결과를 만들게 되죠.

필요한 데이터만 정확히 받도록 하고, 그 상황에 맞는 타입을 조합해 나가는 것. 처음엔 조금 번거로워 보여도, 결국엔 유지보수가 편하고, 일일이 타입 정의 파일을 확인하는 시간도 줄어들 겁니다.

Vike 한입 해보실래요?

Sun, 22 Jun 2025 11:31:32 GMT

요즘 사이드 프로젝트로 블로그를 구성하려고 고민중에 있던 중 발견한 새 기술 스택이 있는데요. 바로 Vike라는 프레임워크입니다. 아직 국내외 커뮤니티를 비롯하여 아직까지 생소한 프레임워크지만, 개발의 유연성과 효율성을 확 끌어올릴 수 있는 흥미로운 요소들을 담고 있다고 생각해서 소개글과 간단한 사용법을 작성해보고자 합니다.

Vike란?

Vike는 UI 프레임워크, 렌더링 전략,서버 환경을 개발자가 원하는 대로 선택할 수 있도록 만들어진, 작지만 확장성 뛰어난 코어 프레임워크예요.

유연하고 안정적인 아키텍처 (Flexible by Design)

Vite 기반의 강력한 개발 경험: Vite를 기반으로 하기 때문에 HMR(Hot Module Replacement)의 빠른 개발 피드백 사이클을 그대로 활용할 수 있다.
기술 스택의 자유로운 조합: UI 프레임워크(React, Vue, Solid...), 데이터 패칭(REST, GraphQL, RPC...), 렌더링 전략(SPA, SSR, SSG...) 등 특정 기술에 종속되지 않고 프로젝트 요구사항에 맞게 스택을 유연하게 조정할 수 있다.
점진적 도입 가능: 별도의 레포지토리 분리나 추가적인 인프라 구축 없이 기존 프로젝트에 빠르게 도입할 수 있다.

이러한 Vike의 철학은 GET Started 페이지에서도 엿볼 수 있습니다. 다양한 기술 스택에 맞게 입맛대로 프로젝트 생성이 가능하죠.

생태계 강자와의 비교: Next.js와 Vike,

학습 곡선과 개발자 경험

SSG와 SSR을 지원하는 프레임워크 시장에서의 선두주자는 단연 Next.js입니다. 특히 React Server Components(RSC) 모델이 도입된 이후 컴포넌트를 서버와 클라이언트에서 매우 세밀하게 분리할 수 있다는 명확한 장점을 제공하죠. 모든 컴포넌트가 기본적으로 서버에서 실행되어 JavaScript 번들에서 제외되므로, 하이드레이션 과정을 최소화하고 클라이언트로 전송되는 JS 양을 줄일 수 있어요.

하지만 이러한 세밀한 제어는 동시에 개발자에게 새로운 고민과 신경 써야 할 지점들을 안겨주기도 합니다. 예를 들어, 단순히 useState 훅 하나를 사용하기 위해 컴포넌트 상단에 'use client'를 명시해야 하고, 이로 인해 해당 컴포넌트 전체가 하이드레이션 대상에 포함될 수 있어요. 또한, dynamic import를 위해 컴포넌트를 별도의 파일로 분리해야 하는 상황이 발생하면서 오히려 개발 복잡도가 증가하는 느낌을 받기도 합니다.

반면 Vike는 전통적인 SSR과 하이드레이션(Hydration) 모델을 기반으로 하여 기존 React 개발 경험을 그대로 활용할 수 있어요. useState, useEffect 같은 익숙한 훅들을 자연스럽게 사용하면서,+Page.tsx와 +data.ts 파일 구조만 이해하면 별다른 러닝커브 없이 빠르게 시작할 수 있습니다. 새로운 멘탈 모델을 학습하는 부담 없이 기존에 알고 있던 React 지식을 바탕으로 서버 사이드 렌더링의 이점을 누릴 수 있다는 점이 매력적입니다.

배포와 인프라 유연성

Next.js는 Vercel과의 깊은 통합으로 배포 경험이 매우 매끄럽긴 하지만, 동시에 Vercel의 인프라에 대한 종속성을 의미하기도 합니다. 물론 다른 플랫폼에도 배포할 수 있지만, 서버 액션이나 일부 고급 기능들은 Vercel에서 최적화되어 있어서 다른 환경에서는 추가 설정이나 우회가 필요한 경우가 빈번합니다. 최근에는 Next.js 15.1+에서 메타데이터 스트리밍 방식 변경으로 인해 Vercel 외 환경에서 SEO 문제가 발생하는 등 플랫폼 종속성이 더욱 심화되는 이슈도 존재하는 상황입니다.

Vike는 개발자의 입맛대로 초기 프로젝트를 구성할 수 있기 때문에 플랫폼 종속성이 훨씬 적다는 장점을 가집니다. 정적 사이트로 빌드하면 Netlify, GitHub Pages, Cloudflare Pages 어디든 배포할 수 있고, SSR이 필요하다면 Node.js가 실행되는 어떤 환경에서든 동작합니다.이런 유연성은 특히 여러 환경을 고려해야 하는 경우나 특별한 요구사항이 있는 프로젝트에서 중요한 고려사항이죠.

Vike 주요 기능

1. 라우팅 전략과 데이터 패칭

Vike는 Next.js와 동일하게 파일 시스템을 기반으로 라우팅을 사용합니다.

1단계: 디렉터리 구조 설계

예시로 상품 목록과 개별 상품 상세 페이지를 만든다고 가정하면, 다음과 같은 디렉터리 구조를 만들 수 있어요

src/pages/
└─ product/
  ├─ +data.ts        # 서버에서 데이터 페칭
  ├─ +Page.tsx       # /product 컴포넌트
  └─ @id/            # id 기반 개별 상품 페이지
    ├─ +data.ts      # 서버에서 데이터 페칭
    └─ +Page.tsx     # /product/:id 컴포넌트

2단계: 데이터 페칭과 컴포넌트 구현

Vike의 데이터 패칭은 서버 사이드 우선 원칙을 따릅니다. +data.ts 파일은 서버에서만 실행되어 페이지에 필요한 데이터를 미리 페칭해 pageContext.data로 반환하고, +Page.tsx 컴포넌트는 useData 훅을 통해 이미 준비된 데이터를 받아와 UI를 렌더링하는 구조예요.

// src/pages/product/+data.ts
// 서버 사이드에서 실행되는 데이터 페칭
import type { PageContextServer } from 'vike/types';

export interface Product {
  id: string;
  name: string;
  price: number;
  description: string;
}

export async function data(pageContext: PageContextServer): Promise {
  const response = await fetch(`/api/products`);
  const products: Product[] = await response.json();

  return products;
}

// src/pages/product/+Page.tsx
// 클라이언트에서 렌더링되는 페이지 컴포넌트
import React from 'react';
import { useData } from 'vike-react/useData';
import type { Product } from './+data';

export default function ProductPage() {
  const products = useData();

  return (
    
      상품 목록
      {products.map((product) => (
        
          {product.name}
          {product.price}원
          상세보기
        
      ))}
    
  );
}

이런 구조의 장점들을 살펴보면:

SSR이 가지는 이점들(보안, 성능, SEO 최적화)을 가집니다.
각 페이지마다 +data.ts와 +Page.tsx가 쌍을 이루어 관심사 분리가 명확히 이루어져요.
데이터 페칭 로직과 UI 로직이 물리적으로 분리되어 있어 유지보수성이 향상됩니다.
컴포넌트에서는 데이터 페칭 로직 없이 순수하게 렌더링에만 집중할 수 있으며 useData() 훅으로 데이터 접근이 매우 간단하고 직관적입니다.

동적 라우팅 구현

개별 상품 페이지는 @id 폴더를 사용해 동적 라우팅을 구현합니다:

// src/pages/product/@id/+data.ts
// 개별 상품 페이지 데이터 페칭

import type { PageContextServer } from 'vike/types';

export interface Product {
  id: string;
  name: string;
  price: number;
  description: string;
}

export async function data(pageContext: PageContextServer): Promise {
  const productId = pageContext.routeParams.id;

  const response = await fetch(`/api/products/${productId}`);
  const product: Product = await response.json();

  return product;
}

// src/pages/product/@id/+Page.tsx
// 개별 상품 상세 페이지
import React from 'react';
import { useData } from 'vike-react/useData';
import type { Product } from './+data';

export default function ProductDetailPage() {
  const product = useData();

  return (
    
      {product.name}
      {product.price}원
      {product.description}
      
    
  );
}

@id 폴더를 통한 동적 라우팅으로 RESTful한 URL 구조를 구현합니다.
Vike에서 제공하는 pageContext로 URL 파라미터에 간편하게 접근할 수 있어요.

2. 정적 렌더링 (SSG: Static Site Generation)

SSG(Static Site Generation)는 빌드 시점에 모든 페이지를 미리 정적 HTML 파일로 생성해두는 렌더링 전략입니다. Vike 역시 이 기능을 지원하며, 한 번 생성되면 변경 및 수정이 잦지 않은 블로그나 리포트 포스팅에 특히 유용하죠. 블로그 포스팅 예제를 통해 Vike의 SSG 전략을 알아보겠습니다.

1단계: SSG 설정 및 디렉터리 구조 설계

글로벌 설정 (vite.config.ts): 프로젝트의 모든 페이지를 기본적으로 SSG로 설정하고 싶다면 Root vite.config.ts 파일의 vike 플러그인 옵션에 prerender: true를 추가해 주세요.

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import vike from 'vike/plugin';

export default defineConfig({
  plugins: [
    react(),
    vike({
      prerender: true, // 모든 페이지를 기본적으로 SSG로 설정
    }),
  ],
});

페이지별 설정 (pages/+config.js 또는 해당 폴더의 +config.js): 특정 페이지 경로만 SSG로 만들고 싶을 경우 해당 페이지 폴더 root 경로에 config.js 파일을 생성하여 prerender: true로 설정해줍니다.

// config.js
export default {
  prerender: true,
};

블로그 SSG를 위한 디렉터리 구조는 다음과 같습니다:

src/pages/
└─ blog/
  ├─ +config.js                     # 이 경로와 하위 경로를 SSG로 설정
  ├─ +Page.tsx                      # 블로그 목록 페이지 (필요하다면)
  ├─ +data.ts                        # 데이터 페칭
  └─ @id/
    ├─ +data.ts                     # 개별 블로그 포스트 데이터 페칭
    └─ +Page.tsx                    # 개별 블로그 포스트 컴포넌트
    └── +onBeforePrerenderStart.ts   # SSG 핵심 요소

2단계: 동적 라우트 처리와 onBeforePrerenderStart 훅 구현

이미 생성된 각 개별 블로그 포스팅의 동적 라우트는 URL에 변수가 포함돼요. /blog/1, /blog/2, /blog/3처럼 말이죠. 이런 경우 Vike는 어떤 ID 값들로 페이지를 만들어야 할지 알 수 없기 때문에 onBeforePrerenderStart 훅을 통해 미리 알려줘야 합니다.

onBeforePrerenderStart 훅의 역할

onBeforePrerenderStart 훅은 동적 라우트에서 SSG를 구현하는 핵심 요소예요. 이 훅은 빌드 시점에 실행되어 생성할 페이지들의 목록을 Vike에게 알려주는 역할을 합니다. Next.js에서 제공하는 getStaticPaths와 유사하게 동작하죠.

// pages/blog/@id/+onBeforePrerenderStart.ts
import type { OnBeforePrerenderStartAsync } from 'vike/types';
import {
  fetchAllBlogPosts,
  fetchBlogPostById,
} from '../../../features/blog/blog.api';
import type { BlogPost } from '../../../features/blog/blog.type';

export type Data = {
  post: BlogPost;
};

export const onBeforePrerenderStart: OnBeforePrerenderStartAsync<
  Data
> = async () => {
  const posts = await fetchAllBlogPosts();

  // 각 포스트에 대해 상세 데이터를 가져와 URL과 pageContext 생성
  const blogPages = await Promise.all(
    posts.map(async (post) => {
      const detailPost = await fetchBlogPostById(post.id);

      return {
        url: `/blog/${post.id}`, // 생성할 정적 URL
        pageContext: {
          data: {
            post: detailPost, // 페칭된 데이터
          },
        },
      };
    })
  );

  return blogPages;
};

이 훅을 통해 각 포스트마다 생성할 URL과 해당 페이지에서 사용할 데이터를 Vike에게 전달합니다.

이제 전체적인 블로그 SSG 구현을 살펴볼게요.

// pages/blog/index/+data.ts
import type { PageContextServer } from 'vike/types';
import { fetchAllBlogPosts } from '../../../features/blog/blog.api';
import type { BlogPost } from '../../../features/blog/blog.type';

export type Data = {
  posts: BlogPost[];
};

export default async function data(
  _pageContext: PageContextServer
): Promise {
  const posts = await fetchAllBlogPosts();
  return { posts };
}

// pages/blog/index/+Page.tsx
import { useData } from 'vike-react/useData';
import type { Data } from './+data';
import { BlogList } from '../../../features/blog/components/BlogList';

export default function Page() {
  const { posts } = useData();

  return ;
}

// pages/blog/@id/+data.ts
import type { PageContextServer } from 'vike/types';
import { fetchBlogPostById } from '../../../features/blog/blog.api';
import type { BlogPost } from '../../../features/blog/blog.type';

export type Data = {
  post: BlogPost;
};

export default async function data(
  pageContext: PageContextServer
): Promise {
  const { id } = pageContext.routeParams;
  const postId = parseInt(id, 10);
  const post = await fetchBlogPostById(postId);
  return { post };
}

// pages/blog/@id/+Page.tsx
import { useData } from 'vike-react/useData';
import type { Data } from './+data';

export default function Page() {
  const { post } = useData();

  return (
    
      
        
          {post.title}
        
      

      
        
          
            {post.body}
          
        
      
    
  );
}

빌드 과정과 결과물

이제 build 명령어를 실행하면 다음과 같은 과정이 진행됩니다:

정적 라우트 처리: /blog 페이지는 +data.ts를 실행하여 모든 포스트 목록을 가져와 정적 HTML을 생성합니다.
동적 라우트 처리: +onBeforePrerenderStart.ts가 실행되어 각 포스트 ID별로 상세 페이지를 생성하죠.

빌드 결과물은 다음과 같은 구조로 생성돼요:

static/
├── blog/
│   ├── index.html              # 블로그 리스트 페이지
│   ├── 1/index.html            # 포스트 #1 상세 페이지
│   ├── 2/index.html            # 포스트 #2 상세 페이지
│   ├── 3/index.html            # 포스트 #3 상세 페이지
│   └── ... (이외 포스트)        # ...

주의사항과 팁

데이터 업데이트: 콘텐츠가 변경되면 다시 빌드해야 정적 파일에 반영됩니다.
빌드 시간: 포스트가 많을수록 빌드 시간이 길어질 수 있어요.
API 호출 최적화: onBeforePrerenderStart에서 불필요한 API 호출을 줄이도록 주의해야 합니다.

3. Vike에서 Hydration을 진행하는 방법

하이드레이션(Hydration)은 서버에서 이미 렌더링된 HTML에 클라이언트 측 JavaScript 코드를 주입하여 사용자와 상호작용할 수 있는 웹 애플리케이션으로 만드는 과정이에요. Vike의 하이드레이션 과정은 크게 두 개의 핵심 훅, onRenderHtml과 onRenderClient 를 통해 이루어집니다.

1단계: 서버에서 HTML 초벌 렌더링 (onRenderHtml 훅)

사용자가 Vike 앱에 처음 들어오면, Vike 서버는 onRenderHtml 훅을 실행하여 해당 페이지의 컴포넌트들을 HTML 문자열로 변환해요. 이 HTML이 브라우저로 전송되면 사용자는 초기 화면을 빠르게 볼 수 있죠.

먼저 서버 측에서 어떻게 HTML을 생성하는지 살펴보겠습니다:

// renderer/+onRenderHtml.tsx (React SSR 예시)

import React from 'react';
import ReactDOMServer from 'react-dom/server';
import { PageShell } from './PageShell'; // 전체 페이지 구조를 담는 컴포넌트
import { escapeInject, dangerouslySkipEscape } from 'vike/server';
import type { OnRenderHtmlHook } from 'vike/types';

const onRenderHtml: OnRenderHtmlHook = async (
  pageContext
): ReturnType => {
  const { Page, pageProps } = pageContext; // +Page.tsx 컴포넌트와 데이터

  // 1단계: React 컴포넌트를 HTML 문자열로 렌더링
  const pageHtml = ReactDOMServer.renderToString(
    
      
    
  );

  // 2단계: HTML 템플릿에 렌더링된 내용과 필요한 스크립트를 삽입
  const documentHtml = escapeInject`
    
      
        Vike App
        
        
      
      
        ${dangerouslySkipEscape(pageHtml)}
      
    `;

  return {
    documentHtml,
    pageContext: {
      // 클라이언트로 전달할 추가적인 pageContext 데이터 (선택 사항)
    },
  };
};
export default onRenderHtml;

위 코드에서 ReactDOMServer.renderToString을 통해 React 컴포넌트가 서버에서 HTML 문자열로 변환되고, escapeInject를 사용하여

내부에 삽입됩니다. 이 HTML에는 클라이언트 측 JavaScript 번들을 로드하는