react-flow-preview

v0.2.3

Published

6 days ago

Static preview for React Flow: SSR/HTML, PNG (Puppeteer), and browser <img> via html-to-image.

0High
0Medium
0Low

phonghalo

react-flow xyflow @xyflow/react server-side preview screenshot og-image ssr

react-flow-preview

Thư viện tạo preview tĩnh cho đồ thị React Flow (@xyflow/react) trên Node.js: xuất HTML (SSR giống hướng dẫn chính thức) và tùy chọn ảnh PNG qua Puppeteer — cùng ý tưởng với ví dụ Server Side Image Creation (ví dụ Pro trên trang React Flow; package này là triển khai tách riêng, mã nguồn mở).

English: Static server-side preview for React Flow graphs — HTML via renderToStaticMarkup + optional PNG via headless Chromium.

Live demo

Open on CodeSandbox — Vite app with custom nodes, interactive editor, and static FlowPreviewImage preview.

Source repo: github.com/Phonghalo/demo-react-flow-preview

Yêu cầu

Node.js ≥ 18
Peer dependencies (bạn cài trong app của bạn):

npm install react react-dom @xyflow/react react-flow-preview

PNG (tùy chọn): cài thêm Puppeteer, rồi import từ react-flow-preview/puppeteer (tách entry để project không cài Puppeteer vẫn typecheck được):

npm install puppeteer

Cài đặt

npm install react-flow-preview

Đảm bảo đã có react, react-dom, @xyflow/react đúng phiên bản mà app đang dùng (React Flow 12+).

Dữ liệu đầu vào (`nodes` / `edges`)

API nhận cùng kiểu dữ liệu như React Flow controlled:

import type { Node, Edge } from '@xyflow/react';

const nodes: Node[] = [
  {
    id: '1',
    type: 'input',
    position: { x: 0, y: 0 },
    data: { label: 'Start' },
    width: 120,
    height: 40,
  },
  {
    id: '2',
    position: { x: 220, y: 90 },
    data: { label: 'Process' },
    width: 140,
    height: 40,
  },
];

const edges: Edge[] = [
  { id: 'e1-2', source: '1', target: '2' },
];

Quan trọng khi render phía server (SSR / ảnh)

Theo tài liệu SSR của React Flow, mỗi node cần kích thước xác định trước khi vẽ tĩnh:

Đặt width và height trên từng node, hoặc
Dùng node.measured.width / node.measured.height nếu bạn đồng bộ từ client sau khi đo.

Nếu thiếu kích thước, preview có thể trống hoặc sai layout.

Custom nodes / edges: truyền nodeTypes / edgeTypes giống <ReactFlow /> (xem FlowPreviewOptions).

API

`FlowPreview`

Component React dùng cho SSR hoặc tùy biến — tắt kéo, zoom, kết nối… để phù hợp preview tĩnh.

`react-flow-preview/client` (từ 0.1.1)

Trong app Vite / CRA chỉ cần cây React Flow tĩnh (không phải ảnh), import:

import { FlowPreview } from 'react-flow-preview/client'

để tránh kéo react-dom/server vào bundle. Entry chính react-flow-preview vẫn dùng cho Node (SSR / PNG).

`react-flow-preview/client-image` (từ 0.2.0) — ảnh tĩnh `<img>`

Khi bạn muốn giống thumbnail / OG / so sánh pixel (không còn DOM React Flow tương tác):

import { FlowPreviewImage } from 'react-flow-preview/client-image';

<FlowPreviewImage
  nodes={nodes}
  edges={edges}
  width={520}
  height={380}
  fitView
  colorMode="dark"
  background={false}
  pixelRatio={2}
  captureDelayMs={180}
  imgProps={{ alt: 'Preview' }}
/>;

Component mount một FlowPreview off-screen, gọi html-to-image toPng, rồi hiển thị <img src="data:image/png;base64,…">. Mỗi lần nodes/edges (và các prop đồ họa liên quan) đổi, ảnh được chụp lại.

toPngOptions: tùy chọn bổ sung cho toPng (ví dụ filter, skipFonts).
Trên đồ thị rất lớn có thể cần tăng captureDelayMs hoặc debounce phía app.

`renderFlowPreviewMarkup(data, options)`

Trả về chuỗi HTML (fragment), không kèm CSS. Dùng khi bạn tự bọc layout hoặc ghép vào template có sẵn stylesheet.

`loadXyflowStylesheet()`

Đọc file style.css của @xyflow/react từ node_modules để nhúng vào <style>.

`renderFlowPreviewDocument(data, options)`

Trả về tài liệu HTML đầy đủ (<!DOCTYPE html>…) đã nhúng CSS mặc định của xyflow — phù hợp Puppeteer hoặc lưu file .html.

