🌟 React 19 + Vite + p5.js 프로젝트 셋업

들어가며

크리에이티브 코딩과 인터랙티브 아트를 다룰 때 p5.js는 여전히 가장 강력한 도구 중 하나입니다. React 생태계와 결합하면 컴포넌트 기반의 구조화된 프로젝트 안에서 비주얼 코딩을 자유롭게 활용할 수 있죠.

과거에는 react-p5 같은 서드파티 래퍼 라이브러리를 사용하는 경우가 많았지만, 2026년 현재 React의 훅(useRef, useEffect)만으로도 p5.js를 완벽하게 통합할 수 있습니다. 오히려 외부 래퍼에 의존하지 않는 편이 더 가볍고, 세밀한 제어가 가능하며, React의 라이프사이클을 정확히 이해하는 데에도 도움이 됩니다.

이 글에서는 React 19 + Vite 8 + p5.js v2 환경을 사용하여, 외부 래퍼 없이 React 훅만으로 p5.js 스케치를 연동하는 방법을 처음부터 끝까지 다룹니다.

---

1. 프로젝트 생성

Create React App(CRA)은 공식 지원이 중단되었으므로, 현재 React 생태계의 표준 빌드 도구인 Vite를 사용합니다.

npm create vite@latest my-p5-app

실행 후 나타나는 프롬프트에서 다음과 같이 선택합니다.

• Framework: React
• Variant: JavaScript

이후 프로젝트 폴더로 이동해 기본 의존성을 설치합니다.

cd my-p5-app
npm install

---

2. p5.js 의존성 설치

외부 래퍼는 사용하지 않고 p5.js 라이브러리만 직접 설치합니다.

npm install p5

💡 왜 래퍼를 쓰지 않을까?
@p5-wrapper/react 같은 라이브러리도 존재하지만, p5.js는 자체적으로 인스턴스 모드(Instance Mode) 를 제공합니다. React의 useRef로 캔버스가 마운트될 DOM을 잡고, useEffect로 인스턴스의 생성/정리를 관리하면 그것으로 충분합니다. 의존성을 하나라도 줄이는 것이 장기적인 유지보수에 유리합니다.

---

3. 프로젝트 구조

최종적으로 프로젝트는 다음과 같은 구조를 갖게 됩니다.

my-p5-app/
├── src/
│   ├── main.jsx           # 엔트리 포인트
│   ├── App.jsx            # p5 인스턴스를 마운트하는 컴포넌트
│   ├── index.css          # 전역 스타일
│   └── sketches/
│       └── rayCasting.js  # 실제 p5 스케치 로직
├── index.html
├── package.json
└── vite.config.js

sketches/ 폴더를 따로 두어 p5 스케치 파일을 분리하는 것이 관리에 용이합니다.

---

4. 전역 스타일 설정 (index.css)

브라우저 기본 여백을 제거하고, 캔버스가 화면을 가득 채우도록 최소한의 스타일만 적용합니다. p5.js 코드에서 참조할 CSS 변수도 함께 선언해둡니다.

/* 브라우저 기본 여백 제거 & 스크롤 방지 */
body {
  margin: 0;
  padding: 0;
  overflow: hidden;
  background-color: #000;
}

/* p5.js 코드가 참조하는 --accent 변수를 전역으로 선언 */
:root {
  --accent: #ffffff;
}

💡 CSS 변수와 p5.js의 연결
:root에 선언한 --accent 값은 getComputedStyle(document.documentElement).getPropertyValue('--accent')를 통해 p5.js 코드 내부에서 읽어올 수 있습니다. 이렇게 하면 색상 테마를 CSS 한 곳에서만 관리할 수 있어 유지보수가 매우 쉬워집니다.

---

5. 엔트리 포인트 (main.jsx)

Vite가 생성한 기본 main.jsx를 그대로 사용합니다. React 19의 createRoot API로 루트 DOM에 앱을 마운트합니다.

import { StrictMode } from "react";
import { createRoot } from "react-dom/client"; // React 및 DOM 렌더링 모듈을 불러옵니다.
import "./index.css";                          // 전역 스타일시트를 불러옵니다.
import App from "./App.jsx";                   // 메인 App 컴포넌트를 불러옵니다.

// 루트 요소에 App 컴포넌트를 렌더링.
createRoot(document.getElementById("root")).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

🧐 StrictMode는 왜 붙여야 할까?

<StrictMode>는 개발 모드에서만 작동하는 React의 "버그 탐지기" 입니다.
프로덕션 빌드에서는 아무런 영향을 주지 않으므로 성능 걱정 없이 붙여두면 됩니다.

StrictMode는 개발 중에 모든 컴포넌트를 "마운트 → 언마운트 → 다시 마운트" 하는
과정을 한 번 더 시뮬레이션합니다. 이렇게 하는 이유는 useEffect의 클린업 로직이
제대로 작성되었는지 검증하기 위해서입니다.

p5.js처럼 외부 리소스를 다루는 코드에서 특히 유용한데, 만약 p5Instance.remove()
클린업을 빼먹었다면 캔버스가 중복 생성되는 버그를 개발 중에 바로 발견할 수 있습니다.

---

6. 핵심: React 컴포넌트에서 p5 인스턴스 마운트하기 (App.jsx)

이 글의 가장 중요한 파트입니다. 외부 래퍼 없이 React의 useRef와 useEffect만으로 p5.js를 연동합니다.

import { useEffect, useRef } from "react";
import p5 from "p5";
import rayCastingSketch from "./sketches/rayCasting";

export default function App() {
  // p5 캔버스가 렌더링될 DOM 요소를 참조하기 위한 ref
  const p5ContainerRef = useRef(null);

  useEffect(() => {
    // p5 인스턴스 생성 (인스턴스 모드)
    // 첫 번째 인자: 스케치 함수, 두 번째 인자: 캔버스가 삽입될 DOM 노드
    const p5Instance = new p5((p) => {
      rayCastingSketch(p, 800); // 스케치 함수에 p5 인스턴스(p)와 크기 전달
    }, p5ContainerRef.current);

    // 클린업 함수: 컴포넌트가 언마운트될 때 p5 인스턴스를 제거하여 메모리 누수 방지
    return () => {
      p5Instance.remove();
    };
  }, []); // 의존성 배열을 비워 컴포넌트 마운트 시 단 한 번만 실행되도록 설정

  return (
    <div
      ref={p5ContainerRef}
      style={{
        display: "flex",
        justifyContent: "center",
        alignItems: "center",
        height: "100vh",
      }}
    ></div>
  );
}

🔑 핵심 포인트 3가지

1. useRef(null)로 DOM 참조 준비
   p5ContainerRef는 p5.js가 캔버스를 그려넣을 빈 <div>를 가리킵니다. 아직 마운트 전이므로 초기값은 null입니다.

2. new p5(sketch, container) — 인스턴스 모드
   p5 생성자의 첫 번째 인자로 스케치 콜백을, 두 번째 인자로 캔버스를 첨부할 DOM 노드를 전달합니다. 이렇게 하면 전역 스코프를 오염시키지 않고 p5를 React 컴포넌트 안에 안전하게 격리할 수 있습니다.

3. return () => p5Instance.remove() — 클린업
   React의 Strict Mode나 라우팅으로 컴포넌트가 여러 번 마운트/언마운트될 수 있습니다. 이때 remove()를 호출하지 않으면 캔버스가 중복 생성되고 메모리가 새게 됩니다. 이 한 줄이 래퍼 라이브러리 없이도 안전하게 p5를 다루는 비결입니다.

---

7. p5 스케치 파일 작성 (sketches/rayCasting.js)

이제 실제 비주얼 로직을 작성합니다. p5.js의 인스턴스 모드를 사용하므로, 모든 API는 콜백의 매개변수(여기서는 p)를 통해 호출합니다.

💡 왜 p5가 아니라 p일까?
p5라는 이름은 라이브러리 자체의 생성자/네임스페이스와 혼동될 수 있습니다. 커뮤니티 관례적으로 짧은 p를 매개변수 이름으로 사용하고 있습니다. 따라서 p.setup, p.draw 형태로 작성하시면 됩니다.

아래는 2D 레이 캐스팅 예제의 일부입니다.

export default function rayCastingSketch(p, size) {
  // --- 변수 및 상태 설정 영역 ---
  let walls = [];                 // 광선이 충돌할 벽(선분)들을 담는 배열
  let accentR, accentG, accentB;  // 강조 색상의 RGB 성분
  let light = { x: size / 2, y: size / 2 }; // 광원의 현재 위치
  let time = 0;                   // 애니메이션 흐름을 위한 시간 변수
  let mouseActive = false;        // 마우스 입력 여부 상태
  const NUM_RAYS = 180;           // 기본적으로 발사할 광선의 수

  // ============================================================
  // p5.js 초기화: 캔버스 및 환경 설정
  // ============================================================
  p.setup = function () {
    p.createCanvas(size, size); // 지정된 크기로 캔버스 생성

    // CSS 변수(--accent)에서 강조 색상 값을 가져옴
    const hex = getComputedStyle(document.documentElement)
      .getPropertyValue("--accent")
      .trim();
    const tmp = p.color(hex);    // hex 값을 p5.color 객체로 변환
    accentR = p.red(tmp);        // R 성분 추출
    accentG = p.green(tmp);      // G 성분 추출
    accentB = p.blue(tmp);       // B 성분 추출

    buildWalls();                // 벽(도형) 생성 함수 호출
    p.background(8, 8, 16);      // 초기 배경색 설정
  };

  // ============================================================
  // p5.js 메인 루프: 렌더링 및 인터랙션
  // ============================================================
  p.draw = function () {
    time += 0.008; // 시간 흐름 업데이트

    const mouseIn = p.mouseX > 0 && p.mouseX < size
                 && p.mouseY > 0 && p.mouseY < size;
    if (mouseIn) {
      light.x = p.mouseX;        // 마우스 위치로 광원 이동
      light.y = p.mouseY;
      mouseActive = true;
    } else if (mouseActive) {
      mouseActive = false;
    }
    if (!mouseActive) updateLightAuto(); // 마우스가 없으면 자동 이동

    p.background(8, 8, 16);             // 배경색 초기화
    const critical = collectCriticalAngles(); // 경계 각도 수집

    // ... (광선 발사, 다각형 렌더링 로직) ...
  };

  // ============================================================
  // 클릭 이벤트: 도형 크기 변경
  // ============================================================
  p.mousePressed = function () {
    if (p.mouseX >= 0 && p.mouseX < size && p.mouseY >= 0 && p.mouseY < size) {
      // 클릭 시 도형 크기 랜덤 변경 로직
    }
  };
}

🎨 스케치 파일 작성 팁

• p.setup, p.draw, p.mousePressed 등 모든 이벤트와 라이프사이클 훅은 p. 접두사로 호출합니다.
• 매개변수 size를 외부에서 주입받으면, React 컴포넌트 쪽에서 캔버스 크기를 동적으로 제어하기 쉬워집니다.
• CSS 변수를 색상 소스로 활용하면, 다크 모드/라이트 모드 전환이나 테마 변경을 React/p5 코드 수정 없이 CSS만으로 해결할 수 있습니다.

---

8. 개발 서버 실행

모든 준비가 끝났다면 개발 서버를 띄워봅니다.

npm run dev

브라우저에서 http://localhost:5173에 접속하면, 화면 중앙에 p5.js 캔버스가 렌더링되는 것을 확인할 수 있습니다. 마우스를 움직이면 광원이 따라다니고, 클릭하면 도형의 크기가 변하는 인터랙티브 아트 작품이 완성됩니다.

---

9. 프로덕션 빌드

실제 배포를 위해서는 다음 명령으로 빌드합니다.

npm run build

결과물은 dist/ 폴더에 생성되며, 다음과 같이 미리 확인할 수 있습니다.

npm run preview

dist/ 폴더를 Vercel, Netlify, GitHub Pages 등의 정적 호스팅 서비스에 업로드하면 그대로 배포됩니다.

---

10. 왜 이 방식이 2026년에 최선인가?

항목	외부 래퍼 사용	useRef + useEffect 직접 구현
의존성 수	많음 (래퍼 + p5)	p5 하나만
React 버전 업데이트 대응	래퍼 측 업데이트 대기 필요	즉시 대응 가능
세밀한 제어	제한적	완벽한 제어
라이프사이클 이해	블랙박스	명시적 이해
학습 가치	낮음	React 훅과 p5 인스턴스 모드를 동시에 학습

외부 래퍼는 편리함을 제공하지만, 결국 내부에서는 똑같이 useRef와 useEffect를 사용하고 있습니다. 직접 구현하면 레이어 하나를 줄이면서 같은 결과를 얻을 수 있고, React의 라이프사이클에 대한 이해도 깊어집니다.

---

마무리

이제 React 19 + Vite 8 + p5.js v2 환경에서 외부 래퍼 없이 React 훅만으로 p5.js 스케치를 연동하는 방법을 알게 되었습니다.

핵심은 단 세 줄입니다.

const p5ContainerRef = useRef(null);
const p5Instance = new p5(sketch, p5ContainerRef.current);
return () => p5Instance.remove();

이 패턴만 기억하면, 앞으로 어떤 복잡한 인터랙티브 아트 프로젝트든 React 컴포넌트 안에 안전하게 담아낼 수 있습니다. 여러분의 크리에이티브한 프로젝트를 시작해보세요! 🎨