Astro + Cloudflare

This guide will walk you through deploying an Astro project to Cloudflare Workers from scratch. Perfect for beginners!

Prerequisites

Before starting, make sure you have:

• Node.js (v18 or higher) or Bun installed
• A Cloudflare account (free tier works fine)
• Basic terminal/command line knowledge

---

Project Folder Structure

Understanding where files go is crucial! Here’s the complete folder structure of an Astro + Cloudflare project:

• Directorymy-astro-site/ Your project folder (root)

  • Directorysrc/ Source code (you work here)

    • Directorypages/ Your website pages

      • index.astro Homepage (/)
    • Directorycomponents/ Reusable components

      • …
    • Directorylayouts/ Page layouts

      • …
    • Directorystyles/ CSS files

      • …
  • Directorypublic/ Static files (images, fonts, etc.)

    • favicon.svg Site icon
  • Directorydist/ Built files (auto-generated)

    • _worker.js Cloudflare Worker script
    • .assetsignore Ignore file for Wrangler
  • Directorynode_modules/ Dependencies (auto-installed)

    • …
  • astro.config.mjs Root Astro configuration
  • wrangler.jsonc Root Cloudflare config
  • package.json Root Project info & scripts
  • tsconfig.json TypeScript config
  • .gitignore Git ignore file

Important Locations

File/Folder	Location	Purpose
astro.config.mjs	Root	Astro + Cloudflare adapter config
wrangler.jsonc	Root	Cloudflare deployment settings
package.json	Root	Dependencies and scripts
.assetsignore	dist/	Tells Wrangler what to ignore
.dev.vars	Root	Local environment variables
Your pages	src/pages/	Website pages you create
Static assets	public/	Images, fonts (copied as-is)

Key Points

1. Root files = Same level as package.json
2. Source files = Inside src/ folder
3. Built files = Auto-generated in dist/ (don’t edit!)
4. Config files = Always in the root

Example: Where to Create Files

When the guide says “create in project root”, it means:

• Directorymy-astro-site/

  • astro.config.mjs Root
  • wrangler.jsonc Root
  • package.json Root

Caution

NOT inside src/ or any subfolder!

---

Part 1: Creating an Astro Project

Step 1: Install Astro

Open your terminal and run:

Bun (recommended)

bun create astro@latest

npm

npm create astro@latest

Step 2: Follow the Setup Wizard

You’ll be asked several questions:

Where should we create your new project?
→ my-astro-site

How would you like to start your new project?
→ Choose a starter template (or "Empty" for blank project)

Install dependencies?
→ Yes

Do you plan to write TypeScript?
→ Yes (recommended)

Initialize a git repository?
→ Yes (recommended)

Step 3: Navigate to Your Project

cd my-astro-site

---

Part 2: Installing Cloudflare Adapter

Astro needs an adapter to work with Cloudflare Workers.

1. Install Cloudflare Adapter

   Bun (recommended)

   bun add @astrojs/cloudflare

   npm

   npm install @astrojs/cloudflare

2. Install Wrangler (Cloudflare CLI)

   Wrangler is Cloudflare’s command-line tool for deployment.

   Bun (recommended)

   bun add wrangler --dev

   npm

   npm install wrangler --save-dev

---

Part 3: Configure Your Project

1. Update Astro Config

   Open astro.config.mjs and add the Cloudflare adapter:

   astro.config.mjs

   // astro.config.mjs
   import { defineConfig } from 'astro/config';
   import cloudflare from '@astrojs/cloudflare';
   
   export default defineConfig({
     output: 'server', // Enable SSR
     adapter: cloudflare(),
   });

   Note

   The output: 'server' enables Server-Side Rendering (SSR) which Cloudflare Workers needs.

2. Create Wrangler Configuration

   Create a file named wrangler.jsonc in your project root (same level as package.json):

   File location:

   my-astro-site/
   ├── package.json
   ├── wrangler.jsonc  ← Create here
   └── astro.config.mjs

   wrangler.jsonc (recommended)

   wrangler.jsonc

   {
     "$schema": "node_modules/wrangler/config-schema.json",
     "name": "my-astro-site",
     "compatibility_date": "2025-10-13",
     "workers_dev": true,
     "assets": {
       "directory": "./dist",
       "not_found_handling": "404-page"
     }
   }

   wrangler.toml

   wrangler.toml

   name = "my-astro-site"
   main = "./dist/_worker.js"
   compatibility_date = "2025-10-13"
   workers_dev = true
   
   [site]
   bucket = "./dist"

   How to create:

   Terminal

   # Make sure you're in project root
   cd my-astro-site
   
   # Create the file
   touch wrangler.jsonc
   
   # Then open it in your editor and paste the JSON above

   Manual

   Create manually in your code editor: File → New → Save as wrangler.jsonc in root.

