Aller au contenu principal
HeartCoHeartCo/Documentation
FREN

FAQ

Frequently asked questions about HeartCo Starter.

Installation and configuration

Can I use npm or yarn instead of pnpm?

No. HeartCo uses pnpm (version 9.x) exclusively. The project is set up as a pnpm monorepo with pnpm-workspace.yaml. The lock files (pnpm-lock.yaml) are not compatible with npm/yarn.

# Install pnpm
npm install -g pnpm@9
 
# Check
pnpm -v

How do I change the database?

Edit DATABASE_URL and DIRECT_URL in your .env. HeartCo works with any PostgreSQL database:

# Supabase (recommended)
DATABASE_URL="postgresql://postgres:password@db.project.supabase.co:6543/postgres?pgbouncer=true"
 
# Local PostgreSQL
DATABASE_URL="postgresql://user:password@localhost:5432/heartco"
 
# Neon, Railway, etc.
DATABASE_URL="postgresql://..."

After the change:

npx prisma migrate dev

HeartCo only supports PostgreSQL. MySQL, SQLite and MongoDB are not compatible.

I'm getting an EPERM error on Windows with Prisma

This is normal — the query_engine-windows.dll.node file is locked while the dev server is running.

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

The build fails with "JavaScript heap out of memory"

The build needs ~7 GB of RAM. Make sure NODE_OPTIONS is set:

# In package.json (already configured)
NODE_OPTIONS=--max-old-space-size=7168 next build

If that isn't enough, raise the value or close other applications.

Customization

How do I rename the application?

Edit the NEXT_PUBLIC_* environment variables (see Customization):

NEXT_PUBLIC_APP_NAME="MyApp"
NEXT_PUBLIC_APP_SHORT_NAME="MA"
NEXT_PUBLIC_APP_TAGLINE="My awesome SaaS"
NEXT_PUBLIC_APP_EMAIL="contact@myapp.com"

The entire brand is centralized in src/lib/config/branding.ts and read from the environment variables.

How do I remove a module I don't need?

Simple option: Remove the module's entry in src/lib/navigation/nav-config.ts. The module will no longer be visible in the sidebar.

Full option:

  1. Remove it from nav-config.ts
  2. Delete the tRPC router in src/server/api/routers/
  3. Remove the import in src/server/api/root.ts
  4. Delete the dashboard page src/app/dashboard/<module>/

The router can safely stay — if it isn't in the sidebar, users won't reach it.

How do I add dark mode?

Dark mode is already built in via next-themes. It is enabled by default and follows the user's system preference.

To force a mode:

import { useTheme } from "next-themes";
 
const { setTheme } = useTheme();
setTheme("dark");  // or "light" or "system"

Make sure you use the semantic CSS tokens (bg-background, text-foreground) and not hardcoded colors (bg-white, text-gray-900).

How do I change the theme colors?

Edit the custom properties in src/styles/globals.css:

:root {
  --primary: 239 84% 67%;        /* Primary color */
  --primary-foreground: 0 0% 100%; /* Text on primary */
  /* ... */
}

The brand colors (landing page):

:root {
  --color-brand: #6366f1;       /* Indigo */
  --color-deep-navy: #0d1b2a;   /* Dark background */
}

Modules and features

Does HeartCo include mobile apps?

Yes. The apps/app-terrain/ and apps/app-temps/ folders contain Expo (React Native) apps connected to the same tRPC backend through the shared packages/mobile-core/ package. They include:

  • Authentication (JWT + secure Zustand store)
  • Offline mode with a sync queue
  • Shared mobile tRPC client

How does the AI (Copilot) work?

HeartCo uses Mistral AI (@mistralai/mistralai) for:

  • A conversational copilot (context-aware chatbot)
  • Document and invoice analysis
  • Content generation (social, blog)
  • A regulatory assistant

Configuration:

MISTRAL_API_KEY="your-mistral-key"

The AI files live in src/lib/ai/: ai-service.ts, prompts.ts, agent-tools.ts.

How does e-invoicing work?

HeartCo supports:

  • Factur-X (EN 16931) — PDF/A-3 generation with embedded XML
  • Iopole — Sending and receiving B2B invoices over the Peppol network

Important: The src/modules/facturx/ and src/modules/iopole/ modules are certified. Do not modify them.

How do I enable demo mode?

NEXT_PUBLIC_DEMO_MODE=true
NEXT_PUBLIC_DEMO_URL="https://demo.heartco.fr"

In demo mode:

  • Destructive actions are blocked (deletion, real email sending)
  • Stricter per-user rate limiting
  • Automatic daily reset via the demo-reset cron (03:00)
  • Data is restored to its initial state every night

Multi-tenant and security

Can I use HeartCo for several organizations?

Yes, it's native. HeartCo is multi-tenant by design. Each sign-up creates an isolated organization. Data is strictly separated via organizationId.

A user can be invited to several organizations through the invitation system.

How does data isolation work?

Every read query goes through ctx.orgDb, which automatically injects organizationId into the Prisma filters. See Security and Database.

Deployment and maintenance

How much does hosting cost?

Estimate for typical usage:

  • Vercel: Pro plan (~$20/month) or Team
  • Supabase: Pro plan (~$25/month) for PostgreSQL
  • Upstash Redis: Pay-as-you-go (~$5/month)
  • Resend: Free up to 3,000 emails/month
  • Pusher: Free up to 200K messages/day

Estimated total: ~$50/month to get started.

How do I update HeartCo?

If you have access to the upstream repository:

git remote add upstream https://github.com/heartco/heartco.git
git fetch upstream
git merge upstream/main

Resolve any conflicts, then:

npx prisma generate
npx prisma migrate dev
pnpm build

How do I enable maintenance mode?

MAINTENANCE_MODE=true
MAINTENANCE_BYPASS_SECRET="your-secret"

All pages redirect to /maintenance except webhooks, crons and the health API. To bypass it as an admin, add ?bypass=your-secret to the URL.

The crons don't run on Vercel

Check that:

  1. vercel.json contains the cron configurations
  2. The CRON_SECRET variable is set (≥32 characters)
  3. You're on Vercel's Pro or Team plan (crons aren't available on the free plan)

Check the logs in the Vercel dashboard → Deployments → Functions → Cron.

Performance

The bundle is too large

HeartCo optimizes the bundle with:

  • optimizePackageImports for lucide-react, framer-motion, date-fns, recharts, @radix-ui
  • Automatic tree-shaking
  • Analysis: pnpm analyze

To reduce it further:

  • Remove unused modules (routers + pages)
  • Use lazy loading for heavy components

Turbopack is causing issues

If hot reload stops working or chunk errors appear:

# Clear the cache
rm -rf .next
 
# Run without Turbopack
npx next dev

Turbopack is enabled by default with pnpm dev. Use npx next dev (without --turbo) if you run into problems.

◀ Testing · Contents