Lumotia/docs/architecture-map/05-core-storage-hotkey-build/dev-launcher-and-scripts.md

name, type, slice, last_verified

name	type	slice	last_verified
Dev launcher and scripts	architecture-map-page	05-core-storage-hotkey-build	2026/05/09

Dev launcher and scripts

Where you are: Architecture map → Core, Storage, Hotkey, Build → Dev launcher and scripts

Plain English summary. Two ways to start Magnotia in development. run.sh is the bespoke launcher that starts Vite first and then Tauri (avoiding a Tauri-spawned-second-Vite mess). The package.json scripts are the canonical npm-run interface — the same scripts CI uses for the frontend gate.

At a glance

• Files: run.sh (636 bytes, +x), package.json (1,211 bytes), package-lock.json (109 KB).
• External tools: npm, npx, curl, bash (run.sh); the Node toolchain (package.json scripts).
• Consumers: run.sh is invoked by Jake on his Monolith. The package.json scripts are invoked by both CI (npm run build) and developers (npm run dev).

run.sh — the local launcher

#!/usr/bin/env bash
# Magnotia dev launcher. Starts Vite first, waits for it to bind port 1420,
# then runs Tauri without triggering a second Vite instance.
# For performance testing use: npm run tauri build
set -euo pipefail
cd "$(dirname "$0")"

export LIBCLANG_PATH=/usr/lib64/llvm21/lib64

printf 'Starting Vite dev server...\n' >&2
npm run dev:frontend &
VITE_PID=$!

until curl -sf http://localhost:1420 > /dev/null 2>&1; do sleep 0.5; done
printf 'Vite ready. Launching Tauri...\n' >&2

cleanup() {
    kill "$VITE_PID" 2>/dev/null || true
}
trap cleanup EXIT INT TERM

npx tauri dev --config '{"build":{"beforeDevCommand":""}}'

Why this exists

The default npm run tauri dev invokes tauri dev, which honours beforeDevCommand from tauri.conf.json and spawns its own Vite. If Vite is already running (eg during interactive iteration), you get two instances racing for port 1420. The launcher solves it by starting Vite explicitly and disabling Tauri's spawn via --config '{"build":{"beforeDevCommand":""}}'.

Steps

1. set -euo pipefail — early exit on any command failure or unset variable.
2. cd "$(dirname "$0")" — anchor to the repo root.
3. Hard-codes LIBCLANG_PATH=/usr/lib64/llvm21/lib64 — Fedora 41 default LLVM 21 path. Breaks on Debian / Ubuntu / macOS. Worth softening to LIBCLANG_PATH=${LIBCLANG_PATH:-/usr/lib64/llvm21/lib64} so a developer-set value wins.
4. Spawn npm run dev:frontend &; capture PID in VITE_PID.
5. Poll curl -sf http://localhost:1420 every 500 ms until 200 OK.
6. Trap EXIT INT TERM to kill the Vite process group on script exit.
7. npx tauri dev with beforeDevCommand disabled.

LIBCLANG_PATH rationale

Bindgen (pulled by whisper-rs-sys and llama-cpp-sys-2) needs a libclang.so at build time. On Fedora's LLVM 21 packaging, the canonical location is /usr/lib64/llvm21/lib64. On Debian-family the path is /usr/lib/llvm-N/lib; on macOS Homebrew it's $(brew --prefix llvm)/lib. The hard-coded value means a clean git clone on a non-Fedora machine fails the first build until the developer sets LIBCLANG_PATH themselves.

package.json — npm scripts and deps

Scripts

"scripts": {
  "dev": "npm run dev:frontend",
  "dev:frontend": "svelte-kit sync && vite dev",
  "build": "vite build",
  "preview": "vite preview",
  "check": "svelte-kit sync && svelte-check --tsconfig ./jsconfig.json",
  "check:watch": "svelte-kit sync && svelte-check --tsconfig ./jsconfig.json --watch",
  "tauri": "tauri"
}

• npm run dev — frontend only (no Tauri). Useful for pure-UI iteration.
• npm run build — Vite production build. CI gate.
• npm run check — svelte-check against jsconfig.json. CI gate.
• npm run tauri — passthrough. npm run tauri dev, npm run tauri build, etc.

Runtime dependencies

• @tauri-apps/api 2.10.1 — JS bridge to Tauri commands.
• @tauri-apps/plugin-autostart 2.5.1 — autostart on boot.
• @tauri-apps/plugin-dialog 2.7.1 — native file dialogs.
• @tauri-apps/plugin-global-shortcut 2.3.1 — non-Linux hotkey backend (Linux uses our own magnotia-hotkey crate, slice 5).
• @tauri-apps/plugin-notification 2.3.3 — toast notifications.
• @tauri-apps/plugin-opener 2.x — open external URLs.
• @chenglou/pretext 0.0.5 — stylable text preview.
• lucide-svelte 0.577.0 — icon set.
• svelte-i18n 4.0.1 — i18n.

Dev dependencies

• @sveltejs/kit 2.58.0 + @sveltejs/adapter-static 3.0.10 + @sveltejs/vite-plugin-svelte 5.0.0.
• @tailwindcss/vite 4.2.1 + tailwindcss 4.2.1 (Tailwind v4, Vite-plugin-driven, no PostCSS config).
• @tauri-apps/cli 2.x.
• svelte 5.0.0, svelte-check 4.0.0, typescript 5.6.2, vite 6.4.2.

Watch-outs

• run.sh LIBCLANG_PATH is Fedora-specific. A new developer on Ubuntu / macOS hits a build failure on first run and has to either edit run.sh or pre-set the env var. Worth the conditional default.
• No dev:fullstack script. The Tauri dev path goes through npx tauri dev (or run.sh), not through an npm script. A npm run dev:fullstack shortcut would make discovery easier.
• Tailwind v4 is in flight. Major version, no PostCSS config. Cross-link to slice 1 for the consumed surface.
• @tauri-apps/api is pinned to 2.10.1 (no caret). Intentional because Tauri's JS bridge can shift behaviour subtly between minors. Pinned ensures we test what we ship.
• Plugin versions are caret-ranged. Compatible-change updates land transparently. npm audit (CI) catches advisories.

See also

• Workspace Cargo.toml
• Frontend build config (vite.config, svelte.config, jsconfig)
• CI pipeline — invokes npm run build and svelte-check.
• Slice 1 frontend — consumer of every @tauri-apps/* runtime dep.