@filekit-studio/diagram

Declarative Diagram-as-Code & JSON graph compiler for @filekit-studio/sketch.

Documentation • Quickstart Guide • Live Playground

@filekit-studio/diagram lets you generate and render beautiful hand-drawn whiteboards, architecture diagrams, and flowcharts directly from declarative JSON or Diagram-as-Code in React and Next.js.

• Zero Coordinates Required: Provide nodes, edges, and clusters — the deterministic DAG layout engine positions and aligns everything automatically.
• Sketch Aesthetics: Powered by @filekit-studio/sketch, rendering organic hand-drawn shapes, rough fills, and magnetic connector arrows.
• Obstacle Evasion & Corridor Seeking: Orthogonal elbow lines automatically navigate around shapes without crossing intermediate services.
• Submerged Passthrough Tunneling: Traversed lines automatically turn into subtle dashed X-ray paths underneath shapes.
• Directional Flows: Supports Left-to-Right (LR), Top-to-Bottom (TB), Right-to-Left (RL), and Bottom-to-Top (BT).
• Excalidraw Native: Direct conversion from .excalidraw schema files and element arrays.
• 100% Client-Side: Zero server calls, zero tracking, works fully offline.

Installation

bun add @filekit-studio/diagram @filekit-studio/sketch
# or
npm install @filekit-studio/diagram @filekit-studio/sketch
# or
pnpm add @filekit-studio/diagram @filekit-studio/sketch

Required Stylesheet Import

Import the self-contained stylesheet in your root layout (app/layout.tsx or pages/_app.tsx):

import '@filekit-studio/diagram/styles.css'
// or: import '@filekit-studio/sketch/styles.css'

Zero CSS Leaks: All styles are strictly scoped under .fk-sketch-root. Importing this stylesheet will never conflict with your app's global CSS, fonts, or Tailwind config.

Quickstart

1. Declarative <Diagram /> Component

'use client'

import React from 'react'
import { Diagram, type DiagramData } from '@filekit-studio/diagram'
import '@filekit-studio/diagram/styles.css'

const architecture: DiagramData = {
  title: 'Cloud Payment Pipeline',
  direction: 'LR',
  nodes: [
    {
      id: 'client',
      label: 'Client Browser\n(React / Next.js)',
      shape: 'rectangle',
      color: 'indigo',
      badge: 'FRONTEND',
    },
    {
      id: 'gateway',
      label: 'API Gateway',
      description: 'Kong / Cloudflare',
      shape: 'rounded',
      color: 'blue',
    },
    {
      id: 'auth',
      label: 'Auth Service',
      description: 'JWT / OAuth2',
      shape: 'diamond',
      color: 'amber',
    },
    {
      id: 'db',
      label: 'Primary Database\n(PostgreSQL)',
      shape: 'cylinder',
      color: 'emerald',
      badge: 'STORAGE',
    },
  ],
  edges: [
    { from: 'client', to: 'gateway', label: 'HTTPS POST' },
    { from: 'gateway', to: 'auth', label: 'Verify Token' },
    { from: 'auth', to: 'db', label: 'SQL Query' },
  ],
  groups: [
    {
      id: 'backend',
      label: 'Internal VPC Cluster',
      nodeIds: ['gateway', 'auth', 'db'],
      color: 'indigo',
    },
  ],
}

export default function ArchitectureDoc() {
  return (
    <div className="w-full h-[500px] rounded-xl overflow-hidden border">
      {/* Automatically inherits dark/light mode and sets contrast */}
      <Diagram
        data={architecture}
        mode="viewer"
        autoFit={true}
        showCopyButton={true}
        copyFormat="elements" // 'elements' for 1-click Ctrl+V paste into Whiteboard, 'image' for PNG, or 'json'
        showZoomControls={true}
      />
    </div>
  )
}

2. Programmatic Compilation (diagramToSketch)

If you want to compile graph JSON into a SketchDocument to save, mutate, or export:

import { diagramToSketch } from '@filekit-studio/diagram'

const sketchDoc = diagramToSketch(architecture, {
  direction: 'LR',
  nodeSpacing: 80,
  rankSpacing: 220,
})

console.log(sketchDoc.elements) // Array of SketchBoardElement objects

3. Rendering Excalidraw JSON Files

import { Diagram } from '@filekit-studio/diagram'
import excalidrawFile from './diagram.excalidraw.json'

export function ExcalidrawViewer() {
  return (
    <div className="w-full h-[600px]">
      <Diagram data={excalidrawFile} mode="viewer" autoFit={true} />
    </div>
  )
}

<Diagram /> Props Reference

| Prop | Type | Default | Description | | :--- | :--- | :--- | :--- | | data | DiagramData \| string | required | Diagram specification object or JSON string. | | mode | 'viewer' \| 'editor' | 'viewer' | Display mode: clean doc viewer or full whiteboard studio. | | direction | 'TB' \| 'BT' \| 'LR' \| 'RL' | 'LR' | Flow direction for the DAG auto-layout engine. | | theme | 'light' \| 'dark' \| 'system' | 'system' | Color theme mode. Automatically detects active website dark mode. | | canvasBackground | string | '#f0f4f8' | Hex background color override (#121214 in dark mode). | | gridStyle | 'grid' \| 'dots' \| 'cross' \| 'none' | 'dots' | Canvas grid pattern. | | autoFit | boolean | true | Scale and center elements to fit container on mount. | | interactive | boolean | true | Allow click-and-drag panning and wheel zooming. | | showCopyButton | boolean | true | Display 1-click clipboard export button. | | copyFormat | 'elements' \| 'image' \| 'json' | 'elements' | 'elements' for Ctrl+V paste into Sketch whiteboard, 'image' for PNG, or 'json'. | | showZoomControls | boolean | true | Display minimal floating zoom percentage and +/-/Fit controls. | | layoutOptions | DiagramLayoutOptions | {} | Fine-tuning for spacing (nodeSpacing, rankSpacing), margins, and padding. | | uiConfig | SketchUIConfig | {} | Granular toggle flags for all 54 UI controls and menus (editor mode). | | controllerRef | Ref<SketchController> | undefined | Ref to imperative controller methods (zoomToFit, zoomIn, zoomOut, etc.). |

License

MIT © FileKit Studio