Beginner Astro Blog with Tailwind & Cloudflare

Part 4: Cloudflare Workers & Deployment

·
astro cloudflare workers beginners

Configure Astro’s Cloudflare adapter, set up wrangler.jsonc, and deploy your blog to Cloudflare Workers using both the CLI and the Cloudflare dashboard.

In this final part, you’ll connect everything to the real world: Cloudflare Workers. We’ll configure Astro’s Cloudflare adapter, set up Wrangler, and walk through both the command line and the Cloudflare dashboard so you can see where everything lives.

By now you have:

  • An Astro v5 blog with Tailwind CSS v4
  • A small design system and base layout
  • Content collections, layouts, and components

Now we’ll make it public and fast, using Cloudflare’s edge network.

Step 1 - Install the Cloudflare Adapter for Astro

Astro needs an “adapter” to know how to run on Cloudflare Workers.

For more on the Cloudflare adapter:

Install the official Cloudflare adapter:

npm install @astrojs/cloudflare

Step 2 - Configure astro.config.mjs for Cloudflare Workers

Open astro.config.mjs and wire up the adapter:

// astro.config.mjs
// @ts-check
import { defineConfig } from 'astro/config'
import cloudflare from '@astrojs/cloudflare'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  site: 'https://your-domain.example', // update this later to your real domain
  output: 'server',

  adapter: cloudflare({
    platformProxy: {
      enabled: true,
    },
    imageService: 'compile',
  }),

  vite: {
    plugins: [tailwindcss()],
  },

  // integrations: [...]  // (astro-icon, mdx, etc., if you use them)
})

Key parts:

  • output: "server" tells Astro to build for a runtime like Cloudflare Workers
  • adapter: cloudflare(...) makes sure Astro generates a _worker.js entry for Wrangler
  • site should eventually match the domain you configure in Cloudflare

For more on Astro output modes and Cloudflare configuration:

Step 3 - Create or Review wrangler.jsonc

Wrangler reads configuration from a wrangler.json or wrangler.jsonc file in your project root.

For complete configuration reference:

Create wrangler.jsonc if you don’t have it yet:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-astro-blog",
  "main": "./dist/_worker.js/index.js",
  "compatibility_date": "2025-11-27",
  "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],
  "workers_dev": false,
  "send_metrics": false,
  "routes": [
    {
      "pattern": "your-domain.example",
      "custom_domain": true,
    },
  ],
  "assets": {
    "binding": "ASSETS",
    "directory": "./dist",
  },
  "observability": {
    "enabled": true,
  },
}

Important fields:

  • name - the Worker’s name inside Cloudflare
  • main - the built Worker entry that Astro generates
  • compatibility_date - the API version; pick a recent date and update occasionally
  • routes - how your Worker is attached to a domain
  • assets - tells Cloudflare to serve static assets from your dist directory

For more on compatibility dates:

If you don’t have a custom domain yet, you can temporarily set:

{
  "workers_dev": true,
  "routes": []
}

Cloudflare will then give you a https://my-astro-blog.your-account.workers.dev URL.

Step 4 - Log In with Wrangler

Before deploying, you need to link Wrangler to your Cloudflare account.

In your terminal:

npx wrangler login

This will:

  • Open a browser window
  • Ask you to log in to Cloudflare (if you’re not already)
  • Request permission for Wrangler to manage Workers on your behalf

Once you see a success message, Wrangler is connected to your account.

For more on authentication:

Step 5 - Build and Test Locally

Let’s make sure the Worker builds correctly before deploying.

From your project root:

npm run preview

Behind the scenes, this should:

  • Run wrangler types
  • Run astro check and astro build
  • Start wrangler dev using the generated _worker.js

For more on local development:

In the terminal you’ll see a local URL, often something like:

http://127.0.0.1:8787/

Open it in your browser. You should see your Astro blog, but now it’s running inside a Cloudflare Worker simulation.

If anything fails:

  • Check the error message for missing environment variables or syntax issues
  • Make sure main in wrangler.jsonc points to the correct built Worker path

Step 6 - Configure Cloudflare via the Dashboard (Web UI)

Even if you prefer the CLI, it’s helpful to understand the Cloudflare dashboard. We’ll link your Worker to a domain and see where configuration lives.

6.1 - Create a Worker (if Wrangler hasn’t already)

For direct access to your Cloudflare dashboard:

  1. Go to https://dash.cloudflare.com
  2. Choose your account
  3. In the left sidebar, click Workers & Pages
  4. Click Create → Worker
  5. Give it a name (for example, my-astro-blog)

If you already deployed with Wrangler, you should see the Worker listed here; you don’t need to create a new one.

6.2 - Attach a Domain (Route)

If you have a domain managed by Cloudflare:

  1. In the dashboard, go to Workers & Pages
  2. Click your Worker (e.g. my-astro-blog)
  3. Go to the Triggers tab
  4. Click Add route
  5. Enter your domain pattern, for example:
    • example.com
    • www.example.com
  6. Click Save

This route should match the pattern you set in wrangler.jsonc. If you prefer, you can manage routes only in the UI and leave routes empty in the config.

For more on routing:

6.3 - Environment Variables (Optional for Now)

If your Astro project uses secrets or environment variables:

  1. In your Worker’s page, go to the Settings tab
  2. Click Variables
  3. Add:
    • Environment variables (non‑secret values like APP_ENV)
    • Secrets (API keys, tokens, anything sensitive)

Later, you can bind these to Astro’s runtime in server endpoints. For a simple blog that doesn’t call external APIs, you can skip this for now.

For more on environment variables:

Step 7 - Deploy to Cloudflare Workers with the CLI

Once everything looks good locally, it’s time to deploy.

From your project root:

npm run deploy

This should:

  • Generate Cloudflare types
  • Type‑check and build your Astro project
  • Upload the built Worker to Cloudflare
  • Attach it to your routes (from wrangler.jsonc or the dashboard)

If the deploy succeeds, Wrangler will print the URLs where your Worker is available.

Check both:

  • https://your-domain.example (if you attached a custom domain)
  • https://my-astro-blog.<your-account>.workers.dev (if workers_dev is enabled)

Step 8 - Basic Production Checklist

Before you call it done, quickly run through:

  • HTTPS working
    Open the site in a browser and confirm the connection is secure.

  • Navigation and content
    Click through your homepage, blog index, and at least one post.

  • Dark mode
    If you implemented a theme toggle, test both light and dark.

  • Performance Open DevTools → Network, refresh, and verify quick responses from Cloudflare’s edge.

For monitoring your Worker’s performance:

If something feels off, you can:

  • Run npm run preview locally again
  • Update your code or configuration
  • Re‑deploy with npm run deploy

Recap: From Zero to Deployed Astro Blog

Across all four parts, you:

  • Part 1 - Created an Astro v5 project, added Tailwind CSS v4, and set up Wrangler scripts
  • Part 2 - Built a design system with CSS variables and fontsource‑powered typography
  • Part 3 - Used content collections, layouts, and astro‑icon to create a real blog
  • Part 4 - Configured the Cloudflare adapter, set up wrangler.jsonc, and deployed to Workers using both the CLI and the dashboard

You now have a beginner‑friendly, modern blog:

  • Fast by default (Astro + Cloudflare edge)
  • Easy to style (Tailwind CSS v4 with a design system)
  • Comfortable for long‑form writing (layouts, typography, and components)

From here, you can keep iterating:

  • Add a search modal or command palette
  • Experiment with more content types (notes, docs, snippets)
  • Integrate analytics or small interactive widgets

But the hard part getting from nothing to a deployed Astro + Tailwind + Cloudflare blog is done. Nicely done.