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

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:

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 configuration and the site/ folder which houses the client-side application entry points.

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. This step also creates the lockfile ensuring consistent dependency versions across environments.

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:

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 as the base template and bundles site/js/main.js as the client-side entry point.

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:

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:

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:

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:

• 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 and bundles 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. pnpm preview serves the static production build generated in the dist/ folder by pnpm build, simulating the deployed environment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}