Local Development Setup¶
Use this page to build, test, and run PlainShelf from source. For release installation, see Installation.
Prerequisites¶
| Tool | Version | Purpose |
|---|---|---|
| Go | 1.27.4 or newer | server, core library, desktop backend |
| Node.js | 22.18+ or 24.11+, below 26 | frontend and end-to-end tests |
| npm | bundled with Node.js | JavaScript dependencies |
| just | recent | repository task runner |
| zsh | recent | shell used by the justfile |
The floor comes from Babel 8, which the mutation-testing dev dependency pulls
in. Its engines field accepts Node.js 22 from 22.18 and Node.js 24 from 24.11,
so Node.js 23 and early 24 releases are out too; outside that range npm ci
warns, and fails outright where npm engine enforcement is on.
Node.js has a ceiling as well as a floor. From Node.js 26 the runtime defines
its own experimental localStorage global, which leaves window.localStorage
undefined inside Vitest's jsdom environment; unit-test files then fail on
import with Cannot read properties of undefined (reading 'getItem'). The unit
suite passes on Node.js 22, which CI runs, and on 24, which the Docker image
builds the frontend with; it fails on 26. Node.js 25 has not been tried.
The desktop app and the standalone reader are both built with Wails v3, which
links GTK 4 and WebKitGTK 6.0 through cgo on Linux whenever the desktop or
reader module compiles, so even their go test and golangci-lint need them
there (libgtk-4-dev and
libwebkitgtk-6.0-dev on Ubuntu 24.04); see the
Wails v3 installation guide.
Android development has additional prerequisites.
Install dependencies¶
From the repository root:
The end-to-end package installs its own dependencies when just test-e2e runs.
Frontend-only development¶
Use mock data when backend behavior is not needed:
Vite serves the UI at http://localhost:5173.
Run the local server¶
The Go server embeds the built frontend, so build it first:
just build-server-frontend
mkdir -p workspace
cp cmd/plainshelf-srv/conf/config.yaml workspace/config.yaml
cd workspace
go run ../cmd/plainshelf-srv/main.go -conf config.yaml
Open http://127.0.0.1:20000. The sample config stores data below the current working directory and protects mutating API requests with an ephemeral local token injected into the served frontend.
just build-server-backend builds the same server as a versioned
plainshelf-srv binary in the repository root instead of running it.
Run the browser-only demo¶
just run-wasm-demo builds the demo, the frontend plus
the server compiled to WebAssembly, with just build-wasm-demo into
workspace/wasm-demo and serves it on port 5180. just test-wasm-demo runs
the smoke test CI gates it with. cmd/plainshelf-wasm/README.md covers the
build.
Run checks¶
| Scope | Command |
|---|---|
| Frontend unit tests | npm --prefix frontend test |
| Frontend type-check and build | npm --prefix frontend run build |
| Go tests for the server, desktop and reader | just test-go |
| Go lint for the same three modules | golangci-lint run, (cd desktop && golangci-lint run), (cd reader && golangci-lint run) |
| End-to-end tests | just test-e2e |
Run the narrowest relevant check while iterating, then run the full check for every area changed before opening a pull request.
Continuous integration adds three frontend gates to that list:
npm --prefix frontend run check-boundaries,
npm --prefix frontend run check-exports, and
npm --prefix frontend run check-licenses. The export check fails on an export
in frontend/src that no other non-test file reads, so a module's exports stay
its interface rather than a list of internals. Drop the export when nothing
needs it; when a unit test is the only reader and the seam is worth keeping,
record it in the allowlist at the top of frontend/scripts/check-exports.mjs.
Every frontend build, the Wasm demo's included, also emits
licenses/third-party.txt into its output directory with
rollup-plugin-license: the license text of every npm package the bundle
actually contains, linked from Settings → System → About. It does not see inlined icons,
fonts, Android native libraries or data a package licenses separately from its
code, so those keep hand-maintained notices in frontend/public/licenses/.
The Go shelf is the only reader of the book package format, the Android app's
pCloud shelf included, and shelf/testdata/conformance/ pins what it reads. A
change to how a shelf is read belongs in that dataset; the dataset's own README
explains the contract.
Mutation testing is available for the reader's helpers and the shared Markdown modules as an on-demand check of how much the unit tests actually verify. It is not part of the checks above.
Dependency vulnerability scanning is CI-only and not in the table either.
govulncheck ./... runs in each of the three Go modules under both GOOS=linux
and GOOS=darwin, and gates the merge. The desktop and reader darwin scans run on
macOS runners, because Wails v3 cannot load for darwin without cgo; npm advisories come from GitHub's
Dependabot alerts instead of a CI job. To reproduce a govulncheck failure
locally, install it with a Go at least as new as the one go.mod targets — built by an older Go it
fails while loading packages, with requires newer Go version, before it scans
anything. SECURITY.md explains why npm has no CI scan.
Versioning¶
Git release tags are the source of truth for the PlainShelf product version.
Tags must use vMAJOR.MINOR.PATCH with an optional SemVer prerelease suffix,
such as v0.8.0 or v0.8.0-beta.1. Build scripts derive development versions
from the latest release tag, the number of subsequent commits, and the current
commit hash. Tags are created by the release workflows; see
Releasing.
The server and the Settings About section expose the full build version. A
macOS bundle uses the numeric MAJOR.MINOR.PATCH core required by the platform,
so a v0.8.0-beta.1 build reports 0.8.0 in its bundle metadata while retaining
the full prerelease version in the app. The private frontend and end-to-end npm
packages stay at 0.0.0; their package metadata is not a product version.
The Homebrew casks record the latest stable release. Publishing one opens a PR
that runs scripts/update-cask.sh <tag> against its assets (see
Releasing). That single step pins both plainshelf.rb and
bookpkg-reader.rb from the same tag, so the desktop cask and the reader cask it
depends on stay in sync.
Desktop app¶
The desktop app's read action opens the standalone reader in its own
window (it shells out to it). On macOS, to test against the reader you are developing rather
than the brew-installed one, build it first with just build-reader; just
run-desktop then auto-detects reader/build/bin/PlainShelfReader.app and opens
reads with it. Override the target explicitly with just run-desktop
/path/to/PlainShelfReader.app, or by exporting PLAINSHELF_READER_APP (a .app
path/name is launched via open -a); an already-set PLAINSHELF_READER_APP takes
precedence. Because the dev and brew readers share a bundle id, keep only the one
you want registered with LaunchServices if open -a activates the wrong copy.
On Windows and Linux the read action starts the reader executable directly,
without waiting for it to exit. It uses PLAINSHELF_READER_APP when set (the
executable's path), otherwise a PlainShelfReader executable next to the
desktop executable, otherwise PlainShelfReader on PATH. Build one with
(cd reader && go build -o PlainShelfReader .) (PlainShelfReader.exe on
Windows). Without one, reading falls back to the in-app reader with a message.
Run the standalone reader on its own with just run-reader, or
just run-reader path/to/book.bookpkg to open a book straight away.
just run-desktop is a plain go run .: Wails v3 has no zero-config wails
dev, so a frontend change needs npm --prefix frontend run build and a
restart. Create a release-style desktop build with just build-desktop, which
runs go tool wails3 task package:darwin from desktop/Taskfile.yml;
just package-desktop-mac then zips that app the way the Homebrew cask expects.
The standalone reader accepts -book, -shelf, and -section using Go's flag
syntax. String flags consume the next argument as their value, even if it begins
with -. Parsing errors stop startup before the window opens. Omit -section or
use a negative value to resume saved progress; -section 0 opens the first section.
Only one reader process runs at a time. A second launch, such as the desktop's
open -n read action, forwards its arguments to the running reader and exits;
the running reader parses them with the same flags, checks that -book names a
folder containing book.json, and opens it in a new window. A book that is
already open focuses its window instead, and a window still waiting for a book
takes the new one. A forwarded path that is not a book package shows an error
and leaves every open window as it was. Closing a window saves that book's
progress and closes only that book; closing the last window quits the reader.
Android app¶
The Android client is experimental and reuses the Vue frontend through Capacitor. It reads from a PlainShelf server or straight from a shelf folder on pCloud. See Android Development for connection modes, setup, and device networking.
Docker image¶
See Docker to build and run the repository's container image.
Code style¶
- Format Go with
gofmtand keepgo testgreen. - Validate Vue and TypeScript with the frontend build.
- Add or update tests when behavior changes.
- Keep user-facing behavior in
docs/; release notes come from pull request titles and labels (see Releasing).