What's Changed
Major internal rewrite. Most changes are under the hood but have an impact on resource usage (#59).
- Much lower RAM usage: Previously all API responses were pre-computed and held in memory, and cover images were all buffered during the library build. Now library data lives in SQLite, statistics are computed per request, and covers are written to disk one at a time during ingest.
- Support for persistent data dir: Extracted cover images and data can now be stored in a persisted directory making startup much faster.
- Incremental updates: File changes are now detected by fingerprint and only affected items are re-processed, instead of rebuilding the entire library.
- Config file support: Settings can now be provided via
koshelf.toml(seekoshelf.example.toml). CLI flags still override. - New reading API: All reading data moves to
/api/reading/*with query parameters for scope, date range, and timezone. - Added jemalloc allocator on non-Windows platforms
Security
- Fixed potential path traversal in CBR extraction and EPUB path resolution
- Lua metadata parser — disabled all standard libraries and bytecode loading to prevent code execution via malicious sidecar files
- Removed permissive CORS policy (embedded frontend is same-origin)
- Added
X-Content-Type-Options,X-Frame-Options, andReferrer-Policysecurity headers
Updated dependencies
- Tailwind CSS v3 → v4
- react-router v6 → v7, Vite v6 → v8, @vitejs/plugin-react v4 → v6
- rusqlite → sqlx
- Bumped event-calendar, typescript-eslint, vitest, @types/node, and other minor frontend deps
Note
Starting with this release, KoShelf uses calendar versioning (YYYY.M.patch) instead of semantic versioning. This version is 2026.3.0.
Warning
Breaking API changes: /api/activity/* and /api/completions/* have been removed in favor of /api/reading/*. Site capabilities has_activity/has_completions are now a single has_reading_data flag. The response envelope is now { data, meta: { version, generated_at } } across all endpoints. See docs/API.md for the new reference.
Full Changelog: v2.4.1...v2026.3.0