Vite, @react-three/fiber, @react-three/drei

 

프로젝트 기본 요소 설치

 

React와 Three.js를 결합한 3D 웹 애플리케이션을 개발하기 위한 기본 요소

• 빌드 도구(Build Tool)
• React를 위한 3D 렌더링 라이브러리(React 기반 Three.js 렌더링)
• @react-three/fiber를 위한 보조 유틸리티 라이브러리(Three.js용 React 컴포넌트 모음)

 

빌드도구

Vite	빠른 개발 서버, HMR(Hot Module Replacement) 지원 ESM(ECMAScript Modules) 기반으로 효율적인 빌드 속도 제공 최신 브라우저 환경에 최적화
Create React App (CRA)	Facebook이 만든 공식 React 프로젝트 생성 도구 Webpack을 사용한 번들링 설정 없이 바로 사용 가능하지만, 속도가 Vite보다 느리고 설정이 무거움
Next.js	SSR(Server-Side Rendering) 및 SSG(Static Site Generation) 지원 파일 기반 라우팅 React 서버 컴포넌트, API Routes 기능 제공 SEO 최적화에 강점
Parcel	설정이 거의 필요 없음 빠른 개발 서버 및 HMR 지원 코드 분할 및 트리 쉐이킹 자동 적용
Webpack(직접 설정)	가장 유연한 빌드 도구 → 설정이 복잡함 Babel, PostCSS, TypeScript 등을 커스텀하게 설정 가능 트리 쉐이킹, 코드 스플리팅 등 최적화 기능 제공
esbuild	Go 언어로 작성되어 속도가 빠름 아직은 React 프로젝트에서 직접 빌드 도구로 사용되기보다는, Vite나 다른 툴의 내부 빌드 엔진으로 활용
Razzle	서버 사이드 렌더링(SSR)을 지원하는 React 빌드 도구 Next.js보다 설정이 자유로운 편 React뿐만 아니라 다른 프레임워크도 지원

 

• 빠른 개발 속도 & HMR → Vite
• SSR, SEO 최적화 → Next.js
• 간단한 프로젝트 → CRA, Parcel
• 완전한 커스텀 & 직접 설정 → Webpack

이전에는 공식 React 빌드도구라고 하기도하고, 간단한 프로젝트였기 때문에 CRA로 빌드했지만 이번에는 변경사항이 즉시 반영되는 Vite의 HMR속도를 체감해보면서도 초기설정이 필요하지않은 아주 모던한 빌드도구를 사용해보려고한다. (classic에서 trendy로 ㅎㅎ.. 다음번엔 WebPack으로 빌드해보고 싶다.)

 

 

React 기반 Three.js 렌더링 라이브러리

three-nebula	React 기반 입자 시스템(particle system) 렌더링 라이브러리 - 특수 효과용
@react-three/fiber	가장 널리 사용되는 Three.js 렌더링 라이브러리
react-three-game-engine	게임 개발을 위한 React 기반 Three.js 엔진

• 일반적인 3D렌더링 → @react-three/fiber
• 입자효과(Particle System) → three-nebula
• 게임 개발 → react-three-game-engine

 

 

Three.js 관련 보조 라이브러리

@react-three/drei	@react-three/fiber에서 자주 사용되는 기능을 미리 구현해 둔 라이브러리 → 직접 Three.js API를 호출할 필요 없이 간편하게 3D오브젝트 추가 가능
@react-three/postprocessing	후처리(Post Processing) 기능을 쉽게 적용할 수 있도록 도와줌 - 블러, 반사, 그림자, 컬러 효과 등 다양한 후처리 필터 제공
@react-three/xr	WebXR(WebAR/WebVR) 지원 @react-three/fiber에서 VR/AR 기기를 활용할 수 있음
@react-three/cannon	물리 엔진 - Cannon.js 기반 Cannon.js를 React 환경에서 쉽게 사용할 수 있도록 도와줌
@react-three/rapier	물리 엔진 - Rapier 기반 @react-three/cannnon 보다 빠른 Rust 기반 물리 엔진(Rapier) Three.js와 호환되며 성능이 뛰어나 대규모 물리 시뮬레이션 가능
react-three-gui	3D 오브젝트 조작 GUI Three.js씬 내에서 UI 컨트롤러 추가 가능 객체의 크기, 색상 등을 실시간으로 조절 가능
react-three-flex	3D UI 배치 React Native의 flexbox 레이아웃을 3D 씬에서도 사용 가능 @react-three/fiber와 결합하여 UI 요소 배치 가능
three/examples/jsm/loaders	모델 및 텍스처 로더 GLTF, OBJ, FBX, SVG 등 3D 모델 로딩 지원 - GLTFLoader, OBJLoader 등을 제공, 3D모델을 쉽게 불러옴