Tùy chọn thêm: stylesheet, extraCss, lang, title (xem type FlowPreviewDocumentOptions).

`renderFlowPreviewPng(data, options, launchOptions?)` — `import { renderFlowPreviewPng } from 'react-flow-preview/puppeteer'`

Mở Chromium bằng Puppeteer, render renderFlowPreviewDocument, chụp PNG (Buffer).

options gồm mọi field của preview (width, height, fitView, …) và kiểu FlowPreviewImageOptions (tùy chọn viewport Puppeteer, không liên quan component FlowPreviewImage):
- deviceScaleFactor (mặc định 2)
- waitUntil (mặc định 'load')
- navigationTimeoutMs (mặc định 30000)
- omitBackground — PNG trong suốt nếu true

launchOptions kiểu PuppeteerLaunchOptions (alias của LaunchOptions từ Puppeteer), ví dụ Docker:

await renderFlowPreviewPng(data, opts, {
  headless: true,
  args: ['--no-sandbox', '--disable-setuid-sandbox'],
});

Ví dụ: HTML tĩnh (OG image / API)

import { renderFlowPreviewDocument } from 'react-flow-preview';
import type { Node, Edge } from '@xyflow/react';

export function buildFlowOgHtml(nodes: Node[], edges: Edge[]) {
  return renderFlowPreviewDocument(
    { nodes, edges },
    {
      width: 1200,
      height: 630,
      fitView: true,
      colorMode: 'light',
      title: 'Workflow preview',
    },
  );
}

Ví dụ: PNG (Express)

import express from 'express';
import type { Node, Edge } from '@xyflow/react';
import { renderFlowPreviewPng } from 'react-flow-preview/puppeteer';

const app = express();

app.get('/preview.png', async (_req, res) => {
  const nodes: Node[] = [
    {
      id: 'a',
      position: { x: 0, y: 0 },
      data: { label: 'A' },
      width: 100,
      height: 36,
    },
    {
      id: 'b',
      position: { x: 180, y: 60 },
      data: { label: 'B' },
      width: 100,
      height: 36,
    },
  ];
  const edges: Edge[] = [{ id: 'ab', source: 'a', target: 'b' }];

  const png = await renderFlowPreviewPng(
    { nodes, edges },
    {
      width: 800,
      height: 500,
      fitView: true,
      deviceScaleFactor: 2,
    },
  );

  res.type('png').send(png);
});

Kiểu TypeScript xuất ra

| Export | Mô tả | |--------|--------| | FlowPreviewData | { nodes, edges } | | FlowPreviewOptions | width, height, fitView, colorMode, nodeTypes, … | | FlowPreviewViewportOptions | Phần viewport (không gồm background / types) | | FlowPreviewImageOptions | Tuỳ chọn PNG | | FlowPreviewDocumentOptions | FlowPreviewOptions + stylesheet, extraCss, … | | FlowPreviewProps | Props của component FlowPreview | | PuppeteerLaunchOptions | Alias LaunchOptions của Puppeteer (từ entry react-flow-preview/puppeteer) |

Ghi chú

Phiên bản React Flow: thiết kế cho @xyflow/react v12+ (SSR).
So với ví dụ Pro: ví dụ trên reactflow.dev dùng stack tương tự (React Flow + Puppeteer); package này gói phần render HTML + tuỳ chọn chụp ảnh thành API npm.
Attribution: tuân thủ điều khoản React Flow khi hiển thị công khai; có thể truyền proOptions nếu bạn có bản Pro.

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

react-flow-preview

Live demo

Yêu cầu

Cài đặt

Dữ liệu đầu vào (nodes / edges)

Quan trọng khi render phía server (SSR / ảnh)

API

FlowPreview

react-flow-preview/client (từ 0.1.1)

react-flow-preview/client-image (từ 0.2.0) — ảnh tĩnh <img>

renderFlowPreviewMarkup(data, options)

loadXyflowStylesheet()

renderFlowPreviewDocument(data, options)

renderFlowPreviewPng(data, options, launchOptions?) — import { renderFlowPreviewPng } from 'react-flow-preview/puppeteer'

Ví dụ: HTML tĩnh (OG image / API)

Ví dụ: PNG (Express)

Kiểu TypeScript xuất ra

Ghi chú

License

Dữ liệu đầu vào (`nodes` / `edges`)

`FlowPreview`

`react-flow-preview/client` (từ 0.1.1)

`react-flow-preview/client-image` (từ 0.2.0) — ảnh tĩnh `<img>`

`renderFlowPreviewMarkup(data, options)`

`loadXyflowStylesheet()`

`renderFlowPreviewDocument(data, options)`

`renderFlowPreviewPng(data, options, launchOptions?)` — `import { renderFlowPreviewPng } from 'react-flow-preview/puppeteer'`