# 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](/homio/beginner/tools-setup/) 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](https://code.visualstudio.com/) is a good free choice; Homio recommends its Astro, TOML, and Tailwind CSS extensions when you open the folder

### Install Node.js
<Tabs>
  <TabItem label="Windows">

    Download the **LTS** installer from [nodejs.org](https://nodejs.org/en/download/) and run it. Then open **PowerShell** and check the version:

    ```bash
    node -v
    ```

  </TabItem>
  <TabItem label="macOS">

    Download the installer from [nodejs.org](https://nodejs.org/en/download/), or use Homebrew:

    ```bash
    brew install node
    node -v
    ```

  </TabItem>
  <TabItem label="Linux">

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

    ```bash
    node -v
    ```

  </TabItem>
</Tabs>

The result must be `v22.12.0` or higher.

### Run Homio On Your Computer
<Steps>

1. 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`.

2. Open a terminal **inside that folder**. In VS Code, use **Terminal → New Terminal**.

3. Install the dependencies (only needed once, and again after updates):

   ```bash
   npm ci
   ```

   `npm ci` installs the exact versions listed in `package-lock.json`. `npm install` works too.

4. Start the development server:

   ```bash
   npm run dev
   ```

5. Open [http://localhost:4321/](http://localhost:4321/) in your browser.

</Steps>

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

<Aside type="caution" title="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 <kbd>Ctrl</kbd> +
  <kbd>C</kbd> and use two terminals instead (**Terminal → New Terminal** twice):

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

  ```bash
  # Terminal 2: the local site
  npx astro dev
  ```

  Every other script works the same on Windows, macOS, and Linux.
</Aside>

<Aside type="note" title="When to restart npm run dev">
  `npm run dev` watches `config.toml`: when you save it, the terminal prints
  `[toml-watcher] ✓ Generated` and the page reloads. Restart the server
  (<kbd>Ctrl</kbd> + <kbd>C</kbd>, then `npm run dev`) after you change
  `trailingSlash` or anything under `[settings.multilingual]`, after you add a
  language, and after you change `src/config/fonts.json`: Astro reads those
  only when it starts. If a saved `config.toml` change doesn't show and the
  terminal printed no `Generated` line, restart.
</Aside>

### Build And Preview The Production Site
```bash
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/](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](/homio/getting-started/quick-start/), step 1).
- `[forms]`: a form still posts to a placeholder address ([Quick Start](/homio/getting-started/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](/homio/customization/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](/homio/customization/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](/homio/deployment/)) |
| `npm run deploy:cf`                     | Uploads `dist/` to Cloudflare Pages. Needs Wrangler installed first (see [Deployment](/homio/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](/homio/getting-started/quick-start/), to make the site yours in about 30 minutes.