Skip to content

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:

npm --prefix frontend ci

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_USE_MOCK_API=true npm --prefix frontend run dev

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

just run-desktop

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 gofmt and keep go test green.
  • 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).