본문으로 건너뛰기
오토프로그 홈

Three.js

v1
작성 2026-08-22읽는 시간 11분

브라우저 안에 작은 3D 무대를 세우는 자바스크립트 라이브러리

Three.js 개념 인포그래픽 — 브라우저 안의 작은 연극 무대. 장면은 무대, 물체는 배우, 조명은 조명, 카메라는 관객의 눈, 렌더러는 화면에 그리는 화가

이건 뭐예요?​

웹 페이지는 원래 납작해요. 글자와 사진이 종이처럼 평평하게 놓여 있죠. 그런데 어떤 사이트는 제품이 빙글빙글 돌고, 책장에서 책이 앞으로 나와 펼쳐져요. 그 뒤에서 일하는 도구 중 가장 많이 쓰이는 게 Three.js(쓰리제이에스) 예요.

Three.js 는 웹 브라우저 안에 3D 를 그려 주는 자바스크립트 라이브러리(라이브러리: 남이 미리 짜 둔 코드 묶음. 가져다 쓰기만 하면 돼요)예요. GitHub(깃허브, 코드를 공개하고 나누는 사이트)의 mrdoob/three.js 저장소에 공개돼 있고, MIT 라이선스라 개인이든 회사든 무료로 써요. 2026년 8월 22일 기준 별(좋아요)이 114,675개, 최신 판은 r185(2026년 7월 1일)예요. 저장소 소개 문구가 딱 한 줄이에요. "JavaScript 3D Library."

저는 이걸 브라우저 안의 작은 연극 무대라고 이해했어요. 무대를 하나 세우려면 다음 것들이 필요하잖아요. Three.js 도 똑같아요.

연극 무대Three.js 용어하는 일
무대장면(Scene)배우와 조명이 놓이는 빈 공간이에요
배우물체(Mesh)무대 위에 놓이는 것. 모양(Geometry) 과 재질(Material, 옷·피부·색) 을 합쳐서 만들어요
조명조명(Light)배우를 비춰요. 조명이 없으면 대부분의 재질은 까맣게 보여요
관객의 눈카메라(Camera)어느 자리에서, 얼마나 넓게 무대를 보는지 정해요
화면에 그리는 사람렌더러(Renderer)카메라가 본 장면을 브라우저의 그림판(<canvas> 라는 HTML 조각)에 그려요

공식 매뉴얼의 첫 장("Fundamentals", 기초)도 같은 말을 해요. 화면에 뭔가 띄우려면 장면·카메라·렌더러 세 가지가 반드시 있어야 하고, 장면에 물체와 조명을 넣은 다음 렌더러가 카메라 시점으로 그려 준다고요.

그림을 그리는 방식은 두 가지예요. 기본은 WebGL(웹지엘, 브라우저가 그래픽카드를 빌려 그림을 그리게 하는 표준) 렌더러고, 더 새로운 WebGPU(웹지피유) 렌더러도 들어 있어요. 초심자는 기본(WebGL)만 알면 충분해요.

쉽게 말해, "무대 세우고, 배우 올리고, 조명 켜고, 관객 자리 정하면, 화가가 화면에 그려 준다." 이게 Three.js 의 전부예요. 나머지는 전부 이 다섯 가지의 응용이에요.

우리는 이렇게 쓰고 있어요​

저(디온웍스 대표)는 코드를 한 줄도 못 써요. 그런데 Three.js 로 만든 화면이 지금 두 개나 돌아가고 있어요. 하나는 저희 본채에, 하나는 수강생 작품이에요.

사례 1 — 본채의 3D 전자책 서가 (autofrog.kr/book)​

지금 보고 계신 이 사이트의 본채 autofrog.kr/book 이 바로 Three.js 무대예요. 2026년 8월 22일에 완성했어요.

autofrog.kr/book 의 3D 전자책 서가 — 책장에 실물 표지 3권이 꽂혀 있고, 클릭하면 책이 앞으로 나와 펼쳐진다

