How to build a free website with Astro and Cloudflare Pages using Claude Code

You do not need to be a developer to have a professional website anymore. But you also should not trust no-code builders that lock you into monthly fees and limited customization. There is a third path: using Claude Code to build a real, production-grade static site that you own completely. Zero monthly hosting costs. Complete control over everything.

This is exactly how I built the site you are reading right now.

Why this stack actually works

The combination of Astro, Cloudflare Pages, and Claude Code creates something unusual: professional-grade web infrastructure that costs nothing to run and does not require coding knowledge to build.

Performance that matters: Astro significantly outperforms traditional React frameworks. It ships dramatically less JavaScript to browsers. Sites built with this stack routinely achieve perfect PageSpeed Insights scores without optimization gymnastics. This site - with hundreds of blog posts - loads instantly from anywhere in the world.

The technical reason is simple. Astro builds static HTML at compile time instead of shipping a massive JavaScript bundle that renders in the browser. Your readers get actual HTML, not a JavaScript application that has to boot up before showing content.

Cost breakdown versus the alternatives: Cloudflare Pages free tier includes unlimited bandwidth, unlimited requests, 500 builds per month, and global CDN delivery. That 500-build limit means you can update your site 16 times per day for free. No credit card required.

Compare this to the alternatives. Traditional website builders charge monthly subscription fees that compound significantly over years. Webflow and Squarespace both require ongoing payments. This stack? Only the cost of a domain name annually.

The savings compound when you factor in Claude Code replacing what would traditionally require hiring a developer. Professional website builds typically cost thousands of dollars. You can build the same thing for the cost of a Claude Pro subscription plus one focused session.

Real example - this actual site: This is not theoretical. The website you are reading runs on this exact stack. Hundreds of blog posts. Custom styling with gooey button effects and gradient animations. Image optimization pipeline. Full SEO implementation. Google Analytics integration. Zero monthly hosting fees.

Build time for a site like this with Claude Code: a weekend of focused work. Maintenance: minimal time monthly for content updates.

When not to use this stack: Be honest about limitations. This approach fails for highly interactive applications - admin dashboards, social networks, real-time collaboration tools. If your site needs user authentication, complex client-side state management, or frequent real-time updates, use Next.js or Nuxt.js instead.

Also skip this if your team has zero technical literacy and no interest in learning. While Claude Code eliminates the need to write code, you still need to understand concepts like Git repositories, deployments, and build processes. If that sounds like a foreign language you refuse to learn, stick with Squarespace.

Getting your machine ready

You need five things installed. Here is what each does and how to get it.

Claude Code Pro subscription - your AI developer

What it is: The AI that writes all your code, handles configuration, and manages deployments.

Why you need it: This is the bridge between “I cannot code” and “I have a professional website.” Claude Code is not autocomplete. It builds entire projects, configures deployment pipelines, and handles the complexity you would normally need a developer for. Unlike many AI tools that disappear after the hype fades, Claude Code is built by Anthropic with serious infrastructure behind it.

Requires: Claude Pro subscription. Not available on the free Claude plan.

How to get it: Go to claude.ai, create an account, upgrade to Claude Pro. Once subscribed, you can access Claude Code through the command line interface.

Install Claude Code: Follow the official installation guide for your operating system. The installer handles everything automatically.

Verify: Open your terminal (Command Prompt on Windows, Terminal on Mac) and type claude --version. Should show version number.

Node.js - the engine that runs Astro

What it is: JavaScript runtime that Astro needs to build your site into HTML and CSS files.

Why you need it: Astro is built on Node.js. Without it, nothing works.

Install (Mac): Download from nodejs.org, choose the LTS version (left button), run the installer, click through the prompts.

Install (Windows): Download the Windows Installer from nodejs.org, run the .msi file, accept defaults, click through.

Verify: Open terminal, type node --version. Should show a recent version number. Then type npm --version to verify the package manager installed correctly.

