Deploying Site

This document will help you deploy your ShipSaaS project to Cloudflare Workers.

Note on Worker Size Limits

The size limit for a Cloudflare Worker is 3 MB on the Workers Free plan, and 10 MB on the Workers Paid plan. When you build a Worker, wrangler will show the raw size and compressed size. Only the latter (compressed size) matters for the Worker size limit.

Total Upload: 10421.14 KiB / gzip: 2241.95 KiB

The ShipSaaS template size is approximately 2.3 MB, so you can deploy it even on the Cloudflare Free plan. However, if you need to use the Cloudflare Email Service, you must pay. We recommend upgrading to the Worker Paid Plan for more features and higher free quotas.

Prerequisites

Before deploying, ensure you have completed the following preparation steps:

1. Project Initialization: Follow the Get ShipSaaS document to complete initialization, dependency installation, and local running.
2. Environment Variable Configuration: Follow the Environment Configuration document to configure the necessary environment variables required for the website's features.

Deployment Steps

Configure Project Name

Update your project name in the wrangler.jsonc file:

wrangler.jsonc

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

Configure Custom Domain

Update your website domain in the wrangler.jsonc file:

wrangler.jsonc

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

Note on Custom Domains

The configuration above applies when your domain is already hosted by Cloudflare and no DNS is configured. If your domain is not yet hosted on Cloudflare, you can temporarily remove the routes configuration. Once the deployment is complete, go to the Cloudflare Dashboard to manually bind your custom domain.

Prepare Environment Variables

Copy .env to .env.production and update the values for your production environment. Make sure to update specific environment variables to their production values:

cp .env .env.production

# Edit .env.production to configure production environment values
# VITE_BASE_URL='https://your-domain.com'
# STRIPE_SECRET_KEY='your-stripe-live-secret-key'
# Check and update other environment variables to their production values carefully

Set Build-Time Environment Variables

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

bun run sync-github-secrets

This script internally performs two operations:

1. Sync .env.production with deploy.yml: Ensures that the env block of the GitHub Actions workflow contains all the build-time variables (VITE_*, CLOUDFLARE_*) defined in .env.production. Any missing environment variables will be added automatically.
2. Push Secrets to GitHub: Reads all non-empty variables from .env.production and sets them as GitHub Secrets via gh secret set. Ensure the .env.production file exists, and that gh is installed and authenticated.

Prerequisites

• You must be logged into GitHub CLI: gh auth status
• The .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:

bun run 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 using the Wrangler CLI.

Note on Runtime Secrets

• Runtime secrets are injected via process.env during Worker execution.
• Environment variables with the VITE_* prefix are automatically excluded since they are only used during the build phase.
• To update runtime secrets, simply run bun run sync-worker-secrets again.

Build and Deploy

Manual Build

If you prefer to manually build and deploy, execute the following command:

bun run deploy

Automated Build

The template supports automated build and deployment via GitHub Actions.

The workflow file is located at .github/workflows/deploy.yml and will automatically build and deploy every time you push code to the main branch.

Enable Workflow: Go to the Actions tab of your GitHub repository and enable "GitHub Actions" if prompted.

Workflow Process: Each push to the main branch triggers the workflow to:

1. Pull the code
2. Install dependencies
3. Build using build-time environment variables from GitHub Secrets
4. Deploy to Cloudflare Workers via wrangler deploy

You can monitor the deployment progress and results in the Actions tab of your repository.

You can also trigger automated builds and deployments by binding your GitHub repository in the Cloudflare Workers dashboard. However, build failure rates on the Cloudflare platform can be high and issue-prone. We highly recommend using GitHub Actions for automated building and deployment instead.

Environment Variables Comparison

Why both are needed

• Build-time Secrets: Must be injected at build time because they are embedded in the client bundle; changing them requires a rebuild.
• Runtime Secrets: Cannot be set via GitHub Secrets because the Worker reads them at runtime, not during build time.

References

• Cloudflare Workers Documentation
• Cloudflare D1 Documentation
• Cloudflare R2 Documentation
• Wrangler CLI Reference

Next Steps

Now that you know how to deploy your website to Cloudflare Workers, explore other related topics:

• Database - Configure D1 database

• Storage - Configure R2 storage

• Payment - Configure Stripe payment

• Authentication - Configure authentication

• Environment Configuration

• Configuration