Instance Mode와 컴포넌트 아키텍처의 통합

React 환경에서 p5.js를 사용할 때 서드파티 래퍼(Wrapper) 라이브러리를 사용하는 것은 지양해야 합니다. 래퍼는 p5의 내부 라이프사이클을 블랙박스화하여 메모리 누수를 유발하고, 복잡한 인터랙션이나 커스텀 셰이더 적용 시 API 접근성을 제한하기 때문입니다.

이 글에서는 React의 훅(Hook)을 이용해 p5의 Instance Mode를 직접 바인딩하고, 아트워크 로직을 sketch.js로 분리하는 보일러플레이트를 구축합니다. 나아가 React 애플리케이션의 진입점과 컴포넌트 아키텍처 설계 원칙까지 함께 다룹니다.

1. 환경 세팅 및 파일 구조

터미널 명령어

Vite를 이용해 React 프로젝트를 생성하고, p5.js를 의존성에 추가합니다.

# Vite React 프로젝트 생성 (JavaScript 템플릿 사용)
npm create vite@latest p5-react-art -- --template react

# 디렉토리 이동 및 의존성 설치
cd p5-react-art
npm install

# p5.js 설치 (래퍼 없이 코어만 설치)
npm install p5

# 개발 서버 실행
npm run dev

파일 구조

아트워크 로직과 React 컴포넌트를 명확히 분리하여 관심사(Separation of Concerns)를 나눕니다.

p5-react-art/
├── node_modules/
├── public/
├── src/
│   ├── assets/
│   ├── components/
│   │   └── P5Canvas.jsx      # p5 인스턴스를 마운트/언마운트하는 React 컴포넌트
│   ├── sketch.js             # p5.js 아트워크 로직 (Instance Mode 함수)
│   ├── App.jsx               # 애플리케이션 레이아웃 및 컴포넌트 조합
│   ├── main.jsx              # React 애플리케이션의 부트스트랩 진입점
│   └── index.css             # 전역 스타일 초기화
├── index.html
├── package.json
└── vite.config.js

2. 핵심 원리 1: Instance Mode와 컴포넌트 라이프사이클

p5.js는 기본적으로 setup()과 draw()를 전역(window) 스코프에 선언하는 Global Mode를 사용합니다. 하지만 React는 단일 페이지 애플리케이션(SPA)이며, 컴포넌트의 마운트/언마운트가 빈번하게 발생합니다.

Global Mode를 사용할 경우, 컴포넌트가 언마운트되어도 window에 바인딩된 p5 인스턴스와 requestAnimationFrame 루프가 파괴되지 않아 메모리 누수(Memory Leak) 및 좀비 캔버스(Zombie Canvas) 가 발생합니다.

이를 해결하기 위해 Instance Mode를 사용합니다. Instance Mode는 p5의 모든 메서드와 프로퍼티를 전역 스코프가 아닌, 콜백 함수의 인자(p)로 전달되는 로컬 스코프로 캡슐화합니다. 이를 통해 React의 useEffect cleanup 함수에서 p.remove()를 호출하여 DOM과 메모리를 명시적으로 해제할 수 있습니다.

3. 핵심 원리 2: 엔트리 포인트와 아키텍처 설계

3.1. main.jsx의 역할: 애플리케이션의 부트스트래핑 (Bootstrapping)

main.jsx는 C나 Java의 main() 함수처럼 React 애플리케이션이 실행되는 가장 첫 번째 진입점(Entry Point) 입니다.

Vite가 index.html을 로드하면, HTML 내부의 <script type="module" src="/src/main.jsx"></script> 태그를 통해 이 파일이 가장 먼저 실행됩니다. main.jsx의 핵심 역할은 가상 DOM(Virtual DOM)과 실제 브라우저 DOM을 연결(Bridging) 하는 것입니다.

// src/main.jsx
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import App from './App.jsx'
import './index.css'

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <App />
  </StrictMode>,
)

기술적 의미:

• DOM 주입: React는 자체적인 렌더링 엔진을 가지고 있습니다. main.jsx는 React에게 "이 #root div 안에 네가 원하는 대로 UI를 그려줘"라고 지시하는 부트스트랩 코드입니다.
• 전역 설정 주입: 전역 CSS(index.css)나 전역 상태 관리(Redux, Zustand 등), 라우터(BrowserRouter) 등을 애플리케이션 최상단에 주입하는 곳이기도 합니다.

3.2. P5Canvas.jsx를 components로 분리하는 이유

단순히 "파일을 나누기 위함"이 아니라, 다음과 같은 3가지 핵심 원칙을 지키기 위함입니다.

① 불순물(Impurity)과 부작용(Side Effects)의 캡슐화