Git - version control that saves every version of your work

What it is: System that tracks every change you make to your site, lets you go back to previous versions, and syncs with GitHub.

Why you need it: You will break things. Everyone does. Git lets you undo. Plus, it is how your code gets from your computer to GitHub to Cloudflare Pages.

Install (Mac): Open Terminal, type git --version. If not installed, macOS prompts you to install Xcode Command Line Tools. Click Install. Takes 5-10 minutes.

Install (Windows): Download from git-scm.com, run installer, accept all defaults unless you know what you are doing.

Verify: Open terminal, type git --version. Should show a version number confirming installation.

GitHub account - stores your code and triggers deployments

What it is: Microsoft-owned platform that hosts your code repositories and integrates with Cloudflare Pages for automatic deployments.

Why you need it: Every time you push code to GitHub, Cloudflare Pages automatically rebuilds and deploys your site. Push to GitHub, site goes live. That simple.

Sign up: Go to github.com, click Sign Up, create free account. Use an email you actually check.

Cloudflare account - hosts your site globally

What it is: The company that runs one of the world’s largest networks. Their Pages service hosts static sites on their global edge network.

Why you need it: Free hosting with unlimited bandwidth on infrastructure that makes your site load fast from anywhere on Earth.

Sign up: Go to cloudflare.com, click Sign Up, create free account. No credit card required for the free tier.

Wrangler CLI (optional) - deploys to Cloudflare from terminal

What it is: Cloudflare’s command line tool for deployments and management.

Why you might need it: Useful for manual deployments or debugging, but not required since GitHub Actions handles deployments automatically.

Install: After signing up for Cloudflare, run npm install -g wrangler in your terminal.

That is everything. Five things installed, you are ready to build.

Building your site with Claude Code

This is where it gets interesting. You are going to describe what you want, and Claude Code builds it.

Step 1: Create new Astro project

Open your terminal and navigate to where you want your project. I keep mine in a Projects or GitHub folder.

Ask Claude Code:

“Create a new Astro project for my personal website. Use the blog template. Include Tailwind CSS for styling. Set up the basic configuration for a blog-focused site.”

Claude Code does this:

• Runs npm create astro@latest with the right options
• Chooses the blog template from official Astro templates
• Installs Tailwind CSS and configures it
• Sets up the project structure with all necessary folders
• Initializes Git repository
• Creates initial commit

You watch it happen. Claude shows you every command it runs, every file it creates, and explains why. The more specific you are in your prompts, the better results you get - understanding how to structure effective prompts makes the entire process smoother.

Step 2: Choose and customize theme

Out of the box, the blog template is generic. You need it to reflect your brand.

Ask Claude Code:

