Building from source

Saga-Scribe is written in Svelte 5 and TypeScript (frontend, with CodeMirror 6 as the editor) and Rust (the shorthand compiler, TEI import and everything else on the backend), using Tauri 2.

Prerequisites

You need:

• bun — the package manager and script runner;
• Rust — rustup installs the toolchain pinned in rust-toolchain.toml automatically;
• the system libraries Tauri needs (Tauri prerequisites) and libxml2.

Debian/Ubuntu:

sudo apt install libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf libxml2-dev

macOS:

brew install libxml2
export PKG_CONFIG_PATH="$(brew --prefix libxml2)/lib/pkgconfig"

Windows: libxml2 via vcpkg, as in .github/actions/setup-libxml2-windows.

Build the application

git clone https://github.com/motheatensoul/saga-scribe
cd saga-scribe
bun install
bun run tauri dev      # run the app in development mode
bun run tauri build    # build installers into src-tauri/target/release/bundle/

Always use bun; the project does not use npm.

Tests and checks

Before opening a pull request:

bun run test        # frontend (Vitest) and Rust tests
bun run check:all   # versions, svelte-check and cargo clippy

check:all runs check:versions, svelte-check (which must report 0 warnings) and cargo clippy. CI runs the same checks, plus a security audit of the JavaScript dependencies.

The project has around 200 Rust tests, covering the parser (including differential tests against the original lexer), the compiler, importer round-trips, the normalizer and the dictionary. Frontend tests cover rendered-text parsing, incremental rendering equivalence, XSLT sanitizing, text diffing, and the editor’s highlighting grammar against a shared DSL corpus.

Flatpak

To build the Flatpak, run flatpak/build-flatpak.sh. It compiles the application inside the GNOME SDK rather than on your system, which is necessary for the resulting binary to link the runtime’s libraries. Only the frontend is built outside.

Do not package a binary built on the host or on Ubuntu: it will link that system’s libraries (such as libxml2.so.2, which GNOME runtimes no longer ship).

This documentation site

The website is a separate, fully static Astro project. It contains two applications:

saga-scribe-website/
├── src/            # the marketing site (sagascribe.app)
├── public/
└── docs/           # the Starlight documentation (docs.sagascribe.app)

Both are installed together with one bun install from the repository root.

bun install
bun run dev          # marketing site at http://localhost:4321
bun run dev:docs     # documentation on the next free port (e.g. 4322)
bun run build        # marketing site into dist/
bun run build:docs   # documentation into docs/dist/
bun run build:all    # both

bun run check runs astro check over the marketing site.

Both outputs are static files. Serve dist/ at sagascribe.app and docs/dist/ at docs.sagascribe.app with any static host — Caddy, nginx, Cloudflare Pages, Netlify or GitHub Pages. No Node.js server is needed.

Conventions

The project’s conventions are collected in AGENTS.md, for human contributors as much as for AI agents: code style, accessibility, the asynchronous patterns that keep large manuscripts responsive, the round-trip guarantees, and how releases and versions work. The look of the interface is described in docs/UI_STANDARDS.md.

Contributions are welcome. Read CONTRIBUTING.md and the Code of Conduct first.