3. Understanding .assetsignore File

   Important

   The .assetsignore file goes in the dist/ folder, NOT the root!

   File location:

   my-astro-site/         ← Project root
   ├── package.json
   ├── wrangler.jsonc
   └── dist/              ← Build output folder
       ├── _worker.js
       └── .assetsignore  ← Create here

   The Problem:

   • The dist/ folder is auto-generated when you run bun run build
   • It gets deleted and recreated every time you build
   • So .assetsignore needs to be recreated after each build

   Solution 1: Auto-create with deploy script

   Add this to your package.json scripts:

   package.json

   {
     "scripts": {
       "deploy": "npm run build && echo '_worker.js' > dist/.assetsignore && npx wrangler deploy"
     }
   }

   Now run: npm run deploy (or bun run deploy)

   Solution 2: Manual creation after build

   # 1. Build first
   bun run build
   
   # 2. Create .assetsignore in dist folder
   echo "_worker.js" > dist/.assetsignore
   
   # 3. Deploy
   npx wrangler deploy

   File content:

   _worker.js

   Why we need it

   • Prevents Wrangler from uploading _worker.js as a static asset
   • _worker.js is the Worker script, not a regular file
   • Without this, deployment will fail with an error

---

Part 4: Set Up Cloudflare Account

1. Create Cloudflare Account

   1. Go to cloudflare.com
   2. Click Sign Up
   3. Enter your email and password
   4. Verify your email address

2. Get Your Account ID Optional

   1. Log in to Cloudflare Dashboard
   2. Click on Workers & Pages in the sidebar
   3. Your Account ID is displayed on the right side
   4. Copy it for later (you might need it)

---

Part 5: Authentication with Wrangler

1. Login to Cloudflare via Wrangler

   Run this command in your terminal:

   npx wrangler login

   This will:

   1. Open your browser automatically
   2. Ask you to authorize Wrangler
   3. Click Allow to grant permissions
   4. Return to terminal - you’ll see “Successfully logged in”

2. Verify Login

   Check if you’re logged in:

   npx wrangler whoami

   You should see your account email and Account ID.

---

Part 6: Build and Deploy

1. Test Locally First

   Before deploying, test your site locally:

   Bun (recommended)

   bun run dev

   npm

   npm run dev

   Visit http://localhost:4321 to see your site.

2. Build Your Project

   Build your Astro site for production:

   Bun (recommended)

   bun run build

   npm

   npm run build

   This creates a dist folder with your built site.

3. Deploy to Cloudflare

   Deploy your site:

   npx wrangler deploy

   What happens:

   • Uploads your built files to Cloudflare
   • Creates a Worker
   • Gives you a live URL like: https://my-astro-site.YOUR-SUBDOMAIN.workers.dev

4. Visit Your Live Site

   After deployment completes, you’ll see:

   Deployed my-astro-site triggers (5.00 sec)
     https://my-astro-site.YOUR-SUBDOMAIN.workers.dev
   Current Version ID: abc123...

   Click the URL or copy it to your browser!

---

Part 7: Update Your Site

Step 17: Making Changes

Whenever you update your site:

1. Make your changes in code

2. Test locally

   Bun (recommended)

   bun run dev

   npm

   npm run dev

3. Build for production

   Bun (recommended)

   bun run build

   npm

   npm run build

4. Deploy

   npx wrangler deploy

Quick command (build + deploy in one line):

Bun (recommended)

bun run build && npx wrangler deploy

npm

npm run build && npx wrangler deploy

---

Configuration Files Reference

File Locations Overview

Here’s where each config file should be:

• Directorymy-astro-site/ PROJECT ROOT

  • astro.config.mjs 1. Astro config
  • wrangler.jsonc 2. Cloudflare config
  • package.json 3. Scripts
  • .dev.vars 4. Local env vars (optional)
  • Directorysrc/

    • …
  • Directorydist/ Generated on build

    • .assetsignore 5. Wrangler ignore

Required Files

Your project needs these configuration files:

1. astro.config.mjs Location: Root

astro.config.mjs

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare(),
});

2. wrangler.jsonc

wrangler.jsonc

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-astro-site",
  "compatibility_date": "2025-10-13",
  "workers_dev": true,
  "assets": {
    "directory": "./dist",
    "not_found_handling": "404-page"
  }
}

3. .assetsignore

_worker.js

4. package.json Scripts

package.json

{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "deploy": "bun run build && echo '_worker.js' > dist/.assetsignore && npx wrangler deploy"
  }
}

What does the deploy script do?

The deploy script runs three commands in sequence:

1. bun run build - Builds your Astro site
2. echo '_worker.js' > dist/.assetsignore - Creates .assetsignore to prevent _worker.js upload error
3. npx wrangler deploy - Deploys to Cloudflare Workers

This one command handles the entire deployment process automatically!

---

Command Reference

Development Commands

Bun (recommended)

Command	Description
bun run dev	Start local development server
bun run build	Build project for production
bun run preview	Preview production build locally
bun run deploy	Build and deploy in one command

npm

Command	Description
npm run dev	Start local development server
npm run build	Build project for production
npm run preview	Preview production build locally
npm run deploy	Build and deploy in one command

Wrangler Commands

Note

Wrangler commands work the same regardless of whether you use Bun or npm.

