Source: https://cliparr.dev/docs/development/

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

macOS / Linux

```bash
git clone https://github.com/techsquidtv/cliparr.git
cd cliparr
cp .env.example .env
pnpm install
pnpm dev
```

PowerShell

```powershell
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

```bash
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.