# How to Set Up Hallmark AI for Local Development: A Complete Guide

> Learn how to set up Hallmark AI for local development by cloning the repository, installing dependencies with pnpm, and running the dev server. Get started quickly.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-07-25

---

**Setting up Hallmark AI locally requires cloning the repository, installing dependencies with **pnpm**, copying `.env.example` to `.env`, and running `pnpm dev` to start the Vite development server on `localhost:3000`.**

Hallmark AI is a web-based design system built on modern Node.js tooling. Whether you are customizing UI components or extending core utilities, configuring a local development environment starts with understanding the project structure in the `Nutlope/hallmark` repository. This guide provides the exact commands and file paths needed to get the application running on your machine.

## Prerequisites and System Requirements

Before installing Hallmark AI, ensure your system meets the baseline requirements. The project requires **Node.js** version 18 or higher (LTS recommended) and uses **pnpm** as its primary package manager for faster, disk-space-efficient dependency management.

If you do not have pnpm installed globally, install it via npm:

```bash
npm i -g pnpm

```

## Step-by-Step Local Installation

### Clone the Repository

Download the source code from GitHub and navigate into the project directory. The root contains the main [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) configuration and the `site/` folder which houses the client-side application entry points.

```bash
git clone https://github.com/Nutlope/hallmark.git
cd hallmark

```

### Install Project Dependencies

Run the install command to download all JavaScript packages listed in [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json). This step also creates the lockfile ensuring consistent dependency versions across environments.

```bash
pnpm install

```

### Configure Environment Variables

Hallmark AI uses optional environment variables for external service integration. Copy the example configuration file to create your local environment:

```bash
cp .env.example .env

```

Open `.env` in your editor to review the placeholders. If you are not connecting to external APIs, you can leave the default values as-is. The repository maintains the template at `.env.example` in the project root.

### Start the Development Server

Launch the Vite-powered development server to serve the application. This command reads [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) as the base template and bundles [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) as the client-side entry point.

```bash
pnpm dev

```

The terminal will display the local URL (typically `http://localhost:3000`). Changes to source files trigger instant hot-module replacement via the Vite configuration.

## Build and Test the Application

### Create a Production Build

To verify the production bundle or test static file generation, compile the project into the `dist/` directory:

```bash
pnpm build

```

This process optimizes assets and outputs deployable files based on the settings in your Vite configuration.

### Preview the Production Build

Serve the built files locally to test the production environment before deployment:

```bash
pnpm preview

```

### Run the Test Suite

Hallmark AI includes tests for core components and utilities located in the `site/_tests` directory. Execute the test runner with:

```bash
pnpm test

```

This command runs the Jest or Vitest suite configured in the project to validate utility functions and component logic.

## Optional Development Tools

Maintain code quality using the built-in linting and formatting scripts defined in [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json):

- **Linting**: Run `pnpm lint` to execute ESLint across the codebase and catch syntax or style errors.
- **Formatting**: Run `pnpm format` to apply Prettier rules and standardize code formatting automatically.

## Summary

- **Clone** the `Nutlope/hallmark` repository and enter the directory.
- **Install** dependencies using `pnpm install` after ensuring Node.js ≥ 18 is installed.
- **Configure** environment variables by copying `.env.example` to `.env`.
- **Develop** using `pnpm dev`, which serves [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) and bundles [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) via Vite on `localhost:3000`.
- **Build** production assets with `pnpm build` and verify with `pnpm preview`.
- **Test** functionality by running `pnpm test` against the `site/_tests` suite.

## Frequently Asked Questions

### What Node.js version is required for Hallmark AI?

Hallmark AI requires **Node.js version 18 or higher** (LTS preferred). The build system and Vite configuration rely on modern JavaScript features available in recent Node releases.

### Do I need to fill in the `.env` file before starting development?

No. If you are not using external API services, you can leave the placeholder values in `.env` as they are. The application will run with default local settings, though some features requiring API keys may be limited.

### How do I run the test suite locally?

Execute `pnpm test` from the project root. This command runs the test runner against files in the `site/_tests` directory, validating core utilities and component behavior.

### What is the difference between `pnpm dev` and `pnpm preview`?

`pnpm dev` starts the **Vite development server** with hot-module replacement, reading directly from source files like [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js). `pnpm preview` serves the **static production build** generated in the `dist/` folder by `pnpm build`, simulating the deployed environment.