[ReactFlow] 이제 reactflow 대신 @xyflow/react

기존 프로젝트에서 reactflow를 사용하고 있었는데, xyflow에 대한 마이그레이션 글을 보고 정리하는 글입니다.

https://reactflow.dev/learn/troubleshooting/migrate-to-v12

Migrate to React Flow 12 - React Flow

 

 

1. 패키지명 변경 및 모노레포 통합
   • 기존 reactflow 패키지가 이제는 @xyflow/react로 완전히 대체되었습니다. 더 이상 기본(default) 방식이 아닌 네임드(named) import 형태로 사용해야 합니다.
   예:

// 이전
import ReactFlow from 'reactflow';

// 이후
import { ReactFlow } from '@xyflow/react';
import '@xyflow/react/dist/style.css';



•    내부적으로는 React Flow뿐 아니라 Svelte Flow도 함께 관리하는 xyflow 모노레포 구조로 통합되었습니다.



⸻

2. React Flow 12의 주요 기능 확장

React Flow 12 (즉, @xyflow/react)는 많은 기능이 추가되고, 범용적인 개선 사항이 포함되었습니다. 주요 추가 기능은 다음과 같습니다:

• 서버 사이드 렌더링(SSR) 지원
• 클라이언트 자바스크립트 없이도 다이어그램 표현 가능
• 문서 사이트, OG 이미지 생성 등에 활용
• 컴퓨팅 플로우용 훅/헬퍼 도구 제공
• 노드 간 데이터 흐름 처리, 값 파생 등을 쉽게 구현
• 다크 모드 지원
• colorMode="light" | "dark" | "system" 옵션으로 테마 전환
• 향상된 개발자 경험 (TSDoc 도입)
• IDE에서 API 사용 시 풍부한 설명 제공
• 퍼포먼스 최적화
• 렌더링 효율 개선, 초기 상태 일괄 처리 등 처리 성능 향상

또한 아래 부가 기능들이 포함되어 있습니다:
• useConnection, controlled viewport, ViewportPortal, onDelete, onBeforeDelete, isValidConnection, autoPanSpeed, paneClickDistance, 더 유연한 Background 스타일링 등


⸻

3. API 변화 및 마이그레이션 포인트

버전 11에서 12로 넘어오면서 중요한 브레이킹 체인지도 있었어요. 공식 가이드에 따르면 다음 사항들을 유의해야 합니다:

• reactflow → @xyflow/react로 패키지 변경
• 노드 측정 속성 변경: node.width / node.height (기존 방식) → 이제는 node.measured.width / node.measured.height로 측정값 제공
• width / height는 이제 CSS 인라인 스타일로 동작하게 됩니다.
• 서버 사이드 렌더링, 컴퓨팅 훅 등 새로운 기능을 활용하려면 필수 마이그레이션이 필요합니다.

⸻

요약 (블로그 작성용)

항목 요약
패키지 변경 reactflow → @xyflow/react
통합 구조 React Flow + Svelte Flow 함께 관리하는 모노레포 구조
주요 기능 SSR, 컴퓨팅 훅, 다크 모드, TSDoc, 성능 개선 등
API 변경점 노드 측정값은 node.measured.*, 스타일 적용 방식 변경 등
개발자 경험 강화 IDE 내 설명 강화, hooks/viewport/controller 기능 강화