Black Friday: 50% off Pro All Access until Nov 30
All articles
Guides 11 min read

How to Install an Astro Theme and Customize It (2026)

Install Astro or an Astro theme with npm create astro or git clone on Node 22.23.4+, then change colors, fonts, content and images without breaking updates.

Published

Updated

On this page

Once Node.js 22.23.4 or newer is installed, an Astro theme runs on your machine in four steps:

  1. Download the theme: git clone <repo-url> my-site, or npm create astro@latest -- --template <user>/<repo>.
  2. cd my-site
  3. npm install
  4. npm run dev, then open http://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:

ToolWhat to installHow to check
Node.jsv22.23.4 or higher, even-numbered release (Astro does not support odd versions like v23)node -v
Package managernpm comes with Node. pnpm or yarn are optionalnpm -v
GitNeeded to clone themes and track your changesgit --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 an engines field, 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.json means npm, pnpm-lock.yaml means pnpm, yarn.lock means 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):

FlagWhat it does
--template <name>Start from an official example or a user/repo on GitHub
--install / --no-installInstall dependencies, or skip it
--git / --no-gitStart a Git repository, or skip it
--add <integrations>Add integrations during setup, for example --add sitemap
--no-aiSkip creating AI agent files
--yes / --noAccept or decline every default without prompts
--dry-runWalk 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.

PathWhat it holdsDo you edit it?
src/pages/Routes. Every .astro, .md, or .mdx file here becomes a URL. Files like [slug].astro generate many pages from dataRarely, unless adding a new kind of page
src/layouts/Page shells: <head>, header, footer, wrappersSometimes
src/components/Reusable UI pieces: cards, buttons, sectionsWhen changing design or structure
src/content/Markdown and MDX content, grouped into collectionsOften. This is where your copy lives
src/content.config.tsDefines each content collection and validates frontmatter with a schemaOnly when adding fields or collections
src/assets/Images and files Astro can optimizeOften
public/Files copied as-is: favicons, robots.txt, images you do not want processedSometimes
astro.config.mjsSite URL, integrations, i18n, Markdown settings, Vite pluginsRarely, but set site before launch
src/styles/Global CSS, often including the Tailwind themeWhen 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.ts validates 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 .mdx only when you need components inside the content. Plain .md is 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.

LocationOptimized?Use for
src/assets/ (imported)Yes. Resized, converted, and given width and heightPhotos, illustrations, most content images
public/No, served exactly as uploadedFavicons, 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 (![Office](../../assets/images/office.jpg)) or a root path for images in public (![Office](/images/office.jpg)).

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:

  1. Turn it off in content or config. Many themes have an enable flag per section or feature. Set it to false.
  2. 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.
  3. Delete files last. Once the site builds without it, delete the component and its content. Run npm run build to 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

SymptomLikely causeFix
Install fails or Astro says the Node version is unsupportedNode too old, or an odd-numbered releaseInstall a current even-numbered Node release (22.23.4+), then reinstall
Cannot find module after pulling changesDependencies changedRun npm install again
Build fails with a content or frontmatter errorA required field is missing or has the wrong typeRead the file and field named in the error, compare with src/content.config.ts
Image import errorWrong relative path or file name caseCheck the path from the current file. Linux hosts are case-sensitive even if your Mac is not
alt missing errorImage used without alt textAdd a descriptive alt, or alt="" for decorative images
Config change has no effectValue read only at startupRestart npm run dev
New Tailwind class does nothingClass built from a string at runtime, or theme variable misspelledWrite full class names in your markup and check the variable name in @theme
Editor shows type errors for collectionsGenerated types are staleRun npx astro sync, or restart the dev server
Works in dev, broken after buildDev 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.

Frequently asked questions

Do I need to know JavaScript to customize an Astro theme?

Not for most changes. Site name, menus, colors, fonts, and page text usually live in config files, CSS variables, and Markdown. You need basic HTML and component knowledge when you want to change layouts or build new sections.

Which Node.js version should I use for Astro?

Use an even-numbered Node.js release at v22.23.4 or higher. That is the minimum in the engines field of Astro 7.4.4 on npm and on the Astro install page, both checked on November 1, 2026. Odd-numbered versions such as v23 are not supported. Check the theme's package.json engines field too.

Should I use npm, pnpm, or yarn?

Use the package manager the theme ships a lock file for. If you see package-lock.json, use npm. If you see pnpm-lock.yaml, use pnpm. Mixing them creates a second lock file and can install different dependency versions.

Can I update a theme after I have customized it?

Yes, if you planned for it. Commit the untouched theme first, keep the original repository as an upstream remote, and keep most of your edits in config, content, and CSS variables. Then you can merge a new release and resolve a small number of conflicts.

Why do my images look blurry or load slowly?

Images in the public folder are served as-is and never optimized by Astro. Put images in src, import them, and render them with the Image component from astro:assets so Astro can resize and convert them at build time.

What is the difference between npm run dev and npm run preview?

The dev server is for editing and reloads as you save. Preview serves the production build from dist so you can check the real output before deploying. Always preview once before you ship.

Share this article

Every premium theme.
Future releases included. $99.

Premium theme collection preview
Premium theme collection preview