“I want a clean, professional look. Modern typography using Inter font. Simple color scheme - white background, dark text, green accent color (#01803d). Include a hero section on the homepage with a call-to-action button.”

Claude Code does this:

• Installs and configures Inter font family
• Updates Tailwind configuration with your color scheme
• Modifies the homepage layout to include hero section
• Creates reusable components for common elements
• Ensures responsive design works on mobile and desktop

Step 3: Configure for your brand

Edit the src/config.yaml file (Claude can do this, or you can edit it yourself - it is just a text file).

Ask Claude Code:

“Update site configuration with my information: Name is [Your Name], site URL will be [yourname.com], description is [your one-line pitch]. Add my LinkedIn and GitHub profile URLs.”

This updates metadata that search engines see, social media previews, and site navigation.

Step 4: Create first blog post

Ask Claude Code:

“Create a new blog post template. Show me the frontmatter structure I need to use. Create an example post about why I am starting this blog.”

Claude creates a markdown file in src/data/post/ with proper frontmatter:

---
publishDate: YYYY-MM-DDT00:00:00Z
title: 'Your post title here'
excerpt: 'Brief summary for SEO and social sharing'
image: ~/assets/images/your-image.jpg
category: 'Technology'
tags:
  - blogging
  - personal-brand
author: 'Your Name'
---

Then you write the actual content. That part is yours. Claude can help structure it, but your voice and ideas are what matter.

Step 5: Test locally

Before deploying to the world, see it working on your machine.

Ask Claude Code:

“Start the development server so I can preview the site locally.”

Claude runs npm run dev. Your site appears at http://localhost:4321. Open that in your browser. Every change you make updates instantly. This is your playground.

Once you are happy, test the production build:

“Build the site for production and preview it.”

Claude runs npm run build && npm run preview. This creates the actual files that will be deployed and lets you test them locally. If this works, deployment will work.

Step 6: Push to GitHub

Ask Claude Code:

“Create a GitHub repository for this project and push the code.”

Claude does this:

• Creates a new GitHub repository via the GitHub CLI
• Adds remote origin
• Commits all changes with a proper commit message
• Pushes to the main branch

Your code now lives on GitHub. Anyone can see it, you can access it from anywhere, and it is backed up.

Step 7: Connect Cloudflare Pages

Log into your Cloudflare account. Go to Pages, click Create a project, connect to your GitHub account.

Select the repository Claude Code just created. Cloudflare asks for build settings:

• Framework preset: Astro
• Build command: npm run build
• Build output directory: dist

Click Save and Deploy. Cloudflare builds your site and gives you a URL: your-project.pages.dev

Step 8: Set up automatic deployments

Ask Claude Code:

“Set up GitHub Actions to automatically deploy to Cloudflare Pages whenever I push to the main branch.”

Claude creates .github/workflows/deploy.yml with the proper configuration. This requires two GitHub secrets:

• CLOUDFLARE_API_TOKEN - Get this from Cloudflare dashboard under API Tokens
• CLOUDFLARE_ACCOUNT_ID - Get this from Cloudflare Pages project settings

Add these secrets in your GitHub repository settings under Secrets and Variables.

Now every push to main automatically builds and deploys your site. Change something, commit, push. Site updates in 2-3 minutes. That is the entire workflow.

Avoiding the gotchas

Real problems that break builds and waste hours. Learn from my mistakes.

Smart quotes will break your build

This is the silent killer. When you copy text from Google Docs, Notion, Slack, or ChatGPT, they include smart quotes (“curly quotes” and ‘apostrophes’). Astro chokes on these.

Your build fails with cryptic errors like “Expected } but found re” pointing at code that looks perfectly fine.

The problem is invisible. Smart quotes look like regular quotes in most editors. You cannot see the difference without inspecting character codes.

Solution: Before every commit, run:

grep -n "[''""—–…]" src/**/*.{astro,ts,tsx,js,jsx,md}

If this returns anything, you have smart quotes. Fix them by replacing with straight quotes.

Better solution: Disable smart quotes at the OS level. Mac: System Preferences → Keyboard → Text → uncheck “Use smart quotes”. Windows: Usually not enabled by default, but check your editor settings.

Image orientation must be landscape

All blog post images must be wider than tall. Portrait or square images break the layout.

When downloading from Unsplash, verify dimensions. A 2400x1600 image is landscape (wider). A 1600x2400 image is portrait (taller). Always choose landscape.

Test builds locally before pushing

Your development server (npm run dev) is forgiving. The production build (npm run build) is not. Always run the production build locally before pushing to GitHub:

npm run build

If this fails, fix it before committing. GitHub Actions will fail the same way, but debugging is harder when you cannot see the full output.

Character encoding issues

Use UTF-8 everywhere. If you paste content and weird symbols appear, it is likely encoding problems. Save all files as UTF-8 (most editors do this by default, but verify).

GitHub Actions secrets setup

For automatic deployments to work, you must add secrets to GitHub. These are not in your code (that would be insecure). They live in repository settings.

Go to your repository → Settings → Secrets and variables → Actions → New repository secret.