React의 철학은 선언형(Declarative) 이며, 컴포넌트는 가능하면 순수 함수(Pure Function) 여야 합니다. (같은 인풋에는 항상 같은 아웃풋이 나와야 함).
하지만 p5.js는 본질적으로 명령형(Imperative) 이며, DOM을 직접 조작하고 requestAnimationFrame이라는 거대한 부작용(Side Effects) 을 발생시킵니다.

이러한 '불순물'을 App.jsx에 직접 섞어 쓰면, React의 상태(State)와 p5의 상태가 뒤엉켜 디버깅하기 지옥 같은 코드가 됩니다. P5Canvas.jsx로 분리함으로써 "이 컴포넌트 내부에서만 p5의 부작용이 발생하고, 언마운트 시 깨끗하게 청소된다" 는 것을 명확히 캡슐화(Encapsulation)할 수 있습니다.

② 관심사의 분리 (Separation of Concerns)

• App.jsx (Orchestrator / 지휘자): 애플리케이션의 전체 레이아웃, 라우팅, UI 컴포넌트들의 배치, 전역 데이터 흐름을 담당합니다.
• P5Canvas.jsx (Implementer / 실행자): 주어진 영역에 p5.js를 활용해 특정 비주얼을 렌더링하는 역할만 담당합니다.

만약 App.jsx 안에 p5 코드가 직접 있다면, 나중에 웹사이트에 '네비게이션 바'나 '푸터'를 추가할 때 레이아웃 코딩과 그래픽스 코딩이 뒤섞여 유지보수가 어려워집니다. 컴포넌트를 분리하면 App.jsx는 그저 <P5Canvas />라는 태그만 보고 "아, 여기에 그래픽이 들어가는구나"라고 추상화할 수 있습니다.

③ 재사용성 (Reusability)과 조합성 (Composability)

앞으로 웹사이트가 커져서 다음과 같은 상황이 올 수 있습니다.

• 랜딩 페이지에는 큰 파티클 배경이 필요하고,
• About 페이지에는 작은 인터랙티브 로고가 필요하며,
• 404 페이지에는 다른 에러 그래픽이 필요할 수 있습니다.

P5Canvas.jsx가 독립된 컴포넌트로 분리되어 있고, sketch.js의 로직을 인자로 받거나 Props를 전달받을 수 있게 설계해 둔다면, 하나의 아트워크 엔진을 여러 페이지에서 재사용할 수 있습니다.

// App.jsx의 미래 모습 예시
function App() {
  return (
    <div className="app-layout">
      <Header />
      <main>
        {/* 재사용 가능한 p5 컴포넌트 */}
        <P5Canvas sketch={particleSketch} width={800} height={600} />
        <P5Canvas sketch={logoSketch} width={200} height={200} />
      </main>
      <Footer />
    </div>
  );
}

4. 코드 구현

4.1. 아트워크 로직 분리 (src/sketch.js)

sketch.js는 p5 인스턴스(p)를 인자로 받아 setup과 draw를 정의하는 함수를 내보냅니다. 이 파일에는 React 관련 코드가 전혀 포함되지 않아, 순수하게 그래픽 알고리즘에만 집중할 수 있습니다.

// src/sketch.js

/**
 * p5 Instance Mode Sketch
 * @param {object} p - p5 인스턴스 컨텍스트
 */
export default function sketch(p) {
  let particles = [];
  const NUM_PARTICLES = 150;

  // p.setup: 캔버스 초기화 및 상태 설정
  p.setup = () => {
    // React 컴포넌트의 DOM 노드 크기에 맞춰 캔버스 생성
    // 부모 컨테이너의 크기를 참조하므로 반응형 대응이 용이함
    const container = p.canvas.parentElement;
    p.createCanvas(container.offsetWidth, container.offsetHeight);
    p.colorMode(p.HSB, 360, 100, 100, 100);
    p.background(0, 0, 10);

    // 파티클 초기화
    for (let i = 0; i < NUM_PARTICLES; i++) {
      particles.push({
        pos: p.createVector(p.random(p.width), p.random(p.height)),
        vel: p.createVector(0, 0),
        hue: p.random(180, 260),
      });
    }
  };

  // p.draw: 프레임별 렌더링 루프
  p.draw = () => {
    // 잔상 효과를 위한 반투명 배경 (트레일 효과)
    p.background(0, 0, 10, 15);

    const time = p.millis() * 0.0005;

    particles.forEach((pt) => {
      // 펄린 노이즈를 기반으로 벡터 필드 생성
      const angle = p.noise(pt.pos.x * 0.003, pt.pos.y * 0.003, time) * p.TWO_PI * 2;
      
      // 노이즈 기반 각도를 속도 벡터로 변환
      pt.vel.set(p.cos(angle), p.sin(angle));
      pt.vel.mult(1.5);
      
      // 위치 갱신 및 화면 경계 래핑(Wrapping)
      pt.pos.add(pt.vel);
      if (pt.pos.x < 0) pt.pos.x = p.width;
      if (pt.pos.x > p.width) pt.pos.x = 0;
      if (pt.pos.y < 0) pt.pos.y = p.height;
      if (pt.pos.y > p.height) pt.pos.y = 0;

      // 렌더링
      p.noStroke();
      p.fill(pt.hue, 80, 90, 60);
      p.circle(pt.pos.x, pt.pos.y, 3);
    });
  };

  // p.windowResized: 브라우저 창 크기 변경 시 캔버스 리사이즈
  // React 컨테이너가 창 크기를 따라가도록 설정한 경우 유용
  p.windowResized = () => {
    const container = p.canvas.parentElement;
    p.resizeCanvas(container.offsetWidth, container.offsetHeight);
  };
}

