JS UI 라이브러리를 instance로 만들어 React 이식하기 (with useImperativeHandle & Tui Grid) 💘

가끔 좋은 JS 라이브러리를 발견해서 써보려고 했는데, 해당 라이브러리가 직접 React를 지원하지 않는 경우들이 있다.

이런 경우에 UI 컴포넌트 instance를 생성해서 React에 직접 연결해주는 작업이 필요한데, 이를 어떻게 잘 할 수 있을지 고민해보았다 😃

(이런 경우는 인스턴스를 직접 컨트롤해야 하는 UI 컴포넌트가 많아서 더욱 고민이 필요하다)

 

보통 React에서는 useRef를 통해서 인스턴스를 관리하는데, 여기에 추가로 useImperativeHandle을 활용해 Tui Grid를 React에서 자연스럽게 사용하는 예제를 한번 만들어 보았다.

(tui는 react 까지 레핑된 라이브러리를 하긴 하는데.., 유지보수가 멈췄다 🤣)

1️⃣ 기본적인 그리드 설정

Tui Grid는 JavaScript 기반의 UI 라이브러리로, 기본적으로 new Grid({ ...options }) 형태로 인스턴스를 생성해야 한다.

(코드를 보면, Grid는 class로 작성되어 있다)

따라서 먼저 기본적인 React 컴포넌트 형태로 감싸는 것부터 시작해 보자.

'use client';
import 'tui-grid/dist/tui-grid.css';
import { useEffect, useRef } from 'react';
import Grid from 'tui-grid';
import type { OptGrid, OptRowHeader } from 'tui-grid/types/options';

interface TuiGridReactProps {
  data?: Record<string, any>[];
  columns: { header: string; name: string; width?: number }[];
  rowHeaders?: OptRowHeader[];
  gridOptions?: Partial<OptGrid>;
}

const TuiGridReact = ({ data = [], columns, rowHeaders, gridOptions }: TuiGridReactProps) => {
  const gridRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!gridRef.current) return;
    new Grid({
      el: gridRef.current,
      data,
      columns,
      rowHeaders,
      ...gridOptions,
    });
  }, [data, columns, rowHeaders, gridOptions]);

  return <div ref={gridRef} />;
};

export default TuiGridReact;

위 코드는 data와 columns 등의 옵션을 받아 Tui Grid를 렌더링하는 아주 기본적인 버전이다.

하지만 이 코드에는 중대한 문제가 있다! 🚨

• Strict Mode에서 문제가 발생할 수 있음 → React Strict Mode에서는 useEffect가 두 번 실행되기 때문에, 그리드가 두 개 생성되는 문제가 생길 수 있다.
• 데이터 갱신이 어렵다 → 외부에서 data가 변경되더라도 기존 Grid 인스턴스가 이를 반영하지 않는다.
• Grid 인스턴스를 컨트롤할 수 없다 → resetData, getInstance 같은 기능을 제공하고 싶다면 인스턴스에 접근할 방법이 필요하다.

이를 해결하기 위해 추가적인 useRef와 useImperativeHandle을 활용한 개선된 방식을 적용해 보자. 🛠️

2️⃣ Grid 인스턴스 관리하기 (useRef & useImperativeHandle)

Grid 인스턴스를 유지하고 외부에서 조작할 수 있도록 forwardRef와 useImperativeHandle을 추가한다.

import { forwardRef, useImperativeHandle } from 'react';

export interface TuiGridReactRef {
  reloadData: (newData: Record<string, any>[]) => void;
  getInstance: () => Grid | null;
}

const TuiGridReact = forwardRef<TuiGridReactRef, TuiGridReactProps>(
  ({ data = [], columns, rowHeaders, gridOptions }, ref) => {
    const gridRef = useRef<HTMLDivElement>(null);
    const instanceRef = useRef<Grid | null>(null);

    useEffect(() => {
      if (!gridRef.current) return;

      requestAnimationFrame(() => {
        instanceRef.current = new Grid({
          el: gridRef.current!,
          data,
          columns,
          rowHeaders,
          ...gridOptions,
        });
      });

      return () => {
        instanceRef.current?.destroy();
        instanceRef.current = null;
      };
    }, [data, columns, rowHeaders, gridOptions]);

    useImperativeHandle(ref, () => ({
      reloadData: (newData) => {
        instanceRef.current?.resetData(newData);
      },
      getInstance: () => instanceRef.current,
    }));

    return <div ref={gridRef} />;
  },
);

export default TuiGridReact;

🔥 여기서 개선된 점

1. instanceRef를 활용한 인스턴스 관리 → useRef를 활용해 Grid 인스턴스를 유지하고, useEffect에서 관리한다.
2. useImperativeHandle을 통한 외부 제어 기능 제공 → reloadData, getInstance 메서드를 제공해 Grid 인스턴스를 컨트롤할 수 있다.
3. Strict Mode에서의 문제 해결 → requestAnimationFrame을 활용해 DOM이 완전히 로드된 후 그리드를 생성하여 null 참조 문제를 방지한다.

3️⃣ 외부에서 활용하기

이제 이 컴포넌트를 실제로 사용하는 예제를 살펴보자. useRef를 이용해 Grid의 데이터를 갱신해보자.

import { useRef } from 'react';
import TuiGridReact, { TuiGridReactRef } from './TuiGridReact';

const App = () => {
  const gridRef = useRef<TuiGridReactRef>(null);

  const updateData = () => {
    gridRef.current?.reloadData([
      { id: 1, name: '새로운 데이터' },
      { id: 2, name: '업데이트된 데이터' },
    ]);
  };

  return (
    <div>
      <TuiGridReact
        ref={gridRef}
        columns={[{ header: 'ID', name: 'id' }, { header: '이름', name: 'name' }]}
      />
      <button onClick={updateData}>데이터 변경</button>
    </div>
  );
};

export default App;

이제 버튼을 누르면 Grid의 데이터가 변경되는 걸 확인할 수 있다. 🎉

🎯 정리

1. Tui Grid 같은 JS UI 라이브러리는 React에서 바로 사용할 수 없기 때문에 컴포넌트 형태로 감싸야 한다.
2. useRef를 활용해 Grid 인스턴스를 유지하고 useEffect에서 초기화 및 정리 작업을 수행한다.
3. useImperativeHandle을 활용하면 외부에서 인스턴스를 컨트롤할 수 있어 더욱 유연한 컴포넌트가 된다.

이제 Tui Grid를 React에서 자유롭게 활용할 수 있다! 🚀

 

😶 실제 작성한 코드 !

https://github.com/citron03/practice-next-15/commit/d74d6c03763d16cdc1db15c52f472f709f25f823

feat(grid): tui grid react instance develop · citron03/practice-next-15@d74d6c0

 

 

참고자료 👻

https://ko.react.dev/reference/react/useImperativeHandle

useImperativeHandle – React