Native iOS client for Librarium, a self-hosted, privacy-focused tracker for your physical book, manga, and comic collection. A self-hosted alternative to Libib and similar cloud catalog services. Free and AGPL 3.0; there is no paid tier. iOS Lite is next up.
Swift · SwiftUI · iOS 26+. Talks to librarium-api over HTTP.
⚠︎ Early beta. Things are changing fast, some edges are rough, and self-hosters should expect to read release notes before upgrading.
Part of the Librarium stack:
| Repo | Role |
|---|---|
librarium |
Marketing site at librarium.press, planning docs |
librarium-api |
Backend · Go · Postgres · River jobs |
librarium-web |
Web client · React · TypeScript · Tailwind · Vite |
librarium-ios ← you are here |
Native iOS client · SwiftUI · iOS 26+ (TestFlight) |
librarium-mcp |
MCP server · Go · chat with your library from Claude / Cursor / etc. |
| Tool | Minimum version |
|---|---|
| Xcode | 16.0 |
| iOS deployment target | 26.0 |
| macOS (for development) | 15.0 (Sequoia) |
| Apple Developer account | Required to run on a physical device |
- Browse and search your Librarium libraries across multiple servers
- View book details, editions, and series
- Track reading status, ratings, and notes per edition
- Manage loans and shelves
- Barcode scanner for quick ISBN lookup and library matching
- Multi-server / multi-account support
- Offline mode with per-library caching
- Dark mode
The iOS app is in public beta on TestFlight. To try it without building from source:
- Install TestFlight from the App Store (if you don't already have it).
- Open the invite link on your iPhone: testflight.apple.com/join/dA3sMnqR.
- Tap Accept, then Install — the app appears on your home screen.
You'll still need a running librarium-api instance to point it at.
Beta builds expire 90 days after upload; TestFlight will prompt you to update when a newer build is available.
git clone https://github.com/fireball1725/librarium-ios.git
cd librarium-iosOpen Librarium.xcodeproj in Xcode (at the repo root — no nested folders).
- Scheme: Librarium
- Destination: any iOS 26+ simulator or a connected device
Press ⌘R or choose Product → Run.
You will be prompted to enter a server URL on first launch. Point it at a running librarium-api instance.
Librarium.xcodeproj # Xcode project
Librarium/ # All app source
├── LibrariumApp.swift # App entry point
├── AppState.swift # Top-level observable state (accounts, auth)
├── ContentView.swift # Root navigation view
├── Models/ # Codable structs mirroring API responses
├── Services/ # API client, auth, offline store, keychain
└── Views/
├── Admin/ # Admin and settings screens
├── Books/ # Book list, detail, barcode scanner, bulk edit
├── Components/ # Reusable UI components (TagPill, EmptyState…)
├── Loans/ # Loan management
├── Members/ # Library member views
├── Series/ # Series browsing and detail
└── Shelves/ # Shelf views
Format: YY.MM.revision (e.g. 26.4.0).
YY— two-digit release year.MM— release month, not zero-padded (26.4, not26.04).revision— feature counter within the month, starting at0. Resets to0when the month rolls over.-devsuffix — local/Debug builds only. Release builds drop the suffix since the App Store requires strictly numericMARKETING_VERSION.
Release history is generated from tags — see GitHub Releases.
Run via Xcode. Debug builds use an orange app icon and display as Librarium Dev on the home screen so they're visually distinct from TestFlight builds. Debug MARKETING_VERSION carries the -dev suffix (e.g. 26.4.1-dev); Release strips it (26.4.0) since the App Store rejects non-numeric version components.
Tagging a release (via the Release workflow, below) pushes a v<version> tag which in turn triggers the TestFlight workflow. That workflow archives, signs, and uploads to TestFlight. The build number is today's UTC date in DDMMYY form (e.g. 26.4.1 (190426) = version 26.4.1 built on 19 Apr 2026), making every build self-dating.
The release GitHub Actions workflow (workflow_dispatch) computes the next YY.MM.revision from the latest tag, updates MARKETING_VERSION for both Debug and Release configs, commits release: <version>, tags v<version>, then bumps Debug back to the next -dev revision. TestFlight upload is handled separately by the existing testflight.yml workflow.
Required repository secrets:
| Secret | Description |
|---|---|
CERTIFICATE_BASE64 |
Apple Distribution certificate exported as a base64-encoded .p12 |
CERTIFICATE_PASSWORD |
Password for the .p12 |
KEYCHAIN_PASSWORD |
Any string — used to lock the temporary CI keychain |
ASC_KEY_ID |
App Store Connect API key ID |
ASC_ISSUER_ID |
App Store Connect API issuer ID |
ASC_PRIVATE_KEY |
Contents of the .p8 private key file |
To regenerate the app icons (production navy and debug orange):
bash generate-icon.shOutputs AppIcon-1024.png, AppIcon-Debug-1024.png, and AppIcon-transparent.png (for web/marketing use) into the repo root.
The app connects to a self-hosted librarium-api server. No cloud service is required. Server URLs and credentials are stored in the iOS Keychain. Multiple servers can be added and all their libraries are shown together.
See CONTRIBUTING.md. PRs must sign off on the Developer Certificate of Origin (git commit -s) — a CI check enforces this.
Questions, updates, and works in progress: FireBall Codes on Discord.
If this saved you some time, you can buy me a sushi roll.
AGPL-3.0-only. See LICENSE for the full text.
Created and maintained by FireBall1725 in Ontario, Canada. More projects and writing there, including why Librarium exists.
Patches welcome; see CONTRIBUTING.md. Everyone who has landed code is on the contributors list.