Skip to main content
Documentation menu

Deployment

Learn how to deploy your MinuteShip project to Cloudflare Workers

This guide will help you deploy your MinuteShip project to Cloudflare Workers.

Pre-deployment Preparation

Before deploying, make sure you have completed the following:

  1. Project Initialization: Follow the Getting Started guide to complete project initialization, install dependencies, and run locally
  2. Environment Variables: Follow the Environment Configuration guide to configure all necessary environment variables for your site's features
  3. Cloudflare Bindings: If you use D1, R2, or KV cache, make sure the corresponding wrangler.jsonc bindings are configured before deployment

Deployment Steps

Configure Project Name

Update the wrangler.jsonc file with your project name:

wrangler.jsonc

{
  "name": "your-project-name" // Change to your project name
}

Configure Custom Domain

Update the wrangler.jsonc file with your website domain:

wrangler.jsonc

"routes": [
  {
    "pattern": "your-domain.com", // Change to your domain
    "custom_domain": true
  }
],

Warning

About Custom Domains

The above configuration assumes your domain is already hosted on Cloudflare. If your domain is not yet hosted on Cloudflare, you can remove the routes configuration for now and manually bind a custom domain in the Cloudflare Dashboard after deployment.

Setup Environment Variables

Copy .env to .env.production and update values with production settings:

cp .env .env.production

# Edit .env.production with production values
# VITE_BASE_URL='https://your-domain.com'
# STRIPE_SECRET_KEY='your-stripe-live-secret-key'
# Other variables - carefully check and update as needed for production

Set Build-time Environment Variables

Run the following command to sync build-time environment variables to GitHub Secrets:

pnpm sync-github-secrets

This script performs two operations internally:

  1. Sync deploy.yml with .env.production: Ensures the GitHub Actions workflow's env block includes all build-time variables (VITE_*, CLOUDFLARE_*) defined in .env.production. Missing environment variables are automatically added.

  2. Push secrets to GitHub: Reads all non-empty variables from .env.production and sets them as GitHub Secrets via gh secret set. Ensure .env.production exists and gh is installed and authenticated.

Warning

Prerequisites

  • GitHub CLI must be logged in: gh auth status
  • .env.production file must contain build-time environment variables
  • Environment variables with VITE_* and CLOUDFLARE_* prefixes are synced to GitHub by default

Set Runtime Environment Variables

Run the following command to set runtime environment variables for the Worker:

pnpm sync-worker-secrets

This command internally executes wrangler secret bulk .env.production, reading non-empty variables from .env.production and bulk-setting them as Worker runtime secrets via the Wrangler CLI.

Warning

Note on Runtime Secrets

  • Runtime secrets are injected at Worker execution time via process.env.
  • This command uploads the supplied env file directly; it does not filter out VITE_* variables. Those values still need to be present at build time, and uploading them as Worker secrets does not change the client bundle.
  • To update runtime secrets, re-run pnpm sync-worker-secrets.

Build & Deploy

Manual Build

If you prefer manual build and deploy:

pnpm run deploy

Automated Build

The template supports automated build and deploy via GitHub Actions.

The workflow file is located at .github/workflows/deploy.yml and automatically builds and deploys on every push to the main branch.

Enable workflow: Go to your GitHub repository's Actions tab and enable "GitHub Actions" if prompted.

Workflow process: On every push to main, the workflow will:

  1. Checkout code
  2. Install dependencies
  3. Run read-only pnpm lint and pnpm test (compiling locale modules first)
  4. Run pnpm build with build-time environment variables from GitHub Secrets
  5. Run pnpm typecheck using the generated build types
  6. Deploy to Cloudflare Workers via wrangler deploy only after all checks pass

This workflow excludes browser E2E. Manual pnpm run deploy only builds and deploys; run pnpm check and pnpm check:production separately before release.

Monitor deployment progress in your repository's Actions tab.

You can also trigger automated build and deploy by binding a GitHub repository in the Cloudflare Workers dashboard. However, Cloudflare's build failure rate is relatively high with various issues. We recommend using GitHub Actions instead for more reliable automated build and deploy.

Environment Variables Comparison

TypeCommandWhen UsedExample
Build-time secretspnpm sync-github-secretspnpm build (baked into JS)VITE_BASE_URL, VITE_STRIPE_PRICE_*
Runtime secretspnpm sync-worker-secretsWorker execution time (process.env)STRIPE_SECRET_KEY, BETTER_AUTH_SECRET

Warning

Why both are needed

  • Build-time secrets must be injected at build time because they are embedded in the client-side bundle. Changing them requires a rebuild.
  • Runtime secrets need a separate upload to the Worker. Saving them in GitHub Secrets alone is insufficient; the current deployment workflow does not sync Worker secrets.

References

Next Steps

Now that you understand how to deploy your website to Cloudflare Workers, explore these related topics: