Aller au contenu principal
HeartCoHeartCo/Documentation
Retour au site

FAQ

Questions fréquentes sur HeartCo Starter.

Installation et configuration

Puis-je utiliser npm ou yarn au lieu de pnpm ?

Non. HeartCo utilise exclusivement pnpm (version 9.x). Le projet est configuré comme monorepo pnpm avec pnpm-workspace.yaml. Les fichiers lock (pnpm-lock.yaml) ne sont pas compatibles avec npm/yarn.

# Installer pnpm
npm install -g pnpm@9
 
# Vérifier
pnpm -v

Comment changer la base de données ?

Modifiez DATABASE_URL et DIRECT_URL dans votre .env. HeartCo fonctionne avec n'importe quelle base PostgreSQL :

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

Après le changement :

npx prisma migrate dev

HeartCo ne supporte que PostgreSQL. MySQL, SQLite et MongoDB ne sont pas compatibles.

J'ai une erreur EPERM sur Windows avec Prisma

C'est normal — le fichier query_engine-windows.dll.node est verrouillé quand le serveur de dev tourne.

Solution : Arrêtez le serveur (Ctrl+C), lancez npx prisma generate, puis redémarrez pnpm dev.

Le build échoue avec "JavaScript heap out of memory"

Le build nécessite ~7 GB de RAM. Vérifiez que NODE_OPTIONS est configuré :

# Dans package.json (déjà configuré)
NODE_OPTIONS=--max-old-space-size=7168 next build

Si ça ne suffit pas, augmentez la valeur ou fermez d'autres applications.

Personnalisation

Comment renommer l'application ?

Modifiez les variables d'environnement NEXT_PUBLIC_* (voir Personnalisation) :

NEXT_PUBLIC_APP_NAME="MonApp"
NEXT_PUBLIC_APP_SHORT_NAME="MA"
NEXT_PUBLIC_APP_TAGLINE="Mon super SaaS"
NEXT_PUBLIC_APP_EMAIL="contact@monapp.fr"

Toute la marque est centralisée dans src/lib/config/branding.ts et lue depuis les variables d'environnement.

Comment supprimer un module dont je n'ai pas besoin ?

Option simple : Retirez l'entrée du module dans src/lib/navigation/nav-config.ts. Le module ne sera plus visible dans la sidebar.

Option complète :

  1. Retirer de nav-config.ts
  2. Supprimer le router tRPC dans src/server/api/routers/
  3. Retirer l'import dans src/server/api/root.ts
  4. Supprimer la page dashboard src/app/dashboard/<module>/

Le router peut rester sans risque — s'il n'est pas dans la sidebar, les utilisateurs n'y accèdent pas.

Comment ajouter le dark mode ?

Le dark mode est déjà intégré via next-themes. Il est activé par défaut et suit la préférence système de l'utilisateur.

Pour forcer un mode :

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

Assurez-vous d'utiliser les tokens CSS sémantiques (bg-background, text-foreground) et non des couleurs hardcodées (bg-white, text-gray-900).

Comment changer les couleurs du thème ?

Modifiez les custom properties dans src/styles/globals.css :

:root {
  --primary: 239 84% 67%;        /* Couleur principale */
  --primary-foreground: 0 0% 100%; /* Texte sur primary */
  /* ... */
}

Les couleurs de marque (landing page) :

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

Modules et fonctionnalités

HeartCo inclut-il des apps mobiles ?

Oui. Les dossiers apps/app-terrain/ et apps/app-temps/ contiennent des apps Expo (React Native) connectées au même backend tRPC via le package partagé packages/mobile-core/. Elles incluent :

  • Authentification (JWT + Zustand store sécurisé)
  • Mode offline avec queue de synchronisation
  • Client tRPC mobile partagé

Comment fonctionne l'IA (Copilote) ?

HeartCo utilise Mistral AI (@mistralai/mistralai) pour :

  • Copilote conversationnel (chatbot contextualisé)
  • Analyse de documents et factures
  • Génération de contenu (social, blog)
  • Assistant réglementaire

Configuration :

MISTRAL_API_KEY="votre-clé-mistral"

Les fichiers IA sont dans src/lib/ai/ : ai-service.ts, prompts.ts, agent-tools.ts.

Comment fonctionne l'e-facturation ?

HeartCo supporte :

  • Factur-X (EN 16931) — Génération de PDF/A-3 avec XML intégré
  • Iopole — Envoi et réception de factures B2B via le réseau Peppol

Important : Les modules src/modules/facturx/ et src/modules/iopole/ sont certifiés. Ne pas les modifier.

Comment activer le mode démo ?

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

En mode démo :

  • Les actions destructrices sont bloquées (suppression, envoi d'emails réels)
  • Rate limiting renforcé par utilisateur
  • Reset automatique quotidien via le cron demo-reset (03:00)
  • Les données sont restaurées à leur état initial chaque nuit

Multi-tenant et sécurité

Puis-je utiliser HeartCo pour plusieurs organisations ?

Oui, c'est natif. HeartCo est multi-tenant par design. Chaque inscription crée une organisation isolée. Les données sont strictement séparées via organizationId.

Un utilisateur peut être invité dans plusieurs organisations via le système d'invitations.

Comment fonctionne l'isolation des données ?

Chaque requête de lecture passe par ctx.orgDb qui injecte automatiquement organizationId dans les filtres Prisma. Voir Sécurité et Base de données.

Déploiement et maintenance

Combien coûte l'hébergement ?

Estimation pour un usage typique :

  • Vercel : Plan Pro (~20$/mois) ou Team
  • Supabase : Plan Pro (~25$/mois) pour PostgreSQL
  • Upstash Redis : Pay-as-you-go (~5$/mois)
  • Resend : Gratuit jusqu'à 3 000 emails/mois
  • Pusher : Gratuit jusqu'à 200K messages/jour

Total estimé : ~50$/mois pour démarrer.

Comment mettre à jour HeartCo ?

Si vous avez accès au repository upstream :

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

Résolvez les conflits éventuels, puis :

npx prisma generate
npx prisma migrate dev
pnpm build

Comment activer le mode maintenance ?

MAINTENANCE_MODE=true
MAINTENANCE_BYPASS_SECRET="votre-secret"

Toutes les pages redirigent vers /maintenance sauf les webhooks, crons et l'API health. Pour bypasser en tant qu'admin, ajoutez ?bypass=votre-secret à l'URL.

Les crons ne s'exécutent pas sur Vercel

Vérifiez que :

  1. vercel.json contient les configurations de crons
  2. La variable CRON_SECRET est configurée (≥32 caractères)
  3. Vous êtes sur le plan Pro ou Team de Vercel (les crons ne sont pas disponibles sur le plan gratuit)

Consultez les logs dans le dashboard Vercel → Deployments → Functions → Cron.

Performance

Le bundle est trop gros

HeartCo optimise le bundle avec :

  • optimizePackageImports pour lucide-react, framer-motion, date-fns, recharts, @radix-ui
  • Tree-shaking automatique
  • Analyse : pnpm analyze

Pour réduire davantage :

  • Supprimez les modules non utilisés (routers + pages)
  • Utilisez le lazy loading pour les composants lourds

Turbopack pose des problèmes

Si le hot reload ne fonctionne plus ou que des erreurs de chunk apparaissent :

# Supprimer le cache
rm -rf .next
 
# Lancer sans Turbopack
npx next dev

Turbopack est activé par défaut avec pnpm dev. Utilisez npx next dev (sans --turbo) en cas de problème.