무료 전자책 3권(『팔리는 바이브 코딩』『Hermes 에이전트 설치 매뉴얼』『클로드 코드 설치하기』)을 3D 책장에 꽂아 뒀어요. 무대 용어로 풀면 이래요.

  • 배우 = 책 3권. 표지는 실제 표지 PNG 를 그대로 입혔어요. 책등과 뒤표지 색은 표지에서 뽑아서 맞췄고요.
  • 연기 = 클릭하면 앞으로 나와 펼쳐지기. 클릭·탭·← → 키·Enter·스와이프 전부 돼요. 펼친 책은 마우스 포인터를 따라 15도쯤 기울어요.
  • 속지 = 실제 내용. 제목 페이지·차례·첫 문단을 그림판에 그려서 책 속에 붙였어요. 지어낸 문장은 0 이에요. 면을 누르면 장이 넘어가요.
  • 무대 배경 = 사이트 색. 벽과 책장 색은 사이트의 CSS(화면을 꾸미는 언어) 색 변수를 읽어요. 다크·라이트를 바꾸면 무대 색도 바로 바뀌어요.

만든 방식은 단순해요. 제가 클로드 코드에 "서가를 3D 로, 표지는 실물, 속지는 실제 내용" 식으로 말하고, 클로드가 코드를 썼어요. 결과물은 three 0.165 기반으로, 화면 그리는 엔진 440줄 + 표지·속지 그리는 부분 230줄이에요. 리액트(React, 화면 조립 도구)와는 분리된 순수 클래스라 다른 사이트에도 옮겨 붙일 수 있어요.

솔직하게 두 가지를 더 말씀드릴게요.

  1. 참고한 게 있어요. 뒤에 나오는 ThreeUI 의 "Complete Shelf"(MIT, 무료 항목) 구성을 보고 저희 것으로 새로 짰어요. 가져온 코드는 없고, 그쪽에 있던 자리 채우기용 가짜 책 정보·배경음악(1.2MB)·책마다 바뀌는 벽색은 뺐어요. 전자책 서가엔 필요 없었거든요.
  2. 첫 렌더(화면에 그려 보기)에서 실패했어요. 카메라 거리를 손으로 넣었더니 데스크톱·모바일 둘 다 책이 잘렸어요. 그래서 "HTML(글·버튼 같은 평평한 화면 요소)이 덮지 않는 빈 영역에 책이 꽉 차게" 거리를 계산하도록 바꿨어요. 관객 자리를 눈대중으로 정하면 안 된다는 교훈이에요.

그리고 안전장치가 하나 있어요. Three.js 는 지연 로딩(필요할 때만 따로 내려받기, 약 120KB 압축 기준)이라 첫 화면 속도를 해치지 않아요. WebGL 이 안 되는 기기·검색엔진·로딩 중에는 원래 있던 2D 정적 서가가 그대로 보여요. 3D 가 실패해도 아무도 빈 화면을 보지 않아요.

사례 2 — 수강생 작품 월목(WallMock)​

이건 제가 짠 게 아니에요. 저희와 같이 공부하는 교육생 smyno73642 님이 디온웍스 현장(전시월 제작 고객에게 "완성되면 이렇게 보입니다"를 납품 전에 보여 주는 용도)에서 쓰려고 클로드 코드로 만든 작품이에요. 랩스 쇼케이스 3D Mockup Preview 에 자세한 제작기가 있고, 라이브는 wallmock.vercel.app 이에요.

월목(WallMock) 3D 미리보기 — 3,000×2,400mm 전시월 벽체에 업로드한 디자인을 입혀 회전·줌으로 확인

전시월·포토월·백월 같은 대형 벽체 인쇄물 시안을 올리면, 실제 벽 크기 비율(예: 3,000×2,400mm)로 2D 평면 목업과 Three.js 3D 미리보기를 만들어 줘요. 마우스로 돌리고 확대하고, 조명을 바꿀 수 있어요. 3D 화면 안에서 이미지를 드래그해 위치를 옮기는 것도 돼요. 이건 레이캐스팅(마우스 위치에서 보이지 않는 빛줄기를 쏴 3D 물체 어디에 닿았는지 찾는 기법)이라는 기법이에요. 스택은 Vanilla JS(순수 자바스크립트) + Three.js r160 + Vercel Serverless(서버를 직접 두지 않고 함수만 올려 돌리는 방식)예요.

쇼케이스 글에 이 작품을 설명하는 한 문장이 있어요.

Three.js를 직접 코딩한 게 아니라 Claude에게 "벽체를 3D로 보여줘"라고 말했을 뿐인데, 조명·그림자·카메라 회전까지 전부 만들어졌다

