Skip to content

Developer Setup

Vivek Sarin edited this page Nov 18, 2026 · 4 revisions

Setup and build

This page explains how to set up a development copy of FlowMotion, build it, and install it in a test vault.

Requirements

  • Node.js, a current Node 22 or 24 release, with npm. CI uses both lines. The locked WebdriverIO tools require at least 22.23.4 on Node 22 or 24.22.1 on Node 24.
  • Git, for cloning the repository.
  • Obsidian, version 1.4.0 or later, with a test vault. Do not test in your main vault.

Dependencies

Package Version Used for
elkjs ^0.12.1 Graph layout (runs in the same thread, no web worker)
yaml ^2.5.0 Parsing YAML definitions
esbuild ^0.28.2 Bundling the plugin, the runtime, and the schema
monaco-editor ^0.57.0 The code editor for .flow files and the edit window. Bundled into main.js
obsidian latest Type definitions for the Obsidian API
typescript ^5.8.3 Type checking
vitest ^5.1.0 Unit tests
tsx ^4.19.0 Running TypeScript scripts (examples, export)
@wdio/cli, @wdio/local-runner, @wdio/mocha-framework, @wdio/spec-reporter ^10.2.0 End-to-end test runner
wdio-obsidian-service, wdio-obsidian-reporter ^3.5.0 Running and reporting tests inside Obsidian

The table lists dependency ranges from package.json; package-lock.json records installed versions. The obsidian range is latest, so dependency updates can introduce new API types.

Commands

Run commands from the repository root. Start with npm ci.

Command What it does
npm ci Installs dependencies from the lockfile
npm run build Runs build-schema and build
npm test Runs unit tests (vitest run)
npm run lint Runs ESLint with the Obsidian plugin rules
npm run test:e2e or make test-e2e Builds the plugin and runs the Obsidian desktop E2E matrix
npm run typecheck Runs tsc --noEmit
npm run examples Writes the example exports to out/
npm run install-plugin -- "<vault path>" Copies dist/plugin into <vault>/.obsidian/plugins/flowmotion
make release-build Installs locked dependencies and builds
make release-check TAG=1.0.2 Checks the chosen tag, manifest, version map, and release files

The quotation marks around the vault path are required when the path contains spaces.

What the build produces

Output Made by Contents
schema/diagram.schema.json build-schema.mjs The JSON Schema for YAML diagrams
schema/storyboard.schema.json build-schema.mjs The JSON Schema for storyboards
dist/plugin/main.js build.mjs The CommonJS plugin. Obsidian supplies the CodeMirror state and view packages at runtime
dist/flowmotion-runtime.js build.mjs The runtime as an IIFE, with the global name FlowMotion. It exports mountModel
dist/plugin/manifest.json, styles.css build.mjs Copied from the repository root

The build appends Monaco's CSS to styles.css and inlines its font. The plugin downloads the Monaco and draw.io runtimes only when enabled.

Installing into a test vault

  1. Run npm run build.
  2. Run npm run install-plugin -- "/path/to/test-vault".
  3. In Obsidian, open Settings, then Community plugins, and turn on FlowMotion.
  4. After each change, run the build and the install again, then check the change in the test vault.

Turn on Rich Code Editor (Monaco) or draw.io editor in FlowMotion settings to download the add-on into the test vault.

Before you open a pull request

  1. npm run typecheck passes.
  2. npm test passes.
  3. npm run build finishes without errors.
  4. If you changed the schema, run npm run schema and commit the regenerated JSON files.
  5. If you changed the output of the renderer, run npm run examples and check the files in out/.
  6. npm run lint passes.
  7. For plugin UI or persistence changes, npm run test:e2e passes.

Related pages

Clone this wiki locally