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.
  • 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=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, with Monaco (about 6 MB in total). Obsidian, Electron, CodeMirror and the Node modules 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

Monaco's CSS is compiled into main.js by an esbuild plugin in build.mjs and its font is inlined. draw.io is not built: the plugin downloads it at runtime.

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 them. Turning on draw.io downloads it 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