저희 서가도, 수강생의 월목도 같은 방식이에요. 무대 용어를 알고 말로 시키면, 코드는 클로드가 써요.

템플릿부터 고르면 빨라요 — ThreeUI​

빈 무대에서 시작하기 막막하면, 이미 꾸며진 무대를 보고 고르는 방법이 있어요. threeui.com 은 디자인코드(designcode.io, MengTo)가 만든 "에이전트용 Three.js 웹 디자인 템플릿" 모음이에요. 항목이 210개예요.

threeui.com 둘러보기 화면 — 템플릿 카드가 격자로 나열돼 있다

분류는 랜딩페이지·히어로·Three.js 장면·배경·버튼·텍스트 애니메이션·UI 요소·CSS·모션·섹션이에요. 예를 들면 살아 있는 숲(Sylva Living World), 책장(Complete Shelf), 베스트셀러 책 진열(Bestsellers Book Showcase), 액체 금속 버튼(Liquid Metal Button), 별자리 배경(Constellation Field) 같은 것들이요.

이 사이트의 핵심은 "Copyable as prompts" 예요. 항목마다 구현 프롬프트가 붙어 있어서, 그걸 클로드 코드에 붙여 넣으면 비슷한 장면을 만들어 줘요. 코드를 복사하는 게 아니라 말을 복사하는 거예요. 바이브 코더한테 딱 맞는 방식이죠.

무료(Community)와 유료(Pro)가 있어요. Pro 는 CLI(명령줄 도구)와 MCP(AI 비서에 외부 도구를 꽂아 주는 연결 규격)로 소스를 바로 받을 수 있어요. 이 둘은 Pro 전용이라 로그인이 필요해요. 저희 서가가 참고한 Complete Shelf 는 무료 항목이었어요. 처음엔 무료 항목의 프롬프트만으로도 충분해요.

한번 써볼까요?​

터미널을 열 필요가 없어요. 아래 프롬프트를 클로드 코드 대화창에 그대로 붙여 넣으면 돼요. 여러분이 직접 하실 일은 브라우저에서 마우스로 돌려 보고 "여기 마음에 안 들어"라고 말하는 것뿐이에요. 나머지는 클로드가 알아서 해 줘요.

1단계 — 무대 세우기

내 사이트 첫 화면에 Three.js 로 우리 제품 상자를 3D 로 띄워줘.
npm 으로 three 최신 판(r185)을 설치하고, 장면·카메라·렌더러를 만든 다음
상자 하나에 조명을 비춰서 천천히 돌게 해줘. 상자 색은 사이트 주색으로 맞추고,
브라우저 창 크기가 바뀌어도 찌그러지지 않게 해줘.

이 프롬프트를 넣으면 클로드가 npm(자바스크립트 부품을 내려받는 도구)으로 three 를 설치하고, 장면·카메라·렌더러·물체·조명 다섯 가지를 만들어 브라우저에 돌아가는 상자를 띄워 줘요.

2단계 — 관객이 움직이게 하기

마우스로 끌면 상자가 돌아가고, 휠로 확대·축소되게 해줘.
Three.js 공식 부속품(OrbitControls) 을 쓰고, 손을 떼면 천천히 원래 자리로 돌아오게.
모바일에선 손가락 드래그로 돌리고 두 손가락으로 확대되게 해줘.

이 프롬프트를 넣으면 클로드가 카메라를 마우스·손가락에 연결해서, 관객이 무대 주위를 직접 걸어 다니듯 볼 수 있게 해 줘요.

3단계 — 안전장치와 확인

WebGL 이 안 되는 기기·검색엔진·로딩 중에는 기존 2D 화면이 그대로 보이게 폴백을 넣어줘.
three 는 지연 로딩으로 따로 분리해서 첫 화면 속도를 지키고,
데스크톱(1280px)과 모바일(390px) 폭에서 3D 가 잘리지 않는지 스크린샷으로 찍어서 보여줘.

이 프롬프트를 넣으면 클로드가 3D 가 실패해도 빈 화면이 안 나오게 막아요(이 대비책을 폴백이라고 불러요). 그리고 두 화면 폭에서 찍은 스크린샷을 보여 줘요. 스크린샷을 눈으로 보는 것, 이건 꼭 직접 하세요. 저는 이 확인을 건너뛰었다가 첫 렌더에서 책이 잘렸어요.

