Documentation

Development

Set up the local workspace and run the checks before opening a pull request.

Development uses the root pnpm workspace. You need Node.js 24 or newer and pnpm 11.2.2 via Corepack.

Local setup 
git clone https://github.com/techsquidtv/cliparr.git
cd cliparr
cp .env.example .env
pnpm install
pnpm dev
git clone https://github.com/techsquidtv/cliparr.git
Set-Location cliparr
Copy-Item .env.example .env
pnpm install
pnpm dev

The frontend runs on http://localhost:5173. The API server runs on http://localhost:3000 and redirects auth callback pages back to the Vite frontend during development.

Optional Docker dev stack

The optional Docker dev stack seeds Plex and Jellyfin with Sintel, a Blender open movie with embedded subtitle tracks.

Run pnpm docker:dev:build after Dockerfile or dependency changes, then pnpm docker:dev:up to start the stack.

Pull request checks

Before opening a pull request, run:

Preflight 
pnpm preflight

Use a Conventional Commit pull request title, such as feat: add subtitle presets, fix: preserve Jellyfin session ids, or ci: update release automation.

Cliparr uses squash merges with the pull request title as the squash commit title. Release automation uses merged pull request titles to choose the next SemVer version and generate release notes.

Release-impacting title types:

  • feat creates a minor release.
  • fix, perf, security, and build(deps) create a patch release.
  • A breaking ! creates a major release.
  • docs, ci, chore, refactor, test, style, and other build changes are included in notes but do not trigger a release by themselves.

Releases

GitHub Releases are the canonical changelog. The manual Release workflow runs from main, publishes Docker images to GHCR, creates the GitHub Release, and triggers a Cloudflare Pages rebuild so /changelog mirrors the latest release notes.

Use the workflow’s dry-run mode before publishing. Real releases require the CLOUDFLARE_PAGES_DEPLOY_HOOK_URL repository secret. Cloudflare Pages builds require a read-only GITHUB_TOKEN or GH_TOKEN environment variable so the changelog mirror does not hit unauthenticated GitHub API rate limits.

Do not include Plex tokens, Jellyfin credentials, server URLs, local media paths, or other private account details in issues, logs, screenshots, or pull requests.