Skip to content

Developer Setup

Vivek Sarin edited this page Nov 17, 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 and fetching the draw.io editor source.
  • zip, for packaging optional add-ons.
  • 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.52.2 The code editor for .flow files and the edit window
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; fetching draw.io and packaging add-ons are optional for ordinary plugin development.

Command What it does
npm ci Installs dependencies from the lockfile
npm run fetch-drawio Copies the draw.io editor into dist/plugin/drawio. Needs Git and network access, once. Use npm run fetch-drawio -- --update to refresh it
npm run build Runs build-schema, build, and build-monaco
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
npm run addons Packages draw.io and Monaco into dist/addons/flowmotion-addons.zip; requires both built add-ons
make release-build Installs locked dependencies, fetches draw.io, builds, and packages add-ons
make release-check TAG=0.1.0 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 plugin, as CommonJS for the browser target. Obsidian and Electron are external
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
dist/plugin/monaco.js build-monaco.mjs The Monaco editor with embedded CSS, loaded only while an editor is open
dist/plugin/drawio/ fetch-drawio.mjs The draw.io editor (Apache-2.0, from jgraph/drawio), with only the files the embedded editor loads
dist/addons/flowmotion-addons.zip package-addons.mjs Optional draw.io and code-editor files for release downloads

The source of the draw.io editor is the clone in .cache/drawio. Keep the cache. Running the fetch again without --update reuses it.

npm run build does not clean dist/plugin; an earlier draw.io fetch can leave files there. The install script copies that directory, including any add-ons present. Both add-on toggles still default to off.

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 Code editor or draw.io editor in FlowMotion settings when testing those add-ons. Fetch draw.io before installation if you need its full editor.

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