Install Halite

The create halite CLI command is the quickest way to start a new Halite project from scratch. It walks you through every step and lets you choose from a few official starter templates.

You can also run the CLI with the --template flag to begin from any existing theme or starter. Browse our themes and starters for blogs, portfolios, docs and landing pages.

To set a project up by hand instead, see the manual setup below.

Prerequisites

• Node.js — v22.12.0 or higher. Odd-numbered versions like v23 are not supported.

• Text editor — we recommend VS Code with the official Halite extension.

• Terminal — Halite is driven from its command-line interface.

Browser compatibility

Halite is built on Vite, which targets browsers with modern JavaScript support by default.

Install from the CLI wizard

You can run create halite anywhere on your machine; there is no need to make an empty folder first.

1. Run the wizard

   Run the following command in your terminal to start the install wizard:

   • npm
   • pnpm
   • Yarn

   # create a new project with npm
   npm create halite@latest

   If all goes well you will see a success message followed by some recommended next steps.

2. Move into the project

   Now that your project exists, cd into the new project directory to start using Halite.

3. Install dependencies

   If you skipped the "Install dependencies?" step during the wizard, install them before continuing.

   • npm
   • pnpm
   • Yarn

   npm install

4. Start the dev server

   You can now start the Halite dev server and see a live preview while you build.

CLI installation flags

You can pass flags to create halite to customise setup — answering yes to everything, skipping git, or adding integrations.

Add integrations

Start a project and add any official integration that supports halite add in one go with --add:

# create a new project with Vue and a sitemap
npm create halite@latest -- --add vue --add sitemap

# create a new project with Vue and a sitemap
pnpm create halite@latest --add vue --add sitemap

# create a new project with Vue and a sitemap
yarn create halite --add vue --add sitemap

Use a theme or starter template

# create a new project from an official example
npm create halite@latest -- --template <example-name>

# create a new project from an official example
pnpm create halite@latest --template <example-name>

# create a new project from an official example
yarn create halite --template <example-name>

Manual setup

1. Create your directory

   Create an empty directory with the name of your project and move into it.

   mkdir my-halite-site
   cd my-halite-site

2. Install Halite

   Important

   Halite must be installed locally, not globally. Make sure you are not running npm install -g halite.

   • npm
   • pnpm
   • Yarn

   npm install halite

   Then replace any placeholder scripts in your package.json:

   {
     "scripts": {
       "dev": "halite dev",
       "build": "halite build",
       "preview": "halite preview"
     }
   }

3. Create your first page

   Create src/pages/index.hal. Every file in src/pages/ becomes a route.

   ---
   const title = 'Hello, world';
   ---
   <h1>{title}</h1>