# 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](/taskly/beginner/tools-setup/) first.

### Requirements
- **Node.js 22.12.0 or later** (declared in `package.json`)
- **npm**, which comes with Node.js. Taskly 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; Taskly 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 Taskly On Your Computer
<Steps>

1. Unzip the download and find the `taskly` folder: the one that contains `package.json`, `README.md`, and `AGENTS.md`. Move it to wherever you keep your projects, then open it in your code editor.

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>

The theme's `README.md` lists these same commands, where the main files live, and a short checklist for launch.

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

<Aside type="caution" title="Windows: the site never starts">
  `npm run dev` starts two programs at once: a watcher that turns
  `config.toml` into JSON, and the Astro server. In some Windows terminals the
  second one waits for the first, which never ends. If the terminal stops at
  `[toml-watcher] Watching config.toml for changes...`, press <kbd>Ctrl</kbd> +
  <kbd>C</kbd> and run the two parts in two terminals instead:
  `npm run toml:watch -- --watch` in the first, `npx astro dev` in the second.
</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.

Until you set your own address in `config.toml`, the build prints a yellow `[site]` warning when the Astro step finishes: the theme ships with the placeholder `https://example.com`. That is expected on your computer; set the address before you deploy ([Quick Start](/taskly/getting-started/quick-start/), step 1).

<Aside type="note">
  Site search only works on a built site (`npm run preview` or a deploy),
  because the search index is created at the end of `npm run build`. In
  `npm run dev`, the search window tells you so.
</Aside>

### Every Script, In Plain Words
| Command                                 | What it does                                                                                       |
| --------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `npm run dev`                           | Starts the local site with live reload                                                             |
| `npm run build`                         | Builds the production site into `dist/`, creates the search index, and removes drafts from the sitemap. Warns while the site URL is still `https://example.com` |
| `npm run preview`                       | Builds, then serves the production site locally                                                    |
| `npm run astro-check`                   | Checks components and the content files that have a schema (including page blocks) for mistakes. Run it before you deploy |
| `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 sharing image from your logo, colors, tagline, and description           |
| `npm run remove-multilingual`           | Deletes every language except English. Read [Internationalization](/taskly/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](/taskly/customization/internationalization/) |
| `npm run indexnow`                      | Tells search engines which pages changed (after you set `indexNowKey`)                             |
| `npm run deploy:cf`                     | Uploads `dist/` to Cloudflare Pages. Needs Wrangler installed first (see [Deployment](/taskly/deployment/)) |
| `npm run toml:watch`                    | Turns `config.toml` into `.astro/config.generated.json`. `dev`, `build`, and `astro-check` already run it |
| `npm run search-index`                  | Builds the search index from `dist/`. `build` already runs it                                      |
| `npm run remove-draft-from-sitemap`     | Removes drafts and `excludeFromSitemap` pages from the sitemap. `build` already runs it            |

Next: [Quick Start](/taskly/getting-started/quick-start/), to make the site yours in about 30 minutes.