Add both CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID. If these are missing or wrong, deployments silently fail.

Cloudflare domain configuration

When adding a custom domain, Cloudflare needs to verify ownership. For the root domain (example.com), you need to point nameservers to Cloudflare. For subdomains (www.example.com), a CNAME record works.

SSL certificates take 5-15 minutes to provision. Your site might show a security warning during this period. That is normal. Wait.

Maintaining your site long-term

You built it. Now you need to keep it running and growing.

Adding new blog posts with Claude Code

Every time you want to publish:

Ask Claude:

“Create a new blog post with title [your title]. Use today’s date in the frontmatter. Set up the proper frontmatter structure and let me write the content.”

Claude creates the file in the right location with proper frontmatter. You write the actual post content. Then:

“Check this blog post for smart quotes and special characters, fix any issues, then commit and push it.”

Claude verifies character encoding, commits with a proper message, pushes to GitHub. Site rebuilds automatically. New post goes live in 2-3 minutes.

Updating existing content

Ask Claude:

“Find the blog post titled [title] and update [specific thing].”

Claude locates the file, makes the change, shows you a diff so you can review, then commits and pushes.

Making design changes

Describe what you want changed visually:

“Make the blog post headings slightly smaller and add more spacing between them.”

Claude finds the relevant CSS, makes the adjustments, shows you the changes in development mode so you can preview, then commits when you approve.

Managing images and assets

Keep images under 500KB for performance. Always use landscape orientation for blog post hero images. Ask Claude to handle the optimization:

“Optimize this image for web use and add it to the assets folder.”

Claude can resize, compress, convert to WebP format if needed, and place it in the correct folder.

Keeping dependencies updated

Once per quarter, ask Claude:

“Check for outdated packages and update them to latest stable versions. Make sure nothing breaks.”

Claude runs npm outdated, updates package.json, tests the build, and commits if everything works. Modern web development requires this maintenance. Claude handles it.

The balance - when to use Claude versus doing it yourself

Use Claude for:

• Anything involving code or configuration
• Setting up new features or integrations
• Debugging build failures
• Dependency updates
• Structural changes to templates or layouts

Do yourself:

• Writing actual blog post content (your voice, your ideas)
• Choosing images and visual direction
• Deciding what features you need
• Content strategy and topic selection
• Reviewing changes before they go live

Think of Claude Code as your technical co-founder who handles all engineering but needs you to make product decisions.

Bonus: Custom touches on this site

Here is what I added beyond the basic template to make this site feel unique:

Gooey button effect: Primary call-to-action buttons use an SVG filter that creates a liquid blob appearance when you hover. Based on this CodePen. Mouse-following gradient that creates organic movement. Touch support for mobile. Keyboard focus for accessibility.

Interactive gradients: Hero section has an animated gradient background. Footer has a subtle gradient that shifts. These are CSS-only, no JavaScript weight.

Image optimization pipeline: Automatic WebP conversion at build time. Quality optimized for best size-to-quality ratio. Multiple responsive sizes generated for different devices. AVIF format for browsers that support it. Result: significantly smaller file sizes than JPEG with no visible quality loss.

Performance optimizations: All CSS inlined at build time (eliminates render-blocking requests). Google Analytics runs in a web worker via Partytown (keeps main thread free). Images lazy load by default with async decoding.

Typography system: Inter font enforced everywhere. Blog post headings use sentence case, never title case. Smaller heading sizes with more line spacing for readability. Body text at 18px with relaxed line height.

All of this was built by asking Claude Code to implement it. Each customization took minimal conversation where I described what I wanted and Claude wrote the code.

The site you are reading right now costs nothing to host, was built in a focused weekend, and handles hundreds of blog posts without breaking a sweat.

Your site can do the same. The tools exist. The infrastructure is free. The AI that bridges the gap requires a Claude Pro subscription.

What you build on top of that foundation is entirely up to you.