Installation

Get started with HazelJS in minutes. Choose the installation method that works best for your setup.

Quick Start

For most users, installing via npm is the fastest way to get started:

npm install -g @hazeljs/cli

📋Prerequisites

Before installing HazelJS, ensure you have the following installed on your system:

🟢

Node.js

Version 18.x or later

node --version
📦

npm

Version 9.x or later

npm --version
🔧

Git

Optional, for development

git --version

Note: If you don't have Node.js installed, visit nodejs.org to download and install it. We recommend using Node.js 20 LTS for the best experience.

🚀Installation Methods

📦

Using npm (Recommended)

Works on all platforms

The easiest and most common way to install HazelJS is through npm. This method works on Windows, macOS, and Linux.

Install the CLI globally:

npm install -g @hazeljs/cli

This installs the HazelJS command-line interface globally, making it available from any directory.

Or install in your project:

npm install @hazeljs/core

Install HazelJS as a project dependency for a specific application.

Install specific packages:

npm install @hazeljs/core @hazeljs/ai @hazeljs/auth
npm install @hazeljs/cache @hazeljs/prisma

Install only the packages you need for your project.

🍺

Using Homebrew (macOS)

macOS and Linux only

If you're on macOS or Linux and use Homebrew, you can install HazelJS with a single command.

Install via Homebrew:

brew install hazeljs

This installs the latest stable version of HazelJS CLI.

Note: If you don't have Homebrew installed, install it from brew.sh

🔨

Building from Source

For developers and contributors

Build HazelJS from source if you want to contribute, customize, or use the latest development version.

Step 1: Clone the repository

git clone https://github.com/hazeljs/hazeljs.git

Step 2: Navigate to the project directory

cd hazeljs

Step 3: Install dependencies

npm install

This installs all dependencies for the monorepo, including all packages.

Step 4: Build the project

npm run build

Compiles TypeScript and builds all packages in the monorepo.

Step 5: Link the CLI (optional)

npm link

Makes the CLI available globally for development.

✅Verifying Installation

After installation, verify that HazelJS is installed correctly:

Check CLI version:

hazeljs --version

This should display the installed version number, for example: v0.2.0

Check available commands:

hazeljs --help

Lists all available CLI commands and options.

🎯Creating Your First Project

Once HazelJS is installed, create a new project:

Create a new HazelJS application:

hazeljs new my-app

This creates a new directory with a complete HazelJS project structure.

Navigate to your project:

cd my-app

Start the development server:

npm run dev

Your application will be available at http://localhost:3000

📚Next Steps

Now that you have HazelJS installed, explore these resources to get started:

🎮

Controllers Guide

Learn how to create controllers, handle routing, and process requests in HazelJS.

💉

Providers Guide

Understand dependency injection, services, and how to create reusable providers.

📦

Packages

Explore all available HazelJS packages: AI, Auth, Cache, Prisma, and more.

⚡

Serverless Guide

Deploy your HazelJS applications to AWS Lambda and other serverless platforms.

🔧Troubleshooting

Permission Errors (npm install -g)

If you encounter permission errors when installing globally, try:

sudo npm install -g @hazeljs/cli

Or configure npm to use a different directory for global packages.

Command Not Found

If the hazeljs command is not found:

  • Verify npm global bin directory is in your PATH
  • Restart your terminal after installation
  • Check installation with: npm list -g @hazeljs/cli

Version Conflicts

If you have multiple Node.js versions installed, ensure you're using the correct one:

nvm use 20

Or use nvm or n to manage Node.js versions.

Need Help?

If you encounter any issues during installation, we're here to help:

📝 Check GitHub Issues💬 Join Discord Community📚 Browse Documentation