entity-server-erd

entity-server 엔티티 설정 파일을 재귀적으로 읽어 ERD 캔버스로 시각화하는 패키지입니다.

설치

npm install entity-server-erd
# React 컴포넌트 사용 시
npm install @xyflow/react react react-dom

사용법

1. Node.js — 엔티티 파싱

import { parseEntitiesDir, inferRelations } from "entity-server-erd";

const entities = await parseEntitiesDir("/path/to/entities");
const relations = inferRelations(entities);
console.log(entities, relations);

2. React — ERD 캔버스

⚠️ @xyflow/react/dist/style.css 를 반드시 임포트해야 합니다.

import "@xyflow/react/dist/style.css";
import { useEffect, useState } from "react";
import { parseEntitiesDir } from "entity-server-erd";
import { EntityERD } from "entity-server-erd/react";
import type { ParsedEntity } from "entity-server-erd";

export default function ErdPage() {
  const [entities, setEntities] = useState<ParsedEntity[]>([]);

  useEffect(() => {
    // Vite/webpack 환경에서는 빌드타임에 엔티티를 불러와 props로 전달하는 방식을 권장합니다.
    fetch("/api/entities").then((r) => r.json()).then(setEntities);
  }, []);

  return <EntityERD entities={entities} height="100vh" />;
}

Vite 환경 (권장)

// vite.config.ts
import { defineConfig } from "vite";
import { parseEntitiesDir } from "entity-server-erd";

export default defineConfig(async () => {
  const entities = await parseEntitiesDir("../server/entities");
  return {
    define: { __ERD_ENTITIES__: JSON.stringify(entities) },
  };
});

// App.tsx
declare const __ERD_ENTITIES__: ParsedEntity[];
<EntityERD entities={__ERD_ENTITIES__} />

Props

| 이름 | 타입 | 기본값 | 설명 | |------|------|--------|------| | entities | ParsedEntity[] | 필수 | 파싱된 엔티티 목록 | | height | string \| number | "100vh" | 컨테이너 높이 | | onSelectEntity | (e: ParsedEntity \| null) => void | — | 엔티티 선택 콜백 | | showSearch | boolean | true | 검색/필터 툴바 표시 | | showMinimap | boolean | true | 미니맵 표시 | | showControls | boolean | true | 줌/패닝 컨트롤 표시 | | style | CSSProperties | — | 루트 컨테이너 스타일 | | className | string | — | 루트 컨테이너 클래스명 |

기능

• 엔티티 JSON을 재귀적으로 읽어 자동 파싱
• 관계 자동 추론: _seq suffix → direct 관계, ref_entity/ref_seq → polymorphic 관계
• 모듈(디렉터리)별 컬러링 및 접기/펼치기
• 키워드 검색, 모듈 필터
• 포커스 모드: 전체 / 1-hop / 2-hop
• 선택 엔티티 상세 패널 (index 필드, body 필드, 관계 목록)
• direct/polymorphic 관계 토글

라이선스

MIT