Beginner Astro Blog with Tailwind & Cloudflare

Part 1: Project Setup

·
astro tailwind cloudflare beginners

Start from zero and create a new Astro v5 blog wired with Tailwind CSS v4 and Cloudflare Wrangler, even if you're new to web development.

In this first part of the series, you’ll go from “nothing installed” to a working Astro v5 project that already knows about Tailwind CSS v4 and Cloudflare Workers. We’ll move slow, explain every step, and keep commands copy‑paste friendly.

What We’re Building in This Series

By the end of all four parts, you’ll have:

  • A modern Astro v5 blog
  • Styled with Tailwind CSS v4 and a small design system
  • Using fontsource for typography and astro-icon for icons
  • Deployed to Cloudflare Workers with wrangler

In Part 1, we focus only on:

  • Installing the tools you need
  • Creating a fresh Astro project
  • Adding Tailwind CSS v4 via the Vite plugin
  • Adding Wrangler scripts so Cloudflare is part of your workflow from day one

If you can copy and paste commands into a terminal, you can follow this guide.

Prerequisites (Beginner Friendly)

You don’t need to be a seasoned developer. You’ll just need:

  • A terminal (macOS Terminal, Windows Terminal, or Linux shell)
  • A code editor (VS Code, Cursor, or any editor you like)
  • A Cloudflare account (free plan is fine)

1. Install Node.js (LTS)

Astro and the tools we’ll use are all Node‑based.

  1. Visit https://nodejs.org
  2. Download the LTS version (marked “Recommended for most users”)
  3. Install it with the default options

Verify that Node and npm are installed:

node -v
npm -v

If both commands print a version (for example v22.x.x and 10.x.x), you’re good.

2. Log In to Cloudflare

Create or sign in to your Cloudflare account:

  1. Go to https://dash.cloudflare.com
  2. Either Sign up or Log in

We’ll use this account later in Part 4 to connect your Worker to a real domain.

Step 1 - Create a New Astro Project

Astro provides a project generator that sets everything up for you. For this series, the project was bootstrapped using Cloudflare’s Workers guide so the app targets Workers from the start:

Cloudflare’s docs use their create-cloudflare tool to scaffold an Astro app that’s already wired up for Workers:

npm create cloudflare@latest -- my-astro-app --framework=astro

You can replace my-astro-app with any folder name you like (for example, my-astro-blog).

The CLI will then ask a few questions:

  • Which framework are you using? This is set by --framework=astro, so it should be preselected.
  • Do you want to install dependencies? Choose Yes so it runs npm install automatically.

When the command finishes, change into your new project folder and list the files:

cd my-astro-app   # or your chosen folder name
ls

You should see something like:

astro.config.mjs
package.json
src/
public/

This is your starting Astro project.

Step 2 - Add Tailwind CSS v4

Tailwind v4 works differently from older versions. In this setup we use:

  • The Vite plugin: @tailwindcss/vite
  • A single global stylesheet that imports Tailwind and your design tokens

In this project, Tailwind was added in two steps:

  1. First, by following Astro’s “Add Tailwind 4” section:
    https://docs.astro.build/en/guides/styling/#add-tailwind-4
  2. Then, by cross‑checking with Tailwind’s own Astro framework guide for extra details:
    https://tailwindcss.com/docs/installation/framework-guides/astro

From inside your project folder, run Astro’s Tailwind helper:

npx astro add tailwind

This command:

  • Installs Tailwind and its related packages
  • Wires Tailwind into your Astro project
  • May update astro.config.mjs and your global styles for you

If, after running this, you don’t see tailwindcss and @tailwindcss/vite in your project, you can manually install them using the command from Tailwind’s official Astro guide:

npm install tailwindcss @tailwindcss/vite

Configure Tailwind in astro.config.mjs

Open astro.config.mjs in your editor and add the Tailwind plugin:

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

export default defineConfig({
  // ...your existing config
  vite: {
    plugins: [tailwindcss()],
  },
})

If you already have a vite section, just add tailwindcss() to its plugins array.

Import Tailwind in Your Global CSS

Astro projects usually have a global stylesheet, such as src/styles/global.css.

Open it (or create it if it doesn’t exist) and add:

@import 'tailwindcss';

This tells Tailwind v4 to generate utility classes for you and inject them through Vite.

We’ll turn this global stylesheet into a full design system in Part 2.

Step 3 - Add Cloudflare Wrangler and Helpful Scripts

Cloudflare Workers are deployed with a tool called Wrangler. We’ll install it and add npm scripts so you don’t have to remember long commands.

For more on Cloudflare Workers and Wrangler:

Install Wrangler as a dev dependency:

npm install -D wrangler

Now open package.json and add scripts like these:

{
  "scripts": {
    "dev": "wrangler types && astro dev --host",
    "build": "wrangler types && astro check && astro build",
    "preview": "wrangler types && astro check && astro build && wrangler dev",
    "deploy": "wrangler types && astro check && astro build && wrangler deploy",
    "cf-typegen": "wrangler types"
  }
}

What these do:

  • wrangler types generates Cloudflare‑specific TypeScript types for Astro
  • astro dev runs the local development server
  • astro build creates your production build in dist/
  • wrangler dev emulates your Worker locally
  • wrangler deploy publishes your Worker to Cloudflare

You don’t need to understand all of this yet. For now, remember:

  • npm run dev → work locally
  • npm run preview → test your Worker locally
  • npm run deploy → go live (we’ll use this in Part 4)

Step 4 - Run the Dev Server

Let’s make sure everything works so far.

From your project folder:

npm run dev

You should see output ending with something like:

Local    http://localhost:4321/
Network  http://your-ip-address:4321/

Open the local URL in your browser. You should see the default Astro starter page.

If you open your browser’s DevTools and inspect elements, you’ll be able to add Tailwind classes like class="text-red-500" and see them take effect. That’s your proof that Tailwind v4 is wired in correctly.

Quick Troubleshooting

If something goes wrong:

  • Command not found (astro, wrangler)
    Make sure you are inside the project folder and that node_modules/.bin is visible to npm. Running the npm run ... scripts is safer than calling tools directly.

  • Port already in use
    Another app might be using port 4321. Stop other dev servers or change the port with astro dev --port 4322.

  • Tailwind classes not working
    Double‑check that:

    • @import "tailwindcss"; is in your global CSS
    • The global CSS file is imported in your main layout or in BaseLayout.astro

Recap and What’s Next

You’ve just:

  • Installed Node and created an Astro v5 project
  • Added Tailwind CSS v4 via the Vite plugin
  • Wired Cloudflare Wrangler into your npm scripts
  • Verified that the dev server runs locally

In Part 2, we’ll slow down and focus on design:

  • Defining a blue-gray design system using Tailwind v4’s @theme directive
  • Adding Outfit, Inter, and Fira Code fonts using fontsource
  • Building a clean base layout with header, footer, and dark mode

When you’re ready, continue with Part 2 to make this starter project look and feel like a real blog.