# How to Install an Astro Theme and Customize It (2026) > Install Node.js 22.23.4 or newer, clone the theme or run npm create astro@latest -- --template user/repo, then npm install and npm run dev. Customize through config files, Markdown content, and Tailwind theme variables before touching components, and commit the original theme first so you can pull updates later. Canonical page: [https://getastrothemes.com/blog/install-customize-astro-theme/](https://getastrothemes.com/blog/install-customize-astro-theme/) - Author: Bektur Aslan - Published: 2026-10-23 - Updated: 2026-11-15 - Categories: Guides ## Faq ### Faq 1 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. #### Question Do I need to know JavaScript to customize an Astro theme? ### Faq 2 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. #### Question Which Node.js version should I use for Astro? ### Faq 3 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. #### Question Should I use npm, pnpm, or yarn? ### Faq 4 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. #### Question Can I update a theme after I have customized it? ### Faq 5 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. #### Question Why do my images look blurry or load slowly? ### Faq 6 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. #### Question What is the difference between npm run dev and npm run preview? 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 my-site`, or `npm create astro@latest -- --template /`. 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](#how-do-you-install-astro-without-a-theme)). 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](https://docs.astro.build/en/install-and-setup/) 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](https://getastrothemes.com/blog/astro-starter-templates/) and [Astro blog themes](https://getastrothemes.com/blog/astro-blog-templates/) 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: ```bash 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](https://docs.astro.build/en/install-and-setup/). 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) ```bash git clone https://github.com//.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 ```bash npm create astro@latest -- --template / ``` With pnpm, drop the extra `--`: ```bash pnpm create astro@latest --template / ``` 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](https://github.com/withastro/astro/tree/main/packages/create-astro)): | Flag | What it does | | ---------------------------- | ---------------------------------------------------------- | | `--template ` | 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 ` | 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 / --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: ```bash 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: ```bash npx astro add sitemap npx astro add mdx ``` It works for official integrations and for community integrations that support the command ([Astro install docs](https://docs.astro.build/en/install-and-setup/)). 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: ``, 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`: ```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: ```css @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`: ```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. ```md --- 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`: ```astro --- import Base from "../layouts/Base.astro"; ---

About us

We have helped local businesses with their books since 2012.

``` 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: ```astro --- import { Image } from "astro:assets"; import teamPhoto from "../assets/images/team.jpg"; --- 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](https://getastrothemes.com/assets/images/office.jpg)`) or a root path for images in `public` (`![Office](https://getastrothemes.com/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 ``) 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.** ```bash git add -A git commit -m "Original theme, untouched" ``` **2. Keep the theme repository as an upstream remote.** If you cloned it: ```bash git remote rename origin upstream git remote add origin https://github.com//.git git push -u origin main ``` When the theme releases an update: ```bash git fetch upstream --tags git merge ``` 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 ```bash 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](https://getastrothemes.com/blog/deploy-astro-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](https://getastrothemes.com/astro-themes/folex-lite/), [Techlo Lite](https://getastrothemes.com/astro-themes/techlo-lite/), and [Lumio Lite](https://getastrothemes.com/astro-themes/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](https://getastrothemes.com/free-astro-themes-templates/#free-templates), or see our roundup of [Astro starter themes](https://getastrothemes.com/blog/astro-starter-templates/). 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](https://getastrothemes.com/themes/), check what you can build under each plan on the [license page](https://getastrothemes.com/license/), or get every theme with the [All Access Pass](https://getastrothemes.com/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](https://getastrothemes.com/blog/build-astro-website-with-ai-coding-tools/).