@hachiware-labs/finch-js

v0.9.0

Published

9 days ago

Fast, beautiful, editable diagrams from concise text.

0High
0Medium
0Low

hachiware-labs

diagram svg dsl sequence-diagram deployment-diagram

Finch.js

Draw beautiful diagrams.

日本語

Draw diagrams from text, then keep your hand-tuned layout as the text changes. Finch.js renders editable SVG diagrams and preserves positions through stable node IDs.

What's new in 0.9.0

Automatic layout gives grouped diagrams clearer connection order, room for independent routes, and labels that are easier to associate with their lines. The Finch skill helps choose the diagram type, nodes, and meaningful groups from your explanation; the built-in editor lets you refine the result.

Release notes and upgrade guidance

Quick start

No install, no build. Save as diagram.html and open it.

<!doctype html>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<style>
  body { margin: 0; }
  #diagram { min-height: 100vh; overflow: auto; padding: 24px; }
</style>

<main id="diagram" aria-label="Application deployment diagram"></main>

<script src="https://cdn.jsdelivr.net/npm/@hachiware-labs/[email protected]/dist/finch.global.js"></script>
<script>
  const deploymentSource = `
@deployment
node browser "Web app" [icon=app-window]
container cloud "Production" [layout=row tone=cyan] {
  server api "API server" [icon=server]
  database db "PostgreSQL" [icon=database]
}
browser -> api
api -> db: SQL
  `.trim();

  Finch.render(deploymentSource, { target: "#diagram" });
</script>

IDs and labels are separate. Keep api stable while changing "API server"; the saved position belongs to the ID.

Click Finch to edit

Click the pink Finch button in the lower-left of the diagram to open the editor. Add elements and connections in Source, then drag and drop nodes to arrange the diagram.

Edit the source again — the nodes you moved stay where you put them. Keep their IDs unchanged.

The demo adds a Redis cache, connects it to the API server, and moves the nodes into place. Try the editable deployment example. Press Save to save your source and layout together as editable HTML, or follow the 15-minute tutorial.

Tutorial · Example gallery · npm package

Diagram types

| Directive | Use it for | Example | | --- | --- | --- | | @deployment | Systems and infrastructure | Deployment | | @graph | General relationships and grouped systems | Graph | | @sequence | Ordered interactions | Sequence | | @flowchart | Processes and decisions | Flowchart | | @state | Lifecycles and transitions | State | | @er | Entities and relationships | ER | | @component | Software boundaries and interfaces | Component | | @slide | Presentation visuals | Slide | | @class | Classes and UML relationships | Class | | @object | Instances and their values | Objects | | @usecase | Actors and system goals | Use case | | @activity | Actions and control flow | Activity | | @timing | Signals and states over time | Timing |

Install

npm install @hachiware-labs/finch-js

import Finch from "@hachiware-labs/finch-js";

For standalone HTML, load the browser bundle:

<script src="https://cdn.jsdelivr.net/npm/@hachiware-labs/[email protected]/dist/finch.global.js"></script>

Styles

The same flowchart, rendered in different styles.

Compare styles, toggle shadows, and export SVGs. Default, Prism, and Midnight are built-in themes. Business, Precision, and Editorial are custom theme examples defined in that page; “+ shadow” shows a shadow-enabled variant.

Icons, role colors, and your images

Use icon and tone across all themes, including custom themes. Containers pass their tone to descendants; a child can override it or use tone=none to reset. Icon artwork is selected per node and is not inherited.

@deployment
container services "Services" [tone=green] {
  node api "API" [icon=server]
  node auth "Auth" [icon=shield-check tone=coral]
}

Lucide is the default. Optional AWS, Azure, Google Cloud, Kubernetes, and Simple Icons packs use names such as icon=aws:application-auto-scaling and icon=simple:github. Load the required pack after Finch. Use image="./photo.png" for your own image, optionally with imageShape=circle or imageShape=rounded.

For icons and images, open the icon and image example. See the icon guide for a complete HTML example and export requirements, and pack sources for asset versions and terms.

Create diagrams with your coding agent

This repository includes a portable finch skill for coding agents. Ask your agent:

Use the Finch skill to explain the normal order flow and manual-review exception in HTML.
Choose meaningful steps and groups by responsibility, preserving the supplied facts.

Codex discovers the skill automatically from this checkout; use $finch when you want to invoke it explicitly. To install the skill in another workspace or for another supported agent:

npx skills add hachiware-labs/finch-js --skill finch

The installer lets you select the target agent. You can also specify agents directly, for example with --agent claude-code cursor. Add --global to make the skill available across repositories, and restart an agent if a newly installed skill is not listed.

Review the chosen content and the rendered diagram together. Start with automatic layout and allow room for connections before adding position constraints. The skill and runtime are installed separately: updating the skill does not change the library version loaded by existing HTML. See the agent guide.

Save diagrams in Markdown

Use exportMarkdown() and Finch.renderMarkdown() to save and restore a diagram and its node positions in one code fence. See the Markdown guide (Japanese).

Learn more

Tutorial: draw, arrange, edit, save, and choose a type in about 15 minutes.
Reference: syntax, editing controls, persistence, events, export, and the instance API.
Examples: complete, editable diagrams for every supported type.
Extending Finch.js: custom diagrams, shapes, layouts, and themes.
Slide patterns: reusable KPI, data-story, roadmap, comparison, and customer-evidence recipes.
Embedding and saving
Generate a diagram from a prompt
UML examples and extensions
Includes, loops, and functions
Notes and sequence pages
Plugin development guide (Japanese)

Development

npm ci
npm run check

To browse the examples locally, run python -m http.server 8000 and open http://127.0.0.1:8000/examples/.

Images and linked examples use the repository build. Sources and freshness record.

Finch.js is licensed under the MIT License.

Header silhouette adapted from a Green Warbler-Finch photograph by Julien Renoult, licensed under CC BY 4.0.
Footer silhouette adapted from Green warbler-finch on Santa Cruz Island by Andrew Katsis, licensed under CC BY 4.0.

Both images were simplified, recolored, and repositioned as silhouettes.