Installation

Installation Guide

Skill level: Beginner · Time: 10 minutes

You need two things on your computer: Node.js (the program that runs the theme) and a code editor to open the files. If you have never used a terminal before, read Tools You Need first.

Requirements

Node.js 22.12 or later (engines in package.json)
npm, which comes with Node.js. Homio ships a package-lock.json, so use npm rather than Yarn or pnpm
A code editor. VS Code is a good free choice; Homio recommends its Astro, TOML, and Tailwind CSS extensions when you open the folder

Install Node.js

Download the LTS installer from nodejs.org and run it. Then open PowerShell and check the version:

node -v

Download the installer from nodejs.org, or use Homebrew:

brew install node
node -v

Install Node.js with your package manager or the official installer, then check the version:

node -v

The result must be v22.12.0 or higher.

Run Homio On Your Computer

Unzip the download and move the theme folder to wherever you keep your projects. Open it in your code editor. It is the folder that contains package.json and AGENTS.md.
Open a terminal inside that folder. In VS Code, use Terminal → New Terminal.
Install the dependencies (only needed once, and again after updates):
Terminal window
```
npm ci
```
npm ci installs the exact versions listed in package-lock.json. npm install works too.
Start the development server:
Terminal window
```
npm run dev
```
Open http://localhost:4321/ in your browser.

Leave the terminal running while you work. When you save a file, including src/config/config.toml, the browser updates on its own. Press Ctrl + C in the terminal to stop the server.

On Windows: start the dev server in two terminals

npm run dev starts two programs at once with &: a watcher that converts config.toml, and Astro. The Windows command prompt runs them one after the other instead, so the watcher starts and Astro never does. If http://localhost:4321/ doesn’t open, stop it with Ctrl + C and use two terminals instead (Terminal → New Terminal twice):

# Terminal 1: converts config.toml every time you save it
npm run toml:watch -- --watch

# Terminal 2: the local site
npx astro dev

Every other script works the same on Windows, macOS, and Linux.

Build And Preview The Production Site

npm run build
npm run preview

npm run build writes the finished site to the dist/ folder. npm run preview builds it again and serves it at http://localhost:4321/, so you can test it exactly as visitors will see it.

On a fresh copy, the build prints two kinds of yellow warnings. Both are expected on your computer, and both tell you what to set before you deploy:

[site]: the site URL is still the placeholder https://example.com (Quick Start, step 1).
[forms]: a form still posts to a placeholder address (Quick Start, step 8).

Every Script, In Plain Words

Command	What it does
`npm run dev`	Starts the local site with live reload, and converts `config.toml` each time you save it. On Windows, see the note above
`npm run build`	Builds the production site into `dist/` and removes drafts from the sitemap. Warns while the site URL or a form address is still a placeholder
`npm run preview`	Builds, then serves the production site locally
`npm run astro-check`	Runs `check-i18n`, then checks components and the content files that have a schema for mistakes. It doesn’t check section files or the contact page file. Run it before you deploy
`npm run check-i18n`	Checks that English and French have the same interface strings, menus, and content files
`npm run format`	Tidies the formatting of files in `src/`
`npm run generate-favicons`	Creates every favicon size from `[site.favicon] image` in `config.toml`
`npm run generate-og-image`	Redraws the shared social image (`[opengraph] image`) with your logo, tagline, and description. Run it after you change them
`npm run remove-multilingual`	Deletes every language except English. Read Internationalization first
`npm run generate-multilingual-content`	Creates French from the English content and overwrites the existing French files. Don’t use it to add a language: see Internationalization
`npm run remove-draft-from-sitemap`	Removes draft pages from the built sitemap. `build` already runs it
`npm run indexnow`	Tells Bing and other IndexNow search engines which pages changed. Needs `[seo.ai] indexNowKey` and a deployed site (see Deployment)
`npm run deploy:cf`	Uploads `dist/` to Cloudflare Pages. Needs Wrangler installed first (see Deployment)
`npm run toml:watch`	Turns `config.toml` into `.astro/config.generated.json`. `dev`, `build`, `astro-check`, `generate-og-image`, and `indexnow` already run it

Next: Quick Start, to make the site yours in about 30 minutes.