공식 매뉴얼은 threejs.org/manual 에 있어요. 클로드가 막히면 "공식 매뉴얼의 Fundamentals 장 기준으로 해줘"라고 한 줄 덧붙이면 돼요.

클로드 코드 터미널에서는 이렇게​

원리가 궁금한 분을 위해, 위 1단계에서 클로드가 실제로 뭘 하는지 보여 드릴게요.

클로드 코드 대화창에서 ! 를 맨 앞에 붙이면 터미널 명령어를 바로 실행할 수 있어요.

# three 라이브러리를 내 프로젝트에 설치 (2026-08-22 기준 0.185.1 = r185)
! npm install three

설치가 끝나면 HTML 에 그림판 한 줄이 필요해요. <canvas id="c"></canvas> — 렌더러가 여기에 그려요.

그다음이 공식 매뉴얼 첫 장(Fundamentals)의 최소 예제예요. 무대 용어를 주석(코드 옆에 적는 설명 메모)으로 달아 뒀어요.

// three 라이브러리를 THREE 라는 이름으로 불러와요
import * as THREE from 'three';

// 그림판(canvas)을 찾아서, 거기에 그릴 화가(렌더러)를 만들어요
const canvas = document.querySelector('#c');
const renderer = new THREE.WebGLRenderer({ canvas });

// 관객의 눈(카메라). 75 = 시야각, 2 = 가로세로 비율, 0.1~5 = 보이는 거리 범위
const camera = new THREE.PerspectiveCamera(75, 2, 0.1, 5);
camera.position.z = 2; // 관객을 무대에서 2만큼 뒤로 물려요

// 빈 무대(장면)를 만들어요
const scene = new THREE.Scene();

// 배우 = 모양(가로1·세로1·깊이1 상자) + 재질(청록색)
const geometry = new THREE.BoxGeometry(1, 1, 1);
const material = new THREE.MeshBasicMaterial({ color: 0x44aa88 });
const cube = new THREE.Mesh(geometry, material);

// 배우를 무대에 올려요
scene.add(cube);

// 화가가 카메라 시점으로 무대를 그림판에 그려요
renderer.render(scene, camera);

여기까지 하면 청록색 정사각형이 하나 보여요. 상자인데 정면에서 봐서 네모로 보이는 거예요. 이 예제의 재질(MeshBasicMaterial)은 조명을 안 받는 종류라 조명 없이도 보여요. 조명을 받는 재질로 바꾸고 조명을 하나 추가하면 입체감이 살아나요. 그 이후부터는 클로드에게 말로 시키는 게 빨라요.

이런 분께 추천해요​

Three.js 는 "사진 한 장으로는 못 보여 주는 걸 브라우저에서 돌려 보여 주고 싶은 분" 을 위한 도구예요. 특히 이런 세 분께요.

  1. 회사 제품을 사진 대신 돌려 보여 주고 싶은 분 — 소형 가전·가구·포장 디자인처럼 "옆면과 뒷면도 봐야 아는" 제품을 파는 분이요. 사진 여섯 장 대신 상자 하나를 띄워 고객이 직접 돌려 보게 할 수 있어요. 1단계 프롬프트가 그 시작이에요.

  2. "완성되면 이렇게 보입니다"를 납품 전에 보여 줘야 하는 분 — 전시월·간판·인테리어 시공처럼 실물이 나오기 전에 고객 확인을 받아야 하는 분이요. 수강생이 만든 월목이 정확히 이 일을 해요. 시안을 올리면 실제 크기 벽에 입혀서 돌려 볼 수 있으니까요.

  3. 전자책·포트폴리오·강의 자료를 목록 대신 기억에 남는 첫 화면으로 만들고 싶은 분 — 1인 출판·교육을 하는 분이요. 저희 서가처럼 책을 꽂아 두고 클릭하면 펼쳐지게 하면, 똑같은 PDF 3권도 다르게 보여요. ThreeUI 의 책장 템플릿 프롬프트부터 붙여 넣어 보세요.

참고 링크​

▸개정 이력1건
  • v12026-08-22초판