name: deployment-strategies description: Core Cloudflare Pages/Workers deployment workflow, environment variable configuration, and secrets management. Use when deploying code, configuring environments, or managing secrets.

Requires: file-read, terminal (Wrangler/Cloudflare CLI). No network access needed.

Deployment Strategies Skill

Use When

Use this skill when:

• Preparing or executing staging/production deployments.
• Updating environment configuration or secrets management steps.

Execution workflow:

1. Run pre-deploy quality checks before deployment changes.
2. Use the appropriate deploy command for the change type (including cache purge when needed).
3. Keep env/secrets handling aligned with existing Cloudflare workflow conventions.
4. Verify deployment health immediately after rollout.

Output requirements:

• Summarize deploy/config changes and affected environments.
• Include exact deploy and verification commands used.

What This Skill Does

Core deployment patterns for SongShare Effect:

• Deploy commands — npm run deploy, npm run deploy:full (with cache purge)
• Environment configuration — per-environment env vars for frontend and API
• Secrets management — Cloudflare Worker secrets via wrangler secret put

Common Scenarios

• Deploying API server to Cloudflare Workers or frontend to Cloudflare Pages
• Configuring environment variables for staging or production
• Adding new secrets or credentials
• Running pre-deploy validation

Deploy Workflow

Local Development

npm run dev:all   # Frontend: http://localhost:5173 | API: http://localhost:8787

Pre-Deploy Checklist

Always run before pushing to production:

npm run lint
npx tsc -b .
npm run test:unit

Deploy Commands

# Standard deploy
npm run deploy
 
# Deploy + purge CDN cache (use this for any user-facing change)
npm run deploy:full
 
# Staging
npm run deploy:staging

Use deploy:full whenever updating UI components, API behavior, or fixing bugs — ensures users see new code immediately rather than cached versions.

Verify After Deploy

# Check API is healthy
curl https://<your-domain>/api/health
 
# Tail live logs for errors
wrangler tail --env production

Environment Configuration

Frontend Variables

Set in .env (dev) or Cloudflare Pages environment (staging/prod):

VITE_API_URL=http://localhost:8787          # Development
VITE_API_URL=https://staging-api.app.com   # Staging
VITE_API_URL=https://api.app.com           # Production
 
VITE_SUPABASE_URL=https://project.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key

API Variables

Non-secret config in wrangler.toml:

[env.production.vars]
ENVIRONMENT = "production"
SUPABASE_URL = "https://project.supabase.co"

Secrets Management

Never commit secrets to git. Use Cloudflare Worker secrets instead:

# Set a secret in production
wrangler secret put SUPABASE_SERVICE_KEY --env production
# (paste value, press Enter)
 
# List current secrets
wrangler secret list --env production

Local development secrets go in .env files (gitignored).

Sub-Skills

• Cache management + GitHub Actions CI/CD
• Rollback, monitoring, troubleshooting

References

• docs/DEPLOY.md
• docs/cache-management.md
• docs/github-actions-workflows.md

Do Not

• Do not violate repo-wide rules in .agent/rules.md.
• Do not add broad lint/type suppressions without explicit justification.
• Do not expand scope beyond the requested task without calling it out.

Success Criteria

• Changes follow this skill's conventions and project rules.
• Relevant validation commands are run, or skipped with a clear reason.
• Results clearly summarize behavior impact and remaining risks.

Skill Handoffs

• If active production recovery is required, also load deployment-operations.
• If CDN cache behavior must change with deploy, also load cloudflare-cache-cicd.