Installation & Setup

Configurez CodeCourier pour le développement local. Couvre la configuration système, les variables d'environnement, Convex, Clerk, E2B et Trigger.dev.

10 min lire
installationsetupenvironment

Ce guide couvre tout ce dont vous avez besoin pour faire tourner CodeCourier en local pour le développement. CodeCourier est une application Next.js adossée à Convex, Clerk, E2B et Trigger.dev. Chaque service nécessite sa propre configuration, mais une fois en place, l’expérience de développement local est pleinement fonctionnelle avec hot reloading et données en temps réel.

Configuration système requise

  • Node.js - Version 20.9.0 ou ultérieure (requise par le SDK Clerk)
  • Gestionnaire de paquets - Bun (recommandé, utilisé dans les scripts du projet) ou npm/yarn/pnpm
  • Git - Pour cloner le repository et gérer les branches
  • Système d’exploitation - macOS, Linux ou Windows (avec WSL recommandé pour la meilleure expérience)

Bun est optionnel

Bien que le projet soit configuré pour Bun (le nom du package est bun-nextjs-convex-clerk), toutes les commandes npm standard fonctionnent aussi. Les instructions ci-dessous montrent les deux options.

Cloner et installer

1

Clonez le repository

Terminal
git clone https://github.com/your-org/codecourier.git
cd codecourier
2

Installez les dépendances

Terminal
bun install

Cela installe toutes les dépendances de production et de développement, y compris Next.js, Convex, Clerk, le SDK E2B, le SDK Trigger.dev, Tailwind CSS, Radix UI, shadcn/ui, Framer Motion et les outils de test (Vitest, Playwright).

Variables d’environnement

Créez un fichier .env.local à la racine du projet. Le repository inclut un fichier .env.example avec toutes les variables prises en charge. Copiez-le comme point de départ :

Terminal
cp .env.example .env.local

Les variables suivantes sont requises pour le développement local :

Convex

.env.local
# Your Convex deployment URL (shown after running npx convex dev)
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud

# Convex site URL (used by Trigger.dev for HTTP callbacks)
CONVEX_SITE_URL=https://your-deployment.convex.site

Authentification Clerk

.env.local
# Clerk publishable key (client-side, starts with pk_test_ or pk_live_)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxx

# Clerk secret key (server-side, starts with sk_test_ or sk_live_)
CLERK_SECRET_KEY=sk_test_xxx

# Clerk JWT issuer domain (found in Clerk dashboard > JWT Templates)
CLERK_JWT_ISSUER_DOMAIN=https://your-clerk-domain.clerk.accounts.dev

# Clerk webhook signing secret (for Convex HTTP webhook handler)
CLERK_WEBHOOK_SECRET=whsec_xxx

Trigger.dev

.env.local
# Shared secret for authenticating callbacks between Trigger.dev and Convex
TRIGGER_CALLBACK_SECRET=your-random-secret-string

Générez un callback secret robuste

Le TRIGGER_CALLBACK_SECRET sert à vérifier que les requêtes HTTP entrantes vers Convex proviennent réellement de vos jobs Trigger.dev. Utilisez une chaîne cryptographiquement aléatoire (au moins 32 caractères). Vous pouvez en générer une avec openssl rand -hex 32.

Variables optionnelles

.env.local
# PostHog analytics (optional)
# NEXT_PUBLIC_POSTHOG_KEY=phc_xxx
# NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

# Meta/Facebook Pixel (optional)
# NEXT_PUBLIC_META_PIXEL_ID=123456789

# Google Ads conversion tracking (optional)
# NEXT_PUBLIC_GOOGLE_ADS_ID=AW-123456789

Configuration des services

1

Mettez en place Convex

Convex est la base de données et le runtime backend de CodeCourier. Démarrez le serveur de développement Convex, qui synchronise votre schéma et vos functions locaux vers un déploiement de développement :

Terminal
npx convex dev

Au premier lancement, la CLI Convex vous invite à vous connecter et à créer un nouveau projet. Après la configuration, elle affiche votre URL de déploiement - copiez-la dans votre .env.local sous NEXT_PUBLIC_CONVEX_URL.

Le serveur de développement Convex surveille les changements des fichiers dans le répertoire convex/ et pousse automatiquement les mises à jour de schéma et de functions. Gardez ce terminal ouvert pendant le développement.

Variables d'environnement Convex

Votre déploiement Convex a aussi besoin de variables d’environnement pour des fonctionnalités comme la vérification des webhooks Clerk. Définissez-les dans le dashboard Convex sous Settings > Environment Variables de votre projet. Au minimum, configurez-y CLERK_WEBHOOK_SECRET et TRIGGER_CALLBACK_SECRET.
2

Configurez l'authentification Clerk

