API reference
relvista is three npm packages. Most sites only need the Docusaurus plugin; the other two are for building your own tools on the same parser, layout and renderer the editor uses.
| Package | Use it to | Runs in |
|---|---|---|
@relvista/docusaurus-plugin | draw DBML diagrams in a Docusaurus site | Docusaurus 3.6+ (build, SSR) |
@relvista/core | parse DBML, read and write layout files, auto-layout, search, diff | Node 20+ and browsers |
@relvista/renderer | draw diagrams in React (static SVG, viewer, editable canvas), export, share | browsers (SVG also in Node) |
All three are ES modules with TypeScript types; there is no CommonJS build.
@relvista/docusaurus-plugin
Register it in docusaurus.config and set site-wide diagram defaults in themeConfig.dbml; pages
then use ```dbml code fences or <DbmlDiagram>. See Getting started and
Usage for the page-level syntax.
// docusaurus.config.ts
export default {
plugins: ['@relvista/docusaurus-plugin'],
themeConfig: { dbml: { height: 560, detailLevel: 'keys' } },
};
Reference: plugin options, themeConfig.dbml and its defaults, the fence meta parser.
@relvista/core
No DOM and no React: it runs in Node, in browsers and in Web Workers, and everything it returns is plain JSON-serialisable data.
import { compileDbml, layoutDiagram, parseLayout } from '@relvista/core';
const { model, diagnostics } = compileDbml(dbmlText);
const geometry = model && (await layoutDiagram(model));
The main entry points:
- compileDbml: DBML (one file or a
useproject) to a DiagramModel and diagnostics; never throws. - parseLayout /
serializeLayout: the
layout file (
schema.dbml.layout.json), validated against its JSON Schema (also exported as@relvista/core/layout.schema.json). - layoutDiagram (ELK, async) and layoutDiagramSync (dagre): auto-layout to a DiagramGeometry, keeping saved positions.
- selectView: the part of a model one
DiagramViewshows. - searchModel and diffModels: search tables, columns and more; compare two schemas.
Everything else: all of @relvista/core.
@relvista/renderer
React components and browser helpers. Import its stylesheet once (it includes React Flow's).
import { DbmlViewer } from '@relvista/renderer';
import '@relvista/renderer/styles.css';
<DbmlViewer source={dbmlText} title="Shop" height={520} />;
- DbmlViewer: the read-only viewer the docs use (toolbar, search, export); props.
- DiagramCanvas: the interactive canvas the editor uses, read-only or editable with a controlled layout; props and handle.
- DiagramSvg: a static, SSR-safe SVG of a model and its geometry; renderDiagramSvgString gives the same picture as a standalone SVG file (Node too).
- exportPng, exportPdf (multi-page, tiled) and printDiagram.
- encodeShareHash / decodeShareHash (share links) and parseDiagramTarget / formatDiagramTarget (deep links to a view, table or viewport).
Everything else: all of @relvista/renderer.
Stability in 1.x
From 1.0 the packages follow semantic versioning:
- Public API. Everything listed in this reference keeps working within 1.x: no export is
removed or renamed and no signature changes incompatibly before 2.0. New exports, options and
props are added in minor releases. Anything not in the reference (deep imports into
dist/, members marked internal, CSS class names other than the documented--rv-*variables) can change in any release. - Layout file. The
layout-1format (layout file, JSON Schema) is stable: every 1.x version reads every layout-1 file and writes files that earlier 1.x versions read. A format that needs incompatible changes gets a new schema (layout-2) and a migration, not a silent change. - DBML. relvista does not parse DBML itself: it delegates to
@dbml/parse, Holistics' parser, pinned to an exact
version. A file valid on dbdiagram.io opens unchanged and saves back byte for byte unless you
edit it. Moving to a newer
@dbml/parseis a deliberate release with its own changelog entry, never a silent range update. - Pictures. Layout and drawing details (exact positions chosen by auto-layout, ref routes, spacing, colours) can improve in minor releases. Saved positions in a layout file always win.
Generated reference
The API reference is generated from the TSDoc comments in the source on every
docs build, so it always matches the code on main.