Skip to main content
This guide will help you set up Hiro CRM for local development.

​
Prerequisites

Before you begin, ensure you have:

​
Optional Tools

  • OpenAI API Key — For AI Assistant features
  • Brevo Account — For email/SMS campaign testing
  • Supabase CLI — For database migrations

​
Installation

1

Clone your fork

First, fork the repository on GitHub, then clone it:
git clone https://github.com/your-username/hiro-crm.git
cd hiro-crm
2

Navigate to frontend directory

The main application code is in the frontend/ directory:
cd frontend
3

Install dependencies

Install all required npm packages:
npm install
This will install Next.js, React, TypeScript, Supabase client, and all development dependencies.
4

Configure environment variables

Copy the environment template:
cp .env.example .env.local
Edit .env.local and fill in your Supabase credentials:
# Required
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
NEXT_PUBLIC_APP_URL=http://localhost:3000
5

Set up the database

You need to apply the database schema to your Supabase project.Option A: Using Supabase CLI (recommended)
# Install Supabase CLI globally
npm install -g supabase

# Link to your project
supabase link --project-ref your-project-ref

# Apply migrations
supabase db push
Option B: Manual via Supabase Dashboard
  1. Go to your Supabase project dashboard
  2. Navigate to SQL Editor
  3. Run the migration files from supabase/migrations/ in order
6

Seed demo data (optional)

To get started with sample data:
# Start the dev server first
npm run dev

# In another terminal, seed locations
curl http://localhost:3000/api/admin/seed-locations
For a full demo dataset with customers and reservations, run supabase/seeds/demo.sql in the Supabase SQL editor.
7

Start the development server

npm run dev
The app will be available at http://localhost:3000.

​
Environment Variables Reference

Here’s a complete breakdown of environment variables:

​
Required Variables

VariableDescription
NEXT_PUBLIC_SUPABASE_URLYour Supabase project URL
NEXT_PUBLIC_SUPABASE_ANON_KEYSupabase anonymous (public) key
SUPABASE_SERVICE_ROLE_KEYSupabase service role key (keep secret!)
NEXT_PUBLIC_APP_URLApplication URL (http://localhost:3000 for dev)

​
Optional Variables

VariableDescriptionFeature
OPENAI_API_KEYOpenAI API keyAI Assistant
BREVO_API_KEYBrevo API keyEmail & SMS campaigns
BREVO_SENDER_EMAILSender email addressEmail campaigns
BREVO_SENDER_NAMESender nameEmail campaigns
BREVO_SMS_SENDERSMS sender IDSMS campaigns
COVERMANAGER_API_KEYCoverManager API keyPOS integration
REVO_ACCESS_TOKENRevo POS access tokenRevo integration
INNGEST_EVENT_KEYInngest event keyBackground workflows
INNGEST_SIGNING_KEYInngest signing keyBackground workflows
GOOGLE_DRIVE_CLIENT_IDGoogle OAuth client IDDocument library
GOOGLE_DRIVE_CLIENT_SECRETGoogle OAuth secretDocument library
GOOGLE_DRIVE_REFRESH_TOKENGoogle refresh tokenDocument library
SENTRY_DSNSentry DSNError tracking
NEXT_PUBLIC_SENTRY_DSNSentry public DSNClient-side errors
Never commit .env.local to version control! It contains sensitive credentials.

​
Verification

Verify your setup is working: 
# Check TypeScript compilation
npm run type-check

# Run tests
npm run test:run

# Build for production (optional)
npm run build

​
Project Structure

Understanding the codebase: 
frontend/
├── app/                    # Next.js App Router
│   ├── (auth)/            # Authentication pages
│   ├── (dashboard)/       # Main app pages
│   ├── api/               # API routes
│   └── layout.tsx         # Root layout
├── components/            # React components
│   ├── ui/               # Reusable UI components
│   └── [feature]/        # Feature-specific components
├── lib/                   # Core libraries
│   ├── supabase/         # Supabase client & queries
│   ├── actions/          # Server actions
│   └── utils/            # Utility functions
├── hooks/                 # Custom React hooks
├── context/               # React context providers
├── types/                 # TypeScript type definitions
├── tests/                 # Test files
│   ├── unit/             # Unit tests
│   ├── integration/      # Integration tests
│   └── setup.ts          # Test configuration
├── e2e/                   # Playwright E2E tests
└── public/                # Static assets

​
Common Development Tasks

​
Running the app with Turbopack disabled

npm run dev:webpack

​
Type checking

npm run type-check

​
Running linter

npm run lint

​
Cleaning build artifacts

npm run clean

​
Creating a test user

npm run create:user

​
Troubleshooting

​
Port 3000 already in use

Change the port in your start command: 
PORT=3001 npm run dev
Update NEXT_PUBLIC_APP_URL in .env.local accordingly.

​
Supabase connection errors

  • Verify your Supabase URL and keys in .env.local
  • Check that your Supabase project is active
  • Ensure RLS policies are set up correctly

​
TypeScript errors

Clear the Next.js cache: 
npm run clean
rm -rf node_modules/.cache
npm run dev

​
Module not found errors

Reinstall dependencies: 
rm -rf node_modules package-lock.json
npm install

​
Next Steps

Code Standards

Learn our coding conventions

Testing Guide

Write and run tests

Build docs developers (and LLMs) love

Get started for freeTalk to us