reader/docs/development.en.md

Development

Project home · Documentation · 简体中文

Requirements

• Node.js 24 is recommended to match the current container and CI. The server uses built-in node:sqlite.
• npm and Git. Server and Web have separate package manifests and lockfiles; there is no root-level npm script.
• Chromium for UI reviews.
• For Android: JDK 17+, Android SDK 35, and Build Tools 35.0.1. The Web asset script requires a POSIX shell; Windows users can use Git Bash or WSL.

Unless noted otherwise, run commands from the repository root.

Install dependencies

npm ci --prefix server
npm ci --prefix web

For browser UI reviews, install Chromium from the Web directory:

cd web
npx playwright install chromium

Linux CI can use npx playwright install --with-deps chromium to install system dependencies too. Alternatively, point CHROME_PATH at an existing Chrome/Chromium executable.

Start development servers

Open two terminals at the repository root. Use a test library and keep data outside it.

Linux/macOS:

mkdir -p /tmp/reader-dev-books /tmp/reader-dev-data
BOOKS_DIR=/tmp/reader-dev-books DATA_DIR=/tmp/reader-dev-data npm run dev --prefix server

PowerShell:

$env:BOOKS_DIR = Join-Path $env:TEMP 'reader-dev-books'
$env:DATA_DIR = Join-Path $env:TEMP 'reader-dev-data'
New-Item -ItemType Directory -Force -Path $env:BOOKS_DIR, $env:DATA_DIR | Out-Null
npm run dev --prefix server

In the second terminal:

npm run dev --prefix web

Open http://localhost:5174. Vite proxies /api to http://127.0.0.1:5888 by default. Set READER_SERVER to change the proxy target.

Checks and tests

Run checks for the modules you change. Available entry points are:

npm run typecheck --prefix server
npm test --prefix server
npm run build --prefix server

npm run typecheck --prefix web
npm test --prefix web
npm run build --prefix web

Web tests use both Vitest and Node's test runner. UI reviews use real Chromium; prepare it as described above. Historical test counts are not a substitute for current results.

For UI changes, run npm run ui:review --prefix web; source workflows have npm run ui:sources --prefix web. The review scripts live under web/tools/ui-review/ and write screenshots and reports to the Git-ignored artifacts/ui-review/ directory. Do not commit one-off screenshots under docs/.

Build and run

Single-container image

docker build -f server/Dockerfile -t reader:local .

Use the repository root as the build context. The image builds both the Web client and server. Set the Compose image to reader:local, or use its commented build configuration.

Without a container

Build both server and Web with their npm run build scripts, then start from the repository root:

BOOKS_DIR=/tmp/reader-dev-books DATA_DIR=/tmp/reader-dev-data WEB_DIR="$PWD/web/dist" npm start --prefix server

In PowerShell, set $env:BOOKS_DIR, $env:DATA_DIR, and $env:WEB_DIR = (Resolve-Path 'web/dist').Path, then run npm start --prefix server. WEB_DIR must point to the built client; the server does not automatically locate another project's web/dist directory.

Android

Build the shared Web assets from the repository root, then build the APK:

sh android/scripts/build-web-assets.sh
cd android
./gradlew :app:assembleDebug

Use gradlew.bat from a native Windows terminal. The output is android/app/build/outputs/apk/debug/app-debug.apk. Add -PdefaultServerUrl=http://nas.local:5888 to preset the server address; otherwise users enter it and sign in. Building an APK does not validate reading on a physical device.

Code map

Directory	Responsibility
server/src/config, db	Runtime configuration, SQLite schema and access
server/src/indexer	File formats, scanning, identity, and metadata
server/src/services, http	Business services, API, authentication, and resources
server/src/media	Media catalog, scans, metadata, and playback
web/src/features/media	Media pages, components, services, themes, and players
server/src/sources	Local library and OPDS integration
web/src/formats	EPUB, TXT, comics, and other format handling
web/src/ui, styles	Shared interactions, imperative reading stage, and reader styles
web/src/core, store	Platform capabilities, synchronization, and offline storage
android/app/src/main/java/cool/cnb/reader	Android Activity, WebView, native image and speech bridges

The application UI uses React 19 and React Router. React Query owns server data and Zustand owns shared client state; the imperative reading stage handles book layout and measurement. Mantine provides base interaction components, Lucide React provides icons, and Shadow DOM isolates book styles. Both the server and Android consume the Web build. See architecture (中文) and UI guidelines (中文) for details.

Contributing workflow

1. Describe the issue, reproduction steps, and expected behavior. Remove credentials from logs, source rules, and examples.
2. Keep changes focused and follow existing error handling and test patterns.
3. Add appropriate regression checks for behavior changes. Documentation-only changes need link, command, and example checks.
4. Describe the changes, validation, and known limitations when submitting.

See the API reference (中文), media architecture (中文), and media validation (中文).