Desktop App Release Process

This document describes how to release a new version of the Transcribe.dev desktop app.

Overview

The release process involves:

1. Bumping the version number
2. Building the app
3. Uploading the binary to Cloudflare R2
4. Updating the API with the new version info
5. (Optional) Creating a GitHub release for tracking

Prerequisites

• Access to Cloudflare account with R2 enabled
• Wrangler CLI configured (npx wrangler login)
• Push access to the repository

Step-by-Step Release Process

1. Bump the Version

cd apps/desktop
npm version <major|minor|patch> --no-git-tag-version
# Example: npm version patch --no-git-tag-version
# This changes 0.2.3 → 0.2.4

Or manually edit apps/desktop/package.json.

2. Build the Desktop App

# From repo root
pnpm --filter desktop build:mac

This creates:

• apps/desktop/dist/desktop-X.X.X.dmg - macOS installer
• apps/desktop/dist/Transcribe.dev-X.X.X-arm64-mac.zip - ZIP archive

3. Upload Binary to R2

# Replace X.X.X with your version
npx wrangler r2 object put transcribe-dev/releases/transcribe-dev-desktop-X.X.X.dmg \
  --file=apps/desktop/dist/desktop-X.X.X.dmg

The file will be available at: https://r2.transcribe.dev/releases/transcribe-dev-desktop-X.X.X.dmg

4. Update the API

Edit apps/api/src/routes/v1/releases.ts:

const CURRENT_RELEASE = {
  version: "X.X.X",  // New version
  releaseDate: "YYYY-MM-DD",  // Today's date
  downloadUrl: "https://r2.transcribe.dev/releases/transcribe-dev-desktop-X.X.X.dmg",
  releaseNotes: `
## What's New in vX.X.X

### Features
- New feature 1
- New feature 2

### Bug Fixes
- Fixed issue 1
  `.trim(),
  minVersion: "0.1.0",
};

5. Deploy the API

cd apps/api
npm run deploy

6. Test the Update

# Should return updateAvailable: true for older versions
curl -s https://api.transcribe.dev/v1/releases/check/0.2.2 | jq .

# Should return updateAvailable: false for current version
curl -s https://api.transcribe.dev/v1/releases/check/X.X.X | jq .

7. Commit and Push

git add -A
git commit -m "chore: Release vX.X.X"
git push origin main

8. (Optional) Create GitHub Release

For tracking purposes, you can also create a GitHub release:

git tag vX.X.X
git push origin vX.X.X

gh release create vX.X.X \
  --title "Transcribe.dev vX.X.X" \
  --notes "Release notes here..."

Note: The actual download happens from R2, not GitHub releases.

Infrastructure

R2 Storage

• Bucket: transcribe-dev
• Custom Domain: r2.transcribe.dev
• Path Pattern: /releases/transcribe-dev-desktop-{version}.dmg

API Endpoints

How the App Checks for Updates

1. On startup (5 second delay) and in Settings → System → Updates
2. Calls https://api.transcribe.dev/v1/releases/check/{currentVersion}
3. If updateAvailable: true, shows banner with download button
4. Download button opens R2 URL in browser

Troubleshooting

Upload to R2 fails

• Ensure you're logged in: npx wrangler login
• Check bucket exists: npx wrangler r2 bucket list

Update not showing in app

• Verify API is deployed: curl https://api.transcribe.dev/v1/releases/latest
• Check version comparison is correct (new version must be greater)

Download URL returns 404

• Verify file was uploaded: npx wrangler r2 object list transcribe-dev --prefix=releases/
• Check the exact filename matches the URL in releases.ts