LogoTanStarter Docs
LogoTanStarter Docs
HomepageIntroductionCodebaseGetting StartedEnvironments
Configuration
Deployment

Integrations

CloudflareDatabaseAuthenticationEmailNewsletterStoragePaymentNotificationsAnalyticsChatboxAffiliates

Customization

MetadataPagesLanding PageBlogComponentsUser ManagementAPI Key Management

Codebase

Project StructureFormatting & LintingEditor SetupUpdating the Codebase
X (Twitter)

Deployment

Learn how to deploy your TanStarter project to Cloudflare Workers

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

Prerequisites

Before deploying your project to Cloudflare Workers, make sure you have a Cloudflare account. If you don't have one, sign up here

Note on Worker Size Limits

The size limit of a Cloudflare Worker is 3 MiB on the Workers Free plan, and 10 MiB on the Workers Paid plan. After building your Worker, wrangler will show both the original and compressed sizes:

Total Upload: 10421.14 KiB / gzip: 2241.95 KiB

Only the latter (compressed size) matters for the Worker size limit. The TanStarter template is approximately 2 MB, so you can deploy even on the Cloudflare Free plan.

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. Cloudflare API Token: Follow the Cloudflare API Token guide to configure the Token
  3. Database Setup: Follow the Database guide to create and initialize both local and remote databases
  4. Storage Setup: If you need file storage feature, follow the Storage guide to create an R2 bucket
  5. Environment Variables: Follow the Environment Configuration guide to configure all necessary environment variables for your site's features

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
  }
],

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.

Configure Production Environment Variables

Set up runtime environment variables for production. Follow the steps below: copy the .env file to .env.production, modify the relevant variables to production values, then bulk set the secrets.

Make sure the Cloudflare API Token includes the Account > Workers Scripts > Edit permission, otherwise you may encounter errors.

# Copy .env to .env.production
cp .env .env.production

# Modify .env.production with production values
# For example: VITE_BASE_URL, STRIPE_SECRET_KEY, etc.
# VITE_BASE_URL='https://your-domain.com'
# STRIPE_SECRET_KEY='your-stripe-live-secret-key'

# Bulk set secrets
pnpm wrangler secret bulk .env.production

# Set individual secrets
echo "your-secret" | pnpm wrangler secret put VITE_BASE_URL

After this step succeeds, you can see the newly created project in the Cloudflare Dashboard under Workers & Pages.

About Environment Files

  1. The .env.production file contains runtime environment variables for production. When you run the pnpm run deploy command in the next step, it will automatically read the environment variables from the .env.production file.

  2. The .env file contains runtime environment variables for local development. When you run the pnpm run dev command during daily development, it will automatically read the environment variables from the .env file.

Deploy to Cloudflare

Deploy your application to Cloudflare Workers by running the following build and deploy command.

Make sure the Cloudflare API Token includes the Zone > Workers Routes > Edit permission, otherwise you may encounter errors.

pnpm run deploy

After this step succeeds, you can see the deployed version in your project and access the website via your custom domain.

About Custom Domains

  1. If you don't have a domain yet, you can use the default domain provided by Cloudflare, which is typically https://{worker-name}-{account-name}.workers.dev. Make sure to update the environment variables in the .env.production file accordingly.

  2. If you already have a domain, you need to host it on Cloudflare, or follow the custom domain binding instructions in the dashboard settings to configure DNS records to properly resolve to the Cloudflare platform.

Connect GitHub Repository

The Worker project has been created via the command line in the previous steps. Now you need to connect your GitHub repository to enable automatic builds and deployments on code push.

  1. Go to the Cloudflare Dashboard and navigate to Workers & Pages
  2. Click on the Worker project created earlier to enter the project details page
  3. Go to Settings → Build, click Connect to connect your GitHub repository
  4. Select your GitHub repository and authorize
  5. Configure the build and deploy commands (use the default values):
    • Build command: pnpm run build
    • Deploy command: npx wrangler deploy
  6. Configure build-time environment variables: add all environment variables starting with VITE_ from your env file

About Environment Variables

  1. Build-time environment variables can only be configured in the dashboard and cannot be set via the command line or configuration files. These variables are read by Vite during the build phase and are mainly client-side variables starting with VITE_. Server-side runtime variables are configured via the wrangler secret command, as described in the previous step.

  2. If you want code pushes to your GitHub repository to automatically trigger builds and deployments on Cloudflare Workers, you must add all environment variables starting with VITE_ from your env file to the build-time environment variables to ensure the website functions correctly.

References

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

Next Steps

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

Database

Configure D1 database

Storage

Configure R2 storage

Payment

Configure Stripe payments

Authentication

Configure authentication

Table of Contents

Prerequisites
Pre-deployment Preparation
Deployment Steps
Configure Project Name
Configure Custom Domain
Configure Production Environment Variables
Deploy to Cloudflare
Connect GitHub Repository
References
Next Steps