4.2. React 바인딩 컴포넌트 (src/components/P5Canvas.jsx)

React 컴포넌트에서는 useRef로 DOM 요소와 p5 인스턴스를 참조하고, useEffect를 통해 인스턴스의 생성과 파괴를 통제합니다.

// src/components/P5Canvas.jsx
import { useRef, useEffect } from 'react';
import p5 from 'p5';
import sketch from '../sketch';

export default function P5Canvas() {
  // 1. DOM 참조 및 p5 인스턴스 참조를 위한 Ref 생성
  const containerRef = useRef(null);
  const p5InstanceRef = useRef(null);

  useEffect(() => {
    // 2. 마운트 시 p5 인스턴스 생성
    // sketch 함수와 DOM 컨테이너를 p5 생성자에 전달
    if (containerRef.current) {
      p5InstanceRef.current = new p5(sketch, containerRef.current);
    }

    // 3. 언마운트 시 Cleanup (Destructor)
    return () => {
      if (p5InstanceRef.current) {
        // p5.remove()는 캔버스 DOM을 제거하고, 
        // requestAnimationFrame 루프를 중단하며, 내부 이벤트 리스너를 해제함
        p5InstanceRef.current.remove(); 
      }
    };
  }, []); // 컴포넌트 마운트/언마운트 시에만 실행

  // 4. p5가 캔버스를 주입할 빈 DOM 컨테이너 렌더링
  return (
    <div 
      ref={containerRef} 
      style={{ 
        width: '100vw', 
        height: '100vh', 
        overflow: 'hidden',
        display: 'flex',
        justifyContent: 'center',
        alignItems: 'center',
        backgroundColor: '#0a0a0a'
      }} 
    />
  );
}

4.3. 앱 진입점 및 스타일 초기화

기본 보일러플레이트의 불필요한 마진을 제거하여 캔버스가 화면을 가득 채우도록 합니다.

src/App.jsx

import P5Canvas from './components/P5Canvas';

function App() {
  return <P5Canvas />;
}

export default App;

src/index.css

/* p5 캔버스의 기본 margin 및 body 스크롤 제거 */
body {
  margin: 0;
  padding: 0;
  overflow: hidden;
  background-color: #0a0a0a;
}

/* p5가 생성하는 canvas 요소의 기본 스타일 조정 */
canvas {
  display: block;
}

5. 아티스트를 위한 기술적 가이드

1. 상태(State) 관리의 분리:
   React의 useState로 아트워크의 파라미터(예: 파티클 수, 노이즈 스케일)를 관리하고, 이를 sketch.js에 전달해야 한다면 useEffect의 의존성 배열에 해당 상태를 넣지 마십시오. 대신 p5InstanceRef.current를 통해 p5 인스턴스의 커스텀 프로퍼티에 직접 할당하거나, React State를 sketch.js 내부의 클로저/모듈 레벨 변수와 동기화하는 패턴을 사용해야 불필요한 re-render와 p5 인스턴스 재생성을 막을 수 있습니다.
2. DOM 접근:
   sketch.js 내부에서 document.getElementById 등을 사용하는 것은 지양하십시오. 대신 p.canvas.parentElement를 통해 React가 주입한 컨테이너 노드에 접근하거나, React 컴포넌트에서 ref를 통해 계산된 크기를 sketch 함수의 인자로 넘겨주는 것이 순수성(Purity)을 유지하는 방법입니다.
3. 고성능 렌더링:
   p5 코어는 2D 렌더러를 기본으로 사용합니다. WebGL 기반의 3D 또는 고성능 2D 셰이더가 필요하다면 p.createCanvas(w, h, p.WEBGL)로 생성자를 변경하십시오. 단, WEBGL 모드에서는 좌표계가 중앙 origin(0,0)으로 변경되므로 기하학 연산 시 이를 고려해야 합니다.