Getting Started

Install and run HeartCo in 5 minutes.

Prerequisites

Important: HeartCo uses pnpm exclusively. Neither npm nor yarn are supported.

Installation

1. Clone the project

git clone https://github.com/your-org/heartco.git
cd heartco

2. Install dependencies

pnpm install

3. Configure environment variables

cp .env.example .env

Open .env and fill in the 3 essential variables to get started:

# Database (Supabase PostgreSQL)
DATABASE_URL="postgresql://postgres:[PASSWORD]@db.[PROJECT].supabase.co:6543/postgres?pgbouncer=true"
DIRECT_URL="postgresql://postgres:[PASSWORD]@db.[PROJECT].supabase.co:5432/postgres"
 
# Authentication (generate with: openssl rand -base64 32)
AUTH_SECRET="your-secret-min-32-chars"

The other variables (public URLs, Stripe, Resend, OAuth, AI, etc.) fall back to sensible defaults in dev (http://localhost:3000) or are entirely optional. Sending emails, Google/Microsoft OAuth and Stripe payments require the corresponding keys — see Deployment for production.

Advanced integrations (Stripe Price IDs for plans/modules/bundles, Iopole, Bridge, Mistral, Sentry, Hotjar/PostHog, Google/Microsoft calendars, etc.) are documented separately in apps/web/.env.integrations.example. Copy only the sections you need into your .env.

4. Prepare the database and demo data

pnpm setup

This command orchestrates:

1. prisma generate — generates the Prisma client in generated/prisma/
2. prisma migrate dev — applies all migrations
3. prisma db seed — populates the database with org + users + demo data

Without this step, the dashboard will be empty and login impossible.

5. Start the development server

pnpm dev

The server starts on http://localhost:3000 with Turbopack.

Verification

Once the server is running, check that everything works:

1. Home page: http://localhost:3000 — HeartCo landing page
2. Login: http://localhost:3000/login — Sign-in page
3. Register: http://localhost:3000/register — Account creation
4. Dashboard: http://localhost:3000/dashboard — (after signing in)

Demo accounts

After pnpm setup, the following accounts are available to sign in:

Useful commands

pnpm setup            # Generate + migrate + seed (first setup or reset)
pnpm dev              # Dev server (Turbopack)
pnpm build            # Production build
pnpm lint             # Check the code (ESLint)
pnpm lint:fix         # Auto-fix
pnpm typecheck        # Check TypeScript types
pnpm test             # Run the tests (Vitest)
pnpm format:write     # Format the code (Prettier)
npx prisma studio     # Graphical DB browser

Project structure

heartco/
├── docs/                  # This documentation
├── prisma/
│   ├── schema.prisma      # Database schema
│   └── migrations/        # SQL migrations
├── generated/prisma/      # Generated Prisma client
├── src/
│   ├── app/               # Pages (App Router)
│   ├── components/        # React components
│   ├── lib/               # Utilities and configuration
│   ├── modules/           # Business modules (facturx, iopole, bridge)
│   ├── server/            # tRPC API + authentication
│   └── styles/            # Global CSS
├── e2e/                   # E2E tests (Playwright)
├── packages/              # Shared packages (ui, shared, mobile-core)
└── packages/              # Shared packages (monorepo)

For a detailed view of the architecture, see Architecture.

Common issues

EPERM on Windows (Prisma DLL)

If you get an EPERM error during prisma generate:

Error: EPERM: operation not permitted, unlink 'generated/prisma/query_engine-windows.dll.node'

Solution: Stop the development server (Ctrl+C), re-run npx prisma generate, then restart pnpm dev.

Port 3000 already in use

# Find the process
lsof -i :3000
# Or on Windows
netstat -ano | findstr :3000

Prisma migration errors

If migrations fail:

npx prisma migrate reset    # Recreates the DB (WARNING: data loss)
npx prisma migrate dev      # Re-applies the migrations

Next steps

• Architecture — Understand the project structure
• Authentication — Configure the OAuth providers
• Customization — Adapt the branding to your project

Contents · Architecture ▶