• 후처리 효과 → @react-three/postprocessing
• VR/AR 지원 → @react-three/xr
• 물리 엔진 → @react-three/cannon, @react-three/rapier
• GUI 컨트롤 → react-three-gui
• 3D UI 배치 → react-three-flex
• 3D 모델 로드 → three/examples/jsm/loaders

 

 

Vite 프로젝트 생성

 

Vite

빠른 개발 환경(빠른 시작 시간, 빌드 시간)을 제공하는 모던한 프론트엔드 빌드 도구

 

 

Vite 설치 및 프로젝트 생성

npm create vite@latest my-first-r3f-app -- --template react

• my-first-r3f-app → 원하는 프로젝트 이름으로 변경 가능
• --template react → React 템플릿을 사용하여 Vite 프로젝트 생성

 

프로젝트 폴더로 이동 후 실행

cd my-first-r3f-app  # 생성된 프로젝트 폴더로 이동
npm install          # 필요한 의존성 설치
npm run dev          # 개발 서버 실행

npm run dev 실행 후, 브라우저에서 http://localhost:5173에 접속하여 프로젝트가 정상적으로 실행되는지 확인

 

 

http://localhost:5173

 

*Vite에서 기본 제공되는 App코드

Vite의 기본 템플릿

 

 

React Three Fiber (R3F) & Drei 설치

 

React Three Fiber (R3F)

React에서 Three.js를 사용할 수 있도록 도와주는 라이브러리

 

Drei

R3F 개발을 편리하게 해주는 추가적인 유틸리티를 제공

 

 

R3F & Drei 설치

npm install three @react-three/fiber @react-three/drei

• three → Three.js 핵심 라이브러리
• @react-three/fiber → React에서 Three.js 쉽게 사용할 수 있도록 지원
• @react-three/drei → R3F에서 자주 사용하는 기능 모음 (카메라 컨트롤, 조명, 모델 로더 등 포함)

 

Drei 주요 기능

• 조명 & 카메라 설정
  기본적인 빛(light)과 카메라 설정 적용
• 3D 모델 로딩
  .glb, .glbf, .obj, .fbx등의 파일 형식을 쉽게 불러올 수 있는 로더(loader) 제공
• 드래그 & 줌 & 회전
  마우스 인터랙션을 간단하게 추가할 수 있는 유틸리티 제공
• 후처리 & 성능 최적화
  블룸 효과, 반사, 그림자 등 후처리 기능 포함

 

peer react@">=18 <19" from @react-three/fiber@8.17.14

 

@react-three/fiber가 react@19는 아직 지원하지 않아서 버전 충돌남

 

npm install react@18 react-dom@18

 

react@18 재설치

 

peerDependenciesMeta

 

 

*peerDependencies

 

특정 패키지가 필수로 요구하는 패키지이지만 직접 포함하지 않고, 프로젝트에서 따로 설치해야 하는 의존성

npm info @react-three/fiber peerDependencies
npm info @react-three/drei peerDependencies

npm info @react-three/fiber peerDependenciesMeta
npm info @react-three/drei peerDependenciesMeta

 

확인 후 optional: true로 표시된 패키지는 선택사항, 표시가 없으면 필수 설치

버전 맞춰서 설치하면 됨

 

 

 

프로젝트 실행

 

설치가 끝났다면, 다시 프로젝트를 실행하여 정상적으로 동작하는지 확인

npm run dev

브라우저에서 http://localhost:5173를 열어 프로젝트가 정상적으로 실행되는지 확인