Astro Site Through Claude Code: From Folder to Publication

Someone who has never written a line of code can build a site with Astro through Claude Code. I stopped writing code by hand a long time ago; I do everything with words through AI, and building a site with Astro works exactly the same way: you explain what you need, and Claude writes the code for you.

The problem is usually not the build itself, but that the path is split into pieces. One article explains installation, another covers commands, a third covers publication, and the complete route never comes together in your head. Here, I take you from an empty folder to a site that opens on the internet at a link: what to install, which command to use to start a project, how to build pages through Claude Code, and how to publish the result for free. I rely on the official Astro documentation.

About working with the service — in the Ailoot documentation.

What do I need before creating an Astro website with Claude Code?#

Astro itself does not ask you to download anything in advance — it will be fetched by the command in the next step. But you do need the environment in which it all runs. Astro describes getting started this way — you need three things:

Let’s go through what each of these means in practice:

1. Node.js — a program without which neither Astro nor most vibe-coding tools will run. Download it from nodejs.org and install it like a regular application. The version number in the documentation increases over time, so before you start, visit the Astro installation page and check the requirement. An even-numbered version (22, 24) is what you need; it is better to avoid an odd-numbered one (23, 25).
2. VS Code — a free editor from Microsoft. You open the project folder in it, and Claude Code works there too; it will write the code.
3. Terminal — a window where you enter commands. You do not need to install it separately: it opens from the menu in VS Code, and all the commands below are entered there.

If you have already installed Claude Code and built anything at all, you already have all of this, and you can skip this step. If not, I have a separate guide on how to install Claude Code.

How do you create an Astro project with one command?#

This is where the project itself begins, and it takes just one command. Open the terminal and enter:

npm create astro@latest

The installation wizard will start. Here is what the documentation says about it:

The wizard will guide you through the steps and ask a few questions: what to name the project folder, which template to start with, and whether to install dependencies right away. You can choose the default options for every question — an empty or minimal template will work for your first site. If you answered “no” to the question about installing dependencies, add them manually later by running the npm install command inside the project folder.

When the wizard is done, it will show that the project has been created and suggest the next step — moving into the project folder:

cd your-project-name

That is all it takes to create the project. Inside, there is already a working site scaffold: several files and folders used to build the page. You will not need to edit them by hand, but it is useful to know what is where. Astro considers only one folder mandatory:

In other words, src/pages is the folder containing the site’s pages: the home page, “about us,” and contact pages. src/components (reusable pieces like headers and buttons), src/layouts (the shared page framework), and the public folder for images and files usually live nearby. You do not have to memorize the layout — just keep in mind that pages live in src/pages, and refer to it when asking Claude: “add a contact page.”

How do you build the site itself through Claude Code?#

The scaffold is ready; now your site is built from it, and Claude Code takes over. Open the project folder in VS Code, launch Claude Code, and describe in words what you need. It edits the files in src/pages and nearby folders itself — you just give it tasks and look at the result.

In my experience, working in small steps works best. One huge request like “make me a company website” ends in a jumble that is hard to fix. So break it into short, clear tasks and give them one at a time:

1. “Make a home page: a large heading, a couple of sentences about what I do, and a button linking to the contact page.”
2. “Add a services page with a list of three sections.”
3. “Add a contact page with a phone number and a link to Telegram.”
4. “Change the styling: a light background and a large, readable font.”

Check each step before moving on — it makes it easier to catch when something is wrong and go back. Why small tasks are more reliable and how to keep AI on track are part of context engineering: the clearer the task and project structure, the more predictable the result.

Astro gives AI a structure that is convenient for this: page content is separate from styling, and pages are built according to shared rules. With this structure, Claude gets confused less often and is less likely to break something nearby when editing one place. If Claude suddenly stops seeing your files or responds irrelevantly, see the guide on why Claude Code cannot see project files.

How can you preview the site before publication?#

Before showing the site to the world, you preview it on your own computer. Astro has a development server for this — it shows the site live right on your computer. Start it with a command in the terminal, inside the project folder:

npm run dev

Astro will start a local preview and print the address in the terminal. By default, it is localhost:4321. Copy the address, open it in your browser, and you will see your site. For now, only you can open this address — no one outside can access it; this is your draft.

The handy thing is that the preview is live: Claude edits a file, and the page in the browser updates by itself; there is no need to reload manually. It is quick — ask Claude, look in the browser, make a correction, look again, and this is the stage where you polish the site. When you are happy with the result, publish it online.

How do you publish an Astro site online for free?#

You need to put the finished site somewhere so other people can open it from a link. The easiest free route is through GitHub: first upload the project code to a repository, then connect a hosting service that builds and publishes the site. Here is the sequence:

1. Create a repository on GitHub. A repository is an online code storage location where you send project files. Claude Code can help with this through natural-language instructions: ask it to “upload the project to a new GitHub repository,” and it will suggest commands. If you have never used GitHub before, keep instructions for registering and signing in nearby.
2. Connect hosting. Go to one of the services (Netlify, Vercel), sign in through your GitHub account, and choose your repository. The Astro documentation describes this method like this: the hosting service watches your repository, builds the site, and publishes it.
3. Check the build settings. Usually the hosting service recognizes Astro and fills in what is needed. If it asks you to enter them manually, the build command in the documentation is astro build (or npm run build), and the finished site is placed in the dist folder.
4. Click “Publish.” The service will build the site and give you a link like site-name.netlify.app. Anyone can open the site at that address.

Here is the documentation’s exact wording about connecting a repository to a hosting service:

After that, publication becomes automatic: send a new change to the repository, and the site is rebuilt and updated by itself; there is nothing else to click.

There is also a second free option — GitHub Pages, where the site is published directly from the repository using GitHub’s own tools. Astro has an official starter for it:

With this option, the site opens at an address like your-name.github.io/repository-name, and you can later connect your own domain to it. You can handle the setup through Claude Code here, too: describe the task in words, and it prepares the necessary file.

How much does it cost to build an Astro site?#

Now let’s talk money. Astro itself is a free, open-source tool; it has no separate price tag. Basic hosting services also offer free options: GitHub Pages, along with starter plans from Netlify and Vercel, which are usually enough for a lightweight Astro site (free plans have traffic limits, but they are usually enough for a lightweight business-card site or landing page).

So, in practice, there are two things you might pay for, and even then, not always. The first is the AI tool you use to build the site. The second is your own domain instead of an address like name.netlify.app; this is optional and costs little per year. You can complete the “build a site and publish it online” route by paying only for Claude.

What else do people ask about Astro sites and Claude Code?#

Get to know Ailoot.