Developer Workflow

This guide covers the branch-based deployment workflow using Cloudflare Workers Builds.

Environments

Branching Strategy

master (production)   ← Protected, auto-deploys to production
  ↑
  PR (merge when ready)
  ↑
dev (staging)         ← Auto-deploys to staging workers
  ↑
  PR (review & test)
  ↑
feature/xyz           ← Developer feature branches

Key principles:

• master is always deployable and reflects production
• dev is the integration branch for testing before production
• Feature branches are short-lived and merge into dev
• All merges happen via Pull Requests

Daily Development Workflow

1. Start a new feature

# Ensure you're up to date
git checkout dev
git pull origin dev

# Create feature branch
git checkout -b feature/my-feature

2. Develop locally

# Start all apps in dev mode
bun run dev

# Or start specific apps
bun run dev:web      # Next.js on http://localhost:3001
bun run dev:server   # Hono API on http://localhost:3000

3. Test in Workers runtime (optional)

Before pushing, test your changes in the actual Workers runtime:

# Test with production config
cd apps/web && bun run preview

# Test with staging config
cd apps/web && bun run preview:staging

4. Push and create PR to dev

git add .
git commit -m "feat: add my feature"
git push -u origin feature/my-feature

Create a Pull Request targeting the dev branch. Request review from teammates.

5. Merge to dev → Automatic staging deployment

Once the PR is approved and merged:

• Workers Builds automatically deploys supaseat-web-preview
• Workers Builds automatically deploys supaseat-api-staging

Test your changes on staging:

• Web: https://supaseat-web-preview.supaseat-950.workers.dev
• API: https://supaseat-api-staging.supaseat-950.workers.dev

6. Promote to production

When staging is verified and ready for production:

git checkout master
git pull origin master
git merge dev
git push origin master

Or create a PR from dev to master for additional review.

Workers Builds automatically deploys to production:

• Web: https://app.supaseat.com
• API: https://api.supaseat.com

Hotfix Workflow

For urgent production fixes:

# Branch from master
git checkout master
git pull origin master
git checkout -b hotfix/critical-fix

# Make the fix, then merge directly to master
git checkout master
git merge hotfix/critical-fix
git push origin master

# Backport to dev to keep branches in sync
git checkout dev
git merge master
git push origin dev

Available Scripts

Root commands

Web app (apps/web)

Server (apps/server)

Workers Builds Configuration

Workers Builds is configured to automatically deploy on push:

Build configuration lives in each app's wrangler.jsonc:

{
  "build": {
    "command": "./node_modules/.bin/opennextjs-cloudflare build",
  },
}

Environment Variables

Production vs Staging

Environment-specific variables are defined in wrangler.jsonc:

{
  // Production (default)
  "vars": {
    "NEXT_PUBLIC_SERVER_URL": "https://api.supaseat.com",
  },
  "env": {
    // Staging
    "preview": {
      "vars": {
        "NEXT_PUBLIC_SERVER_URL": "https://supaseat-api-staging.supaseat-950.workers.dev",
      },
    },
  },
}

Secrets

Secrets are set per environment via Wrangler CLI:

# Production
wrangler secret put DATABASE_URL

# Staging
wrangler secret put DATABASE_URL --env staging

See Cloudflare Deployment for the full list of required secrets.

Best Practices

1. Keep feature branches small - Easier to review and less merge conflicts
2. Test on staging before production - Always verify changes work in the Workers runtime
3. Use meaningful commit messages - Follow conventional commits (feat:, fix:, chore:)
4. Don't skip staging - Even small changes should flow through dev first
5. Keep dev and main in sync - After production deploys, ensure dev has all changes

Troubleshooting

Staging deployment didn't trigger

Check that:

• The push was to the dev branch
• Workers Builds is connected to your repository
• The build didn't fail (check Cloudflare Dashboard → Workers → Deployments)

Local preview doesn't match production

The bun run dev command uses Node.js, while production uses the Workers runtime. Always test with bun run preview before deploying to catch runtime differences.

Merge conflicts between dev and master

git checkout dev
git fetch origin
git merge origin/master
# Resolve conflicts
git push origin dev