Skip to main content

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.

PackageUse it toRuns in
@relvista/docusaurus-plugindraw DBML diagrams in a Docusaurus siteDocusaurus 3.6+ (build, SSR)
@relvista/coreparse DBML, read and write layout files, auto-layout, search, diffNode 20+ and browsers
@relvista/rendererdraw diagrams in React (static SVG, viewer, editable canvas), export, sharebrowsers (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:

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} />;

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-1 format (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/parse is 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.