Repository navigation
Developer Setup
This page explains how to set up a development copy of FlowMotion, build it, and install it in a test vault.
-
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.
| 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.
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.
| 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.
- Run
npm run build. - Run
npm run install-plugin -- "/path/to/test-vault". - In Obsidian, open Settings, then Community plugins, and turn on FlowMotion.
- 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.
-
npm run typecheckpasses. -
npm testpasses. -
npm run buildfinishes without errors. - If you changed the schema, run
npm run schemaand commit the regenerated JSON files. - If you changed the output of the renderer, run
npm run examplesand check the files inout/. -
npm run lintpasses. - For plugin UI or persistence changes,
npm run test:e2epasses.
© 2026 @vrsarin. FlowMotion documentation.