몰입형 3D 포트폴리오 구축하기: Next.js 14 + React Three Fiber

배경

기술 쇼케이스를 겸하는 개인 포트폴리오 사이트입니다. 흔한 정적 포트폴리오 대신, React Three Fiber(R3F)로 몰입형 3D 경험을 만들었습니다 — 프론트엔드 개발뿐 아니라 3D 그래픽, 다국어 처리, DevOps 통합까지 하나의 프로젝트 안에서 보여줍니다.

라이브: creative.soominlab.com GitHub: Lajancia/Next14-R3F

기술적 하이라이트

1. React Three Fiber로 구성한 3D 씬

이 사이트는 여러 개의 인터랙티브 3D 씬을 포함합니다:

매크로 키보드 — 홈페이지 히어로 영역: 키캡까지 표현한 정교한 키보드 모델(.glb)을 커스텀 라이팅과 후처리 효과로 렌더링
바이크 — 오빗 컨트롤이 적용된 인터랙티브 3D 바이크 모델

각 씬은 독립적인 R3F 컴포넌트입니다:

// 예시: 3D 키보드 씬 컴포넌트 구조
import { Canvas } from "@react-three/fiber";
import { OrbitControls, Environment, useGLTF } from "@react-three/drei";

function KeyboardScene() {
  const { nodes, materials } = useGLTF("/keyboard.glb");
  return (
    <group>
      {Object.values(nodes).map((node, i) => (
        <mesh
          key={i}
          geometry={node.geometry}
          material={materials[node.name]}
        />
      ))}
    </group>
  );
}

2. i18next 기반 이중언어 지원

i18next로 한국어·영어 완전 다국어 처리를 구현했습니다:

라우트 기반 동적 언어 감지(/en/pipeline, /ko/pipeline)
accept-language 헤더를 통한 서버 사이드 언어 협상
페이지 컴포넌트별로 네임스페이스가 분리된 번역 파일

3. Panda CSS 스타일링

스타일링은 Panda CSS — 다음 특징을 가진 모던 CSS-in-JS 프레임워크 — 로 처리합니다:

타입 세이프한 디자인 토큰
빌드 타임에 생성되는 zero-runtime CSS
미디어 쿼리 보일러플레이트 없는 반응형 variant

CI/CD 파이프라인

이 프로젝트에는 완전한 DevOps 파이프라인이 포함되어 있습니다:

dockerfile — pnpm을 활용한 멀티 스테이지 빌드(deps → builder → runner)
docker-compose.yml — 로컬 배포 설정
Jenkinsfile — 자동 빌드, GHCR로 push, GitOps 저장소 업데이트
ecosystem.config.js — 프로덕션용 PM2 프로세스 관리

핵심 판단

왜 Tailwind 대신 Panda CSS를 썼나? Panda CSS는 빌드 타임에 타입 세이프한 아토믹 스타일을 생성해서, Tailwind의 개발 경험을 CSS-in-JS 라이브러리 수준의 타입 안전성과 함께 제공합니다. 애플리케이션 전체에서 공유할 수 있는 설정 가능한 디자인 토큰도 지원합니다.

왜 CI/CD 케이스 스터디를 따로 뒀나? Next14-R3F 프로젝트는 원래 3D 포트폴리오와 Jenkins/K3s 파이프라인을 모두 포함하고 있었습니다. 시각화와 인프라라는 서로 다른 엔지니어링 관심사를 다루기 때문에, 각각을 별도로 문서화했습니다.

결과

항목	세부 내용
3D 씬	GLTF 모델을 사용한 인터랙티브 WebGL 씬 2개
다국어	한국어 + 영어, 라우트 기반 감지
스타일링	타입이 있는 디자인 토큰을 갖춘 Panda CSS
CI/CD	Jenkins → GHCR → K3s (전용 케이스 스터디 참고)