Once Node.js 22.23.4 or newer is installed, an Astro theme runs on your machine in four steps:
- Download the theme:
git clone <repo-url> my-site, ornpm create astro@latest -- --template <user>/<repo>. cd my-sitenpm installnpm run dev, then openhttp://localhost:4321.
Then customize in this order: config files, Markdown content, Tailwind theme variables, and only then components. Commit the untouched theme before you edit anything so you can pull its updates later. To install Astro on its own, without a theme, run npm create astro@latest (details below). This is written for first-time Astro users; we sell themes and point out where ours differ.
What you need before installing a theme
You need three things on your machine:
| Tool | What to install | How to check |
|---|---|---|
| Node.js | v22.23.4 or higher, even-numbered release (Astro does not support odd versions like v23) | node -v |
| Package manager | npm comes with Node. pnpm or yarn are optional | npm -v |
| Git | Needed to clone themes and track your changes | git --version |
Versions checked on November 1, 2026: Astro 7.4.4 requires Node >=22.23.4 in its engines field, and the Astro install docs list the same minimum.
Two practical notes:
- Check the themeโs
package.json. Many themes declare anenginesfield, for example"node": ">=22.0.0". Astroโs own minimum still applies, so meet whichever is higher. - Use the package manager the theme was built with. Look at the lock file in the repository root:
package-lock.jsonmeans npm,pnpm-lock.yamlmeans pnpm,yarn.lockmeans yarn. Using a different one ignores the tested dependency versions.
A code editor with the official Astro extension (available for VS Code and other editors) gives you syntax highlighting and type errors inside .astro files. It is not required, but it catches typos early.
Still choosing a theme? Our Astro starter themes and Astro blog themes lists compare free options, with license and Astro version for each.
How do you install Astro without a theme?
If you want a blank Astro project instead of a theme, run the setup wizard:
npm create astro@latest
It asks where to create the project and which theme to start from, then offers to install dependencies and start a Git repository. Move into the new folder and run npm run dev. The pnpm and Yarn versions of the command are in the Astro install docs. Starting from a theme instead saves you building the header, footer and page layouts yourself, and the rest of this guide covers that route.
Three ways to get the theme onto your computer
There are three common ways. Pick based on whether you want the themeโs Git history.
Option 1: Clone the GitHub repository (best for staying upgradeable)
git clone https://github.com/<github-user>/<repo>.git my-site
cd my-site
You get the full commit history and a remote pointing at the original repository. That remote is what lets you pull theme updates later, so this is the option we recommend for client sites. Paid themes delivered through GitHub repository access work the same way.
Option 2: Use create astro with a theme
npm create astro@latest -- --template <github-user>/<repo>
With pnpm, drop the extra --:
pnpm create astro@latest --template <github-user>/<repo>
To use a branch other than main, add #branch-name to the end of the theme argument. The wizard copies the files, can install dependencies, and can start a fresh Git repository. The catch: the new repository has no link to the themeโs history, so updating later means comparing files by hand.
The wizard asks a few questions. You can answer them with flags instead, which helps in scripts or when you set up several client sites the same way (create-astro flags):
| Flag | What it does |
|---|---|
--template <name> | Start from an official example or a user/repo on GitHub |
--install / --no-install | Install dependencies, or skip it |
--git / --no-git | Start a Git repository, or skip it |
--add <integrations> | Add integrations during setup, for example --add sitemap |
--no-ai | Skip creating AI agent files |
--yes / --no | Accept or decline every default without prompts |
--dry-run | Walk through the steps without changing anything |
For example, npm create astro@latest -- --template <github-user>/<repo> --install --no-git copies the theme and installs dependencies but leaves Git to you, which suits Option 1โs workflow if you then add the original repository as a remote.
Option 3: Download a ZIP
Paid themes are sometimes delivered as a ZIP. Unzip it, open the folder in a terminal, and run git init followed by a first commit straight away (see the upgradeable section below) so you have a clean baseline.
Install dependencies and run the dev server
From the project folder:
npm install
npm run dev
Open http://localhost:4321. Astro uses port 4321 by default for both the dev and preview servers. Edits to pages, components, CSS, and Markdown reload in the browser as you save.
Use the themeโs npm run dev script rather than calling astro dev directly. Some themes do extra work in that script. For example, our themes convert src/config/config.toml into a generated JSON file before Astro starts and keep watching it while you work. Skipping the script can leave that file missing or stale.
Add an integration with astro add
Use astro add instead of editing package.json and astro.config.mjs by hand. It installs the package and updates the config in one step, and it asks before it changes a file:
npx astro add sitemap
npx astro add mdx
It works for official integrations and for community integrations that support the command (Astro install docs). Check the theme first: many already include sitemap, MDX or Tailwind, so look in astro.config.mjs and its integrations array before you add anything.
What each folder in an Astro theme does
Most Astro themes follow the same layout. Once you know what each folder does, you know where to make every change.
| Path | What it holds | Do you edit it? |
|---|---|---|
src/pages/ | Routes. Every .astro, .md, or .mdx file here becomes a URL. Files like [slug].astro generate many pages from data | Rarely, unless adding a new kind of page |
src/layouts/ | Page shells: <head>, header, footer, wrappers | Sometimes |
src/components/ | Reusable UI pieces: cards, buttons, sections | When changing design or structure |
src/content/ | Markdown and MDX content, grouped into collections | Often. This is where your copy lives |
src/content.config.ts | Defines each content collection and validates frontmatter with a schema | Only when adding fields or collections |
src/assets/ | Images and files Astro can optimize | Often |
public/ | Files copied as-is: favicons, robots.txt, images you do not want processed | Sometimes |
astro.config.mjs | Site URL, integrations, i18n, Markdown settings, Vite plugins | Rarely, but set site before launch |
src/styles/ | Global CSS, often including the Tailwind theme | When changing colors or typography |
Folder names vary between themes. In our themes, components live in src/layouts/components/ and site settings live in src/config/. Read the themeโs README or docs once before you start, it takes five minutes and saves an hour.
Where do you change the site name, logo, and metadata?
Look for a config file before searching through components. Common locations are src/config/, src/site.config.ts, or src/consts.ts.
In Getastrothemes themes it is src/config/config.toml:
[site]
title = "Northwind Accounting"
description = "Tax planning and bookkeeping for small businesses in Leeds."
baseUrl = "https://northwind-accounting.com"
logo = "/images/logo.svg"
trailingSlash = true
Change the title, description, base URL, and logo path first. The base URL matters more than it looks: Astro uses the site value in astro.config.mjs (which our themes fill from baseUrl) to build canonical URLs, the sitemap, and Open Graph tags. A theme left on its demo URL will publish the wrong canonical links.
Next, update the menus and social links. In our themes these are src/config/menu.en.json (plus one file per language), src/config/social.json, and for multilingual sites src/config/language.json.
Some settings are read only when the server starts. If a config change does not show up, stop the dev server and run npm run dev again.
How do you change colors and fonts with Tailwind?
Most current Astro themes use Tailwind CSS v4, which moved configuration from tailwind.config.js into CSS. Theme values are CSS variables inside an @theme block, and Tailwind generates utilities from them. A variable named --color-primary gives you bg-primary, text-primary, border-primary, and so on.
Find the file with the @theme block, often src/styles/global.css or a dedicated src/styles/theme.css, and change the values rather than the class names:
@theme {
--color-primary: #0f3d3e;
--color-secondary: #e2f0ee;
--color-accent: #f2a541;
--font-primary: "Inter", sans-serif;
}
Because every component already uses bg-primary or text-accent, one edit rebrands the whole site. Do not search and replace hex codes across components. You will miss some and make updates harder.
You may also see @theme inline. Tailwind uses inline when a theme variable points at another variable, such as a font variable defined elsewhere, so utilities resolve to the correct value. Leave that keyword as it is.
If the theme is still on Tailwind v3, colors live in tailwind.config.js or tailwind.config.mjs under theme.extend.colors. The idea is the same.
Fonts. Themes load fonts in different ways: a Google Fonts link in the layout, self-hosted files, or Astroโs font configuration. Our themes keep font choices in src/config/fonts.json:
{
"name": "Inter",
"variants": [
{ "style": "normal", "weight": "400" },
{ "style": "normal", "weight": "600" }
],
"display": "swap",
"cssVariable": "--font-primary",
"provider": "google",
"subsets": ["latin"],
"fallback": "sans-serif"
}
Change the name and the weights you need, keep the cssVariable the same, and the rest of the theme picks it up. Load only the weights you use. Every extra weight is another file the visitor downloads.
Edit content in Markdown
Open a file in src/content/. The block between the --- lines is frontmatter, structured data the theme reads. Everything below it is the body.
---
title: "Bookkeeping for Small Businesses"
description: "Monthly bookkeeping, payroll, and VAT returns."
draft: false
---
We handle the monthly books so you can focus on clients.
## What is included
- Bank reconciliation
- Payroll
- Quarterly VAT returns
Rules that prevent most beginner errors:
- Keep the same frontmatter fields the file already has.
src/content.config.tsvalidates them, and a missing required field or wrong type stops the build with an error naming the file and field. - Quote strings that contain a colon, and write dates as
2026-01-15. - Use
.mdxonly when you need components inside the content. Plain.mdis simpler.
Many themes also store homepage sections as Markdown files. In our themes, each section (banner, services, call to action) has its own file in src/content/sections/ with an enable: true flag plus its title, text, and buttons. You can rewrite the whole homepage without opening a component.
How do you add a new page?
There are two routes depending on the theme.
Plain Astro file. Create src/pages/about.astro:
---
import Base from "../layouts/Base.astro";
---
<Base title="About us">
<section class="container py-20">
<h1 class="text-primary">About us</h1>
<p>We have helped local businesses with their books since 2012.</p>
</section>
</Base>
It is now live at /about/. Use the layout name your theme actually exports, check the existing pages in src/pages/ and copy their imports.
Content collection page. Many themes generate pages from a collection with a dynamic route such as src/pages/[page].astro. You add a Markdown file instead of a route. In our themes, a new file at src/content/pages/english/accessibility.md with a title in its frontmatter becomes /accessibility/, using the same styling as the Privacy Policy page.
Then add the page to the menu file so visitors can find it.
Replace images without losing optimization
Where an image lives decides whether Astro optimizes it.
| Location | Optimized? | Use for |
|---|---|---|
src/assets/ (imported) | Yes. Resized, converted, and given width and height | Photos, illustrations, most content images |
public/ | No, served exactly as uploaded | Favicons, logos referenced by path, files that need a fixed URL |
In components, import the file and use the Image component:
---
import { Image } from "astro:assets";
import teamPhoto from "../assets/images/team.jpg";
---
<Image src={teamPhoto} alt="Our team at the Leeds office" />
alt is required, and Astro reports an error without it. For an image in public/ or a remote URL, also pass width and height.
In Markdown, use a relative path for images in src () or a root path for images in public ().
The quickest way to swap demo images is to replace each file with your own using the same file name and similar proportions. Nothing else needs to change. If your image has a different aspect ratio, check the layout at mobile and desktop widths afterwards.
Remove sections you donโt need
Start with the least invasive option and only go further if you have to:
- Turn it off in content or config. Many themes have an
enableflag per section or feature. Set it tofalse. - Remove it from the page. Delete the component tag (for example
<Testimonials />) from the page or layout that renders it. Keep the component file for now. - Delete files last. Once the site builds without it, delete the component and its content. Run
npm run buildto confirm nothing else imported it.
The same goes for whole features. Our premium themes ship with English, French and Arabic content, menus, and routing, with Arabic laid out right to left. The free Lite themes ship English and French. If you only need one language, npm run remove-multilingual strips the extra language files and settings in one step, so you do not have to unpick routing by hand. Commit before running it so you can roll back.
Keep your changes upgradeable
Themes get dependency updates, security fixes, and Astro version upgrades. Whether you can take them depends on choices you make on day one.
1. Commit the original theme before any edits.
git add -A
git commit -m "Original theme, untouched"
2. Keep the theme repository as an upstream remote. If you cloned it:
git remote rename origin upstream
git remote add origin https://github.com/<you>/<your-site>.git
git push -u origin main
When the theme releases an update:
git fetch upstream --tags
git merge <release-tag>
Merge a specific release tag rather than whatever is on main, read the changelog first, and do it on a separate branch so you can test before merging into your live site.
3. Put your edits where updates rarely touch them. Config files, content, images, and theme variables are your territory. Components, utilities, and build scripts are the theme authorโs. The more of your work lives in the first group, the fewer merge conflicts you get.
4. When you must change a component, copy it. Create MyHero.astro from Hero.astro and use your copy. The original can then update cleanly.
This is the main reason our themes are config-first: site settings, menus, fonts, social links, and languages each have their own file, and releases are published as GitHub tags with a changelog. Paid themes include repository access, and the changelog for each theme is on its theme page.
Build and preview before you deploy
npm run build
npm run preview
astro build writes the production site to dist/. astro preview serves that output locally on port 4321 so you can check it before deploying. Preview is for checking only, not for running in production. Some themes wire extra steps into these scripts, for example our preview script runs a build first, so read package.json to see what each one does.
Before you deploy, click through the preview and check:
- Every page in the menu loads, including 404
- Page titles and descriptions are yours, not the demoโs
- Images look sharp on mobile and desktop
- Forms post to your own endpoint, not a placeholder
site/ base URL is your real domain
Deployment differs by host. For Cloudflare, see our guide to deploying Astro on Cloudflare.
Common errors and their fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| Install fails or Astro says the Node version is unsupported | Node too old, or an odd-numbered release | Install a current even-numbered Node release (22.23.4+), then reinstall |
Cannot find module after pulling changes | Dependencies changed | Run npm install again |
| Build fails with a content or frontmatter error | A required field is missing or has the wrong type | Read the file and field named in the error, compare with src/content.config.ts |
| Image import error | Wrong relative path or file name case | Check the path from the current file. Linux hosts are case-sensitive even if your Mac is not |
alt missing error | Image used without alt text | Add a descriptive alt, or alt="" for decorative images |
| Config change has no effect | Value read only at startup | Restart npm run dev |
| New Tailwind class does nothing | Class built from a string at runtime, or theme variable misspelled | Write full class names in your markup and check the variable name in @theme |
| Editor shows type errors for collections | Generated types are stale | Run npx astro sync, or restart the dev server |
| Works in dev, broken after build | Dev and production differ (paths, trailing slashes, env variables) | Always test with npm run build and npm run preview before deploying |
If you are stuck, the themeโs docs and issue tracker usually have the answer, and npm run astro -- check reports type and theme errors across the whole project.
Where to go next
If you are new to Astro, practice on a free theme before customizing a client site. Our MIT licensed Lite themes, Folex Lite, Techlo Lite, and Lumio Lite, use the same config-first structure as the premium versions, so everything in this guide applies. Browse all of them on the free Astro themes page, or see our roundup of Astro starter themes.
When you are ready for a full business site, the premium themes add more pages, sections, and homepage variants for specific industries. Compare them on the themes page, check what you can build under each plan on the license page, or get every theme with the All Access Pass, from $99. If you want help from an AI assistant while you customize, read how to build an Astro website with AI coding tools.