Créez une application Clerk sur dashboard.clerk.com :

  1. Créez une nouvelle application et activez les méthodes de connexion souhaitées (Google, GitHub, e-mail, etc.)
  2. Copiez la Publishable Key et la Secret Key depuis la page API Keys dans votre .env.local
  3. Configurez un JWT Templatepour Convex. Dans le dashboard Clerk, allez dans JWT Templates, créez un nouveau template nommé “convex” et configurez les champs issuer et audience comme documenté dans le guide d’intégration Convex + Clerk
  4. Copiez le JWT issuer domain dans CLERK_JWT_ISSUER_DOMAIN
  5. Configurez un endpoint Webhookpointant vers votre Convex site URL (p. ex., https://your-deployment.convex.site/clerk-webhook). Activez les événements utilisateur (user.created, user.updated, user.deleted). Copiez le signing secret dans CLERK_WEBHOOK_SECRET
3

Mettez en place l'accès aux sandboxes E2B

E2B fournit les sandboxes cloud où les agents IA s’exécutent. La configuration se fait au niveau du projet dans l’interface CodeCourier (Project Settings > API Keys), et non comme variable d’environnement locale. Toutefois, pour vérifier votre configuration E2B pendant le développement :

  1. Créez un compte sur e2b.dev et récupérez votre clé API depuis le dashboard
  2. Après avoir démarré CodeCourier, rendez-vous dans Project Settings et ajoutez votre clé API E2B dans la section API Keys

Le SDK E2B (package e2b) est déjà inclus dans les dépendances du projet. Les sandbox templates (qui définissent l’environnement de base et les outils préinstallés) sont configurés par workflow et gérés via l’interface CodeCourier.

4

Connectez Trigger.dev

Trigger.dev prend en charge l’exécution des jobs en arrière-plan pour le provisionnement de sandbox, les runs de workflow et les sessions d’issues. Pour le développement local :

  1. Inscrivez-vous sur trigger.dev et créez un nouveau projet
  2. Installez la CLI Trigger.dev globalement ou utilisez npx :
Terminal
npx trigger.dev@latest dev

Cela démarre le serveur de développement Trigger.dev, qui se connecte au cloud Trigger.dev pour recevoir et traiter les jobs localement. Le projet inclut un fichier trigger.config.ts qui définit toutes les tasks enregistrées.

Trigger.dev est optionnel pour le développement UI

Si vous travaillez uniquement sur le frontend et n’avez pas besoin de tester l’exécution réelle des sandboxes, vous pouvez ignorer la configuration de Trigger.dev. L’interface se chargera et affichera les données de Convex - les runs et les sandboxes ne s’exécuteront simplement pas.

Démarrez le serveur de développement

Avec Convex dev qui tourne dans un terminal, démarrez le serveur de développement Next.js dans un autre :

Terminal
bun dev

L’application démarre sur http://localhost:3000. Vous devriez voir la page de connexion Clerk. Après vous être authentifié, vous serez dirigé pour créer votre premier projet ou en rejoindre un existant.

Vérifiez l’installation

Parcourez cette checklist pour confirmer que tout fonctionne :

  1. Authentification : Vous pouvez vous connecter et vous déconnecter via Clerk. Votre utilisateur apparaît dans le dashboard Convex sous la table users.
  2. Création de projet : Vous pouvez créer un nouveau projet. Vérifiez que les tables projects, projectMembers et projectSettings se remplissent dans Convex.
  3. Mises à jour en temps réel : Ouvrez deux onglets de navigateur sur le même projet. Créez un workflow dans un onglet et confirmez qu’il apparaît instantanément dans l’autre.
  4. Stockage des clés API : Ajoutez une clé API E2B dans les paramètres du projet et vérifiez qu’elle apparaît avec seulement les quatre derniers caractères visibles.

Lancer les tests

CodeCourier inclut à la fois des tests unitaires (Vitest) et des tests de bout en bout (Playwright) :

Terminal
# Unit tests
npm run test

# Unit tests with watch mode
npm run test:watch

# Unit tests with coverage report
npm run test:coverage

# End-to-end tests (requires the dev server running)
npm run test:e2e

# E2E tests with interactive UI
npm run test:e2e:ui

Dépannage

Convex dev ne démarre pas

Assurez-vous d’être connecté à la CLI Convex (npx convex login) et que votre fichier convex.json pointe vers un projet valide. Si vous voyez des erreurs de validation de schéma, vérifiez que tous les fichiers du répertoire convex/ compilent sans erreur TypeScript.

Boucle de redirection d’authentification Clerk

Vérifiez que NEXT_PUBLIC_CLERK_PUBLISHABLE_KEYcorrespond à l’environnement de votre application Clerk (test vs production). Assurez-vous que le JWT template dans Clerk est nommé “convex” et que l’issuer domain dans CLERK_JWT_ISSUER_DOMAIN correspond exactement.

La création de sandbox échoue

Vérifiez que votre clé API E2B est correctement configurée dans les paramètres du projet (pas dans .env.local - les clés E2B sont stockées par projet dans Convex). Vérifiez que le serveur de développement Trigger.dev tourne et est connecté. Consultez le dashboard Trigger.dev pour les logs d’exécution des jobs.

Erreurs de vérification de types

Lancez le type checker pour trouver les problèmes :

Terminal
npm run typecheck

Le projet utilise TypeScript 5.9+ en mode strict. Convex génère automatiquement les types dans convex/_generated/ - s’ils sont manquants, assurez-vous que npx convex dev a été exécuté au moins une fois.

Prochaines étapes

Core Concepts

Comprenez le modèle de données et comment les fonctionnalités de CodeCourier se connectent.

Votre premier projet

Parcours détaillé de la configuration d'un projet pour un usage réel.