Command	Description
npx wrangler login	Login to Cloudflare
npx wrangler logout	Logout from Cloudflare
npx wrangler whoami	Check current login status
npx wrangler deploy	Deploy to Cloudflare Workers
npx wrangler tail	View live logs from your worker
npx wrangler delete	Delete your worker

Deployment Commands

Recommended: Use the deploy script

The deploy script automatically handles build, .assetsignore creation, and deployment.

Bun (recommended)

Quick Deployment:

bun run deploy

What it does:

1. Builds your Astro site
2. Creates .assetsignore file (prevents _worker.js error)
3. Deploys to Cloudflare Workers

Manual Steps (if needed):

# 1. Build
bun run build

# 2. Create .assetsignore
echo '_worker.js' > dist/.assetsignore

# 3. Deploy
npx wrangler deploy

npm

Quick Deployment:

npm run deploy

What it does:

1. Builds your Astro site
2. Creates .assetsignore file (prevents _worker.js error)
3. Deploys to Cloudflare Workers

Manual Steps (if needed):

# 1. Build
npm run build

# 2. Create .assetsignore
echo '_worker.js' > dist/.assetsignore

# 3. Deploy
npx wrangler deploy

---

Troubleshooting

Common Issues and Solutions

Issue 1: “API Token Required”

Error:

In a non-interactive environment, it's necessary to set a CLOUDFLARE_API_TOKEN

Solution

Run npx wrangler login to authenticate.

Issue 2: “_worker.js Upload Error”

Error:

Uploading a Pages _worker.js directory as an asset

Solution

Create .assetsignore file with _worker.js content.

Issue 3: “Port Already in Use”

Error:

Port 4321 is in use

Note

Astro will automatically try the next port (4322, 4323, etc.)

Issue 4: Build Fails

Solution

1. Delete node_modules and dist folders
2. Run npm install (or bun install)
3. Try building again: npm run build

Issue 5: Worker Not Working After Deploy

Solution

1. Check your astro.config.mjs has output: 'server'
2. Verify Cloudflare adapter is installed
3. Rebuild and redeploy

---

Environment Variables (Advanced)

Setting Environment Variables

If your app needs environment variables:

1. Create .dev.vars File

   For local development:

   .dev.vars

   DATABASE_URL=your-database-url
   API_KEY=your-api-key

2. Add to Cloudflare

   For production, add secrets via Wrangler:

   npx wrangler secret put DATABASE_URL
   # Enter your value when prompted

   Or add in wrangler.jsonc:

   wrangler.jsonc

   {
     "vars": {
       "ENVIRONMENT": "production"
     }
   }

---

Custom Domain (Optional)

Adding Your Own Domain

1. Add Domain to Cloudflare

   1. Go to Cloudflare Dashboard
   2. Click Add Site
   3. Enter your domain
   4. Follow DNS setup instructions

2. Add Route to Worker

   In wrangler.jsonc, add:

   wrangler.jsonc

   {
     "routes": [
       {
         "pattern": "yourdomain.com/*",
         "zone_name": "yourdomain.com"
       }
     ]
   }

3. Deploy

   npx wrangler deploy

   Your site will be available at your custom domain!

---

Best Practices

Best Practices

1. Use Version Control

Always commit your code to Git:

git add .
git commit -m "Deploy to Cloudflare"
git push

2. Test Before Deploy

Always run npm run dev and test locally before deploying.

3. Keep Dependencies Updated

Bun (recommended)

bun update

npm

npm update

4. Use Environment Variables

Never commit secrets/API keys. Use Wrangler secrets or .dev.vars.

5. Monitor Your Site

Use Cloudflare Dashboard to monitor:

• Traffic
• Errors
• Performance

---

Next Steps

Now that your site is deployed:

1. Add More Pages - Create new .astro files in src/pages/
2. Customize Design - Edit your components and styles
3. Add Features - Install Astro integrations
4. Set Up CI/CD - Automate deployments with GitHub Actions
5. Monitor Performance - Use Cloudflare Analytics

---

Useful Links

Astro Documentation Official Astro documentation and guides

Cloudflare Workers Docs Learn about Cloudflare Workers platform

Wrangler CLI Docs Command-line tool for Cloudflare Workers

Astro Cloudflare Adapter Official adapter documentation

---

Summary

You’ve learned how to:

• Install and set up Astro
• Add Cloudflare adapter
• Configure Wrangler
• Authenticate with Cloudflare
• Build and deploy your site
• Update and redeploy
• Troubleshoot common issues

Quick Deploy Commands

Full Deployment (Recommended):

Bun (recommended)

bun run deploy

npm

npm run deploy

Or Step by Step:

Bun (recommended)

# 1. Build
bun run build

# 2. Create .assetsignore
echo '_worker.js' > dist/.assetsignore

# 3. Deploy
npx wrangler deploy

npm

# 1. Build
npm run build

# 2. Create .assetsignore
echo '_worker.js' > dist/.assetsignore

# 3. Deploy
npx wrangler deploy

Happy deploying!