How to Build an Astro Website With Claude (Step by Step)
Use Claude to build a real Astro site, in the chat at claude.ai or with Claude Code in your terminal. This very site was built that way.
Tested on Astro 7.4
In this guide
Claude is the AI assistant made by Anthropic. You can use it two ways to build an Astro site: chat with it at claude.ai and paste the code in yourself, or run Claude Code, which works inside your project and edits files for you.
Full disclosure: AstroBeginner itself was built with Claude Code, with a person checking the work. So this guide is what we actually do.
Which way should you use?
| Chat at claude.ai | Claude Code | |
|---|---|---|
| Where it runs | In your browser | In your terminal, editor, or the Claude desktop app |
| Who edits the files | You | Claude, with your approval |
| Can it run commands? | No | Yes |
| Cost | Free plan available | Needs a paid Claude plan or API credits |
| Best for | Learning, small changes | Building and changing whole sites |
If you’ve never built a site, start with the chat. You’ll learn more by pasting the code in yourself. Move to Claude Code when you’re comfortable.
Before you start: create the project yourself
Whichever way you go, create the Astro project with the official tool, not by asking the AI to write every file from scratch. The official starter is always up to date, and AI tools sometimes reach for old patterns.
npm create astro@latest my-site -- --template basicsIf this is new to you, our free course walks through it. The project includes an AGENTS.md file with instructions for AI tools, which both Claude and ChatGPT read.
Option 1: Build with the chat at claude.ai
Step 1: Tell Claude what you have
Open a new chat and set the scene. Be specific about your version, because Astro changed a lot in 2026:
I'm a beginner building a website with Astro 7.4. I created the project with
"npm create astro@latest" using the basics template. I want a personal site
with a home page, an about page and a blog. Walk me through it one step at
a time, and show me the full contents of each file you want me to create.Step 2: Do one step at a time
Claude will give you a file. Create it in your editor, paste the contents, save, and look at your site in the browser. Then tell Claude what you see, including any error, before asking for the next step.
This back-and-forth matters. If you ask for everything at once, one small mistake early on becomes ten confusing errors later.
Step 3: Paste errors exactly
When something breaks, copy the whole error from your terminal or browser and paste it. Don’t describe it in your own words. The file name and line number in the error are what Claude needs. See how to fix Astro errors with AI.
Option 2: Build with Claude Code
Step 1: Install Claude Code
On a Mac or Linux, run this in your terminal:
curl -fsSL https://claude.ai/install.sh | bashWindows users have a PowerShell command in the official quickstart. Then open a new terminal window and check it worked:
claude --versionStep 2: Start it inside your project
cd my-site
claudeThe first time, it asks you to log in through your browser. Then you’re at a prompt where you type in plain English.
Step 3: Give it the job
Try this as your first request:
Read AGENTS.md first. Then add an about page at /about with a short bio, and
add a link to it in the navigation. Start the dev server in the background
and check the page loads before you finish.Claude Code reads your files, proposes changes, and asks before making them. Say yes when the change looks right. When it’s done, open the page yourself and check.
Step 4: Keep the steps small
Good requests for a beginner:
- “Add a blog using content collections, with one example post.”
- “Add Tailwind CSS using the official astro add command.”
- “Build the site and tell me if there are any errors.”
- “Deploy this to Cloudflare Workers. Explain each step before you run it.”
Avoid “build me a complete website”. You’ll get something, but you won’t understand it, and you won’t be able to fix it.
Give Claude the Astro docs
Claude’s knowledge has a cutoff date, and Astro moves fast. The fix is to connect it to the live Astro documentation through an MCP server. It’s a one-line setup, and it stops a whole class of outdated-code mistakes. See how to connect Claude and ChatGPT to the Astro docs.
Check the work
Before you publish anything an AI wrote:
- Run
npm run buildand make sure it passes. - Click through every page on your phone and your computer.
- Read the code once, even if you don’t understand all of it. You’ll catch things like a wrong site name or a leftover placeholder.
Our list of mistakes AI makes with Astro tells you what to look for.
Where to go next
- Astro prompts for Claude and ChatGPT, a set of prompts you can copy
- How to build an Astro site with ChatGPT, if you’d rather compare
- What is Claude Code?, in plain English
Frequently asked questions
Do I need to pay for Claude to build a website?
The chat at claude.ai has a free plan, which is enough to generate code you paste in yourself. Claude Code, which edits files for you, needs a paid Claude plan or API credits, according to its documentation.
Can Claude put my site online?
Claude Code can run the deploy commands for you if you give it permission. The chat version can only tell you what to type. Either way, you own the hosting account.
Is code from Claude safe to publish?
Treat it like code from a helpful colleague. Read it, run it, and test it before you publish. Our guide to the mistakes AI makes with Astro lists the things to check.
Stuck on a step?
Check the common errors guide, look up a word in the glossary, or ask in the official Astro Discord, where the support channels are friendly to beginners.