Que construisons-nous dans ce tutoriel ?

Un Bookmark Manager Full-Stack avec une REST API Node.js/Express, une base de données SQLite, un système de tags, une recherche plein texte et un frontend simple en HTML/CSS/JS. L'application entière est construite en utilisant OpenCode comme AI coding agent dans le terminal, illustrant des workflows réels plutôt que de lister des fonctionnalités.

Ai-je besoin d'une API key pour suivre ce tutoriel ?

Non. OpenCode propose des modèles Zen gratuits, incluant Grok Code Fast, GLM 4.7 et Big Pickle, qui fonctionnent sans API keys. Vous pouvez également l'exécuter entièrement hors ligne avec des modèles locaux via Ollama. Si vous possédez une API key Claude, GPT ou Gemini, vous pouvez les utiliser pour une qualité de sortie supérieure.

Combien de temps faut-il pour construire le projet complet ?

Environ 30 minutes si vous suivez les étapes. Le tutoriel est structuré en 7 phases : configuration du projet, modèle de données, API endpoints, recherche, tags, frontend et tests. Chaque phase prend 3 à 5 minutes avec OpenCode gérant la génération de code.

Puis-je utiliser OpenCode dans VS Code ou Cursor ?

Oui. OpenCode s'exécute dans n'importe quel terminal intégré. Ouvrez un terminal partagé dans VS Code (Cmd+Esc sur Mac) ou Cursor et lancez OpenCode à partir de là. Il partage automatiquement votre sélection et le contexte du fichier ouvert avec l'AI agent.

Quelle est la différence entre Build mode et Plan mode ?

Le Build mode donne à l'AI agent un accès complet pour lire, écrire et exécuter du code. Le Plan mode le restreint à une analyse en lecture seule — l'agent peut examiner votre code et créer des fichiers de plan mais ne peut rien modifier. Nous utilisons le Plan mode dans ce tutoriel avant les étapes majeures de refactorisation.

Comment ajouter des MCP servers à OpenCode ?

Ajoutez-les dans votre configuration opencode.json sous la clé mcp. Chaque MCP server nécessite un nom unique, un type (local ou remote) et des détails de connexion. Les serveurs locaux utilisent un champ command ; les serveurs distants utilisent un champ url avec des en-têtes optionnels. OpenCode gère automatiquement l'OAuth pour les MCP servers distants.

Créez un Bookmark Manager Full-Stack avec OpenCode en 30 minutes (étape par étape)

Ce que nous construisons

Oubliez les listes de fonctionnalités. La meilleure façon d'apprendre un outil est de construire quelque chose avec lui.

Dans ce tutoriel, vous utiliserez OpenCode — l'agent de codage AI open-source avec 120K+ GitHub stars — pour construire un gestionnaire de favoris complet à partir de zéro. L'application disposera de :

Une API REST avec Express.js et TypeScript
Une base de données SQLite avec recherche en texte intégral
Un système de tags pour organiser les favoris
Un frontend simple mais fonctionnel
Des tests unitaires

Chaque fonctionnalité de OpenCode est introduite au moment où vous en avez besoin — et non dans une section de fonctionnalités abstraites. À la fin, vous saurez comment installer OpenCode, configurer les modèles, utiliser les modes Build et Plan, configurer des serveurs MCP et créer des agents personnalisés — tout cela parce que vous les aurez utilisés pour construire un projet réel.

Temps : ~30 minutes Prérequis : Node.js 18+ installé, un terminal (macOS, Linux ou WSL sur Windows) Coût : Gratuit (en utilisant les modèles Zen de OpenCode)

Phase 1 : Installation de OpenCode et configuration du projet (5 minutes)

Installer OpenCode

Ouvrez votre terminal et exécutez l'une de ces commandes :

# Option 1: npm (recommandé)
npm i -g opencode-ai@latest

# Option 2: Homebrew (macOS/Linux)
brew install sst/tap/opencode

# Option 3: Installateur en une ligne
curl -fsSL https://opencode.ai/install.sh | bash

Vérifiez l'installation :

opencode --version

Vous devriez voir le numéro de version. En date du March 2026, la dernière version stable est disponible sur le GitHub repository de OpenCode.

Créer le répertoire du projet

mkdir bookmark-manager && cd bookmark-manager
git init
npm init -y

Lancer OpenCode pour la première fois

opencode

Ceci ouvre la TUI (Terminal User Interface) de OpenCode — une interface interactive plein écran construite avec Bubble Tea. Vous verrez une entrée de chat en bas et un volet de conversation dans la zone principale.

Choisir un modèle

Lors du premier lancement, OpenCode vous demandera de sélectionner un modèle. Vous avez trois options :

Gratuit (modèles Zen) : Tapez /models et sélectionnez l'un des modèles Zen gratuits. Pour ce tutoriel, Grok Code Fast 1 ou GLM 4.7 fonctionnent bien. Ils sont gratuits et ne nécessitent aucune clé API.

Local (Ollama) : Si vous avez Ollama installé, OpenCode le détectera automatiquement. Le modèle recommandé pour Ollama est glm-4.7:cloud.

Payant (apportez votre propre clé) : Tapez /connect pour lier votre clé API Anthropic, OpenAI ou Google. Les clés sont stockées localement dans ~/.local/share/opencode/auth.json.

Pour ce tutoriel, n'importe quel modèle fonctionne. Les modèles aux capacités plus élevées (Claude Sonnet 4.6, GPT-5.4) produiront de meilleurs résultats sur des tâches complexes, mais les modèles Zen gratuits gèrent tout ce que nous construisons ici.

Phase 2 : Échafaudage du projet avec le mode Build (4 minutes)

OpenCode démarre en mode Build par défaut. Le mode Build donne à l'agent AI un accès complet pour créer des fichiers, éditer le code et exécuter des commandes. C'est ce que nous voulons pour l'échafaudage.

Votre premier prompt

Tapez ceci dans le chat de OpenCode :

Configurez un projet Node.js TypeScript avec Express pour une API REST de gestionnaire de favoris.
Utilisez SQLite via better-sqlite3 pour la base de données. Ajoutez TypeScript, ts-node et
nodemon comme dépendances de développement. Créez un répertoire src/ avec un point d'entrée index.ts
qui démarre un serveur Express sur le port 3000.

OpenCode va :

Créer un tsconfig.json
Installer les dépendances avec npm install
Créer src/index.ts avec la configuration du serveur Express
Mettre à jour package.json avec les scripts de démarrage

Regardez la TUI — vous verrez l'agent exécuter des commandes terminal, créer des fichiers et expliquer ce qu'il fait à chaque étape. Il ne s'agit pas de génération de code isolée ; OpenCode a un accès complet à votre système de fichiers et à votre terminal.

Vérifier que cela fonctionne

Une fois que OpenCode a terminé, dites-lui :

Lancez le serveur et vérifiez qu'il démarre correctement sur le port 3000.

OpenCode exécutera npx nodemon src/index.ts et confirmera que le serveur est à l'écoute. Vous devriez voir une sortie comme Server running on http://localhost:3000.

Que s'est-il passé (Fonctionnalité : mode Build)

Le mode Build est l'agent par défaut de OpenCode. Il a accès à tous les outils : lecture/écriture de fichiers, exécution de terminal et édition de code. Selon la documentation de OpenCode, vous pouvez le considérer comme un AI pair programmer avec un accès complet à votre environnement de développement.

Phase 3 : Création du modèle de données et de la base de données (4 minutes)

Concevoir le schéma

Tapez ce prompt :

Créez un module de base de données dans src/db.ts qui :
1. Initialise une base de données SQLite dans ./data/bookmarks.db
2. Crée une table bookmarks avec : id (auto-incrément), url (texte, unique),
   title (texte), description (texte, nullable), created_at (datetime),
   updated_at (datetime)
3. Crée une table tags avec : id (auto-incrément), name (texte, unique)
4. Crée une table de jonction bookmark_tags pour les relations many-to-many
5. Active le mode WAL pour les performances de lecture concurrente
6. Crée une table virtuelle FTS5 pour la recherche en texte intégral sur le titre et la description
Exportez une fonction pour obtenir l'instance de la base de données.

OpenCode générera le module de base de données complet. Faites attention à la façon dont il gère la configuration FTS5 (Full-Text Search 5) — c'est une fonctionnalité SQLite qui alimentera notre fonctionnalité de recherche plus tard.

Initialiser la base de données au démarrage du serveur

Importez le module de base de données dans index.ts et initialisez-le au démarrage du serveur.
Affichez un message de confirmation.

Créer la configuration opencode.json

C'est un bon moment pour introduire la configuration du projet. Créez un fichier en disant à OpenCode :

Créez un fichier opencode.json à la racine du projet avec le nom du projet
"bookmark-manager" et une règle disant "Ceci est une API Express TypeScript
utilisant better-sqlite3. Suivez les conventions RESTful. Utilisez async/await.
Retournez des réponses JSON avec un formatage d'erreur cohérent."

Ceci crée le fichier de configuration de projet que OpenCode lit au démarrage. Cela donne à l'AI un contexte persistant sur votre projet — normes de codage, décisions d'architecture et contraintes — de sorte que vous n'ayez pas à les répéter dans chaque prompt.

Phase 4 : Construction des endpoints de l'API REST (5 minutes)

Générer les routes

Créez un module de routes dans src/routes/bookmarks.ts avec ces endpoints :
- POST /api/bookmarks — créer un favori (valider que url et title sont présents)
- GET /api/bookmarks — lister tous les favoris avec pagination (paramètres page, limit)
- GET /api/bookmarks/:id — obtenir un seul favori avec ses tags
- PUT /api/bookmarks/:id — mettre à jour un favori
- DELETE /api/bookmarks/:id — supprimer un favori et ses associations de tags
Utilisez les codes de statut HTTP appropriés. Retournez du JSON avec une structure cohérente :
{ success: boolean, data: any, error?: string }

Enregistrer les routes

Importez les routes de favoris dans index.ts et enregistrez-les. Ajoutez également
le middleware express.json() et un gestionnaire d'erreurs global.

Tester avec curl

Démarrez le serveur, puis créez un favori de test en utilisant curl :
curl -X POST http://localhost:3000/api/bookmarks \
  -H "Content-Type: application/json" \
  -d '{"url": "https://opencode.ai", "title": "OpenCode - AI Coding Agent"}'
Ensuite, récupérez tous les favoris pour vérifier qu'il a été enregistré.

OpenCode exécutera ces commandes dans votre terminal et vous montrera les réponses. C'est là que l'outil brille — vous ne quittez jamais le terminal, et l'AI vérifie son propre travail.

Phase 5 : Ajout de la recherche avec FTS5 (4 minutes)

Introduire le mode Plan

Avant de construire la recherche, utilisons le mode Plan pour réfléchir à l'implémentation. Changez de mode :

/plan

Vous êtes maintenant en mode Plan. L'AI peut lire votre code et l'analyser mais ne peut modifier aucun fichier. C'est utile pour planifier avant d'apporter des modifications.

Analysez mon schéma de base de données actuel et ma table FTS5. Planifiez comment implémenter un
endpoint de recherche qui interroge la table FTS5 et renvoie les favoris classés par
pertinence. Considérez les cas limites : requêtes vides, caractères spéciaux, correspondances
partielles.

OpenCode examinera votre code, écrira un plan dans .opencode/plans/ et expliquera son approche sans toucher aux fichiers. Lisez le plan, ajustez-le si nécessaire, puis revenez en arrière :

/build

Implémenter la recherche

Sur la base du plan, implémentez un endpoint GET /api/bookmarks/search?q=query
qui utilise la table virtuelle FTS5 pour la recherche en texte intégral. Incluez la mise en évidence
des extraits (snippet highlighting) et le classement par pertinence. Gérez les cas limites du plan.

Tester la recherche

Créez trois autres favoris de test avec des titres et des descriptions différents,
puis testez l'endpoint de recherche avec une requête qui devrait correspondre à deux d'entre eux.

Que s'est-il passé (Fonctionnalité : mode Plan)

Le flux de travail Plan/Build est la façon dont les développeurs expérimentés utilisent OpenCode pour les tâches complexes. Planifiez d'abord, examinez l'approche, puis construisez. Les fichiers de plan sont enregistrés dans .opencode/plans/ et peuvent être consultés plus tard par l'agent de build. Cela empêche l'AI de prendre des décisions structurelles majeures à la volée.

Phase 6 : Implémentation du système de tags (4 minutes)

Créer les endpoints de tags

Créez un module de routes dans src/routes/tags.ts avec :
- POST /api/tags — créer un nouveau tag
- GET /api/tags — lister tous les tags avec le nombre de favoris
- POST /api/bookmarks/:id/tags — ajouter un tag à un favori
- DELETE /api/bookmarks/:id/tags/:tagId — supprimer un tag d'un favori
- GET /api/bookmarks?tag=tagname — filtrer les favoris par tag (mettre à jour l'endpoint
  de liste existant pour prendre en charge ce paramètre de requête)
Enregistrez les routes de tags dans index.ts.

Tester le flux de tags

Créez deux tags : "dev-tools" et "tutorials". Ajoutez le tag "dev-tools" au
favori OpenCode. Ensuite, récupérez les favoris filtrés par le tag "dev-tools".

Phase 7 : Construction d'un frontend simple (5 minutes)

Générer le frontend

Créez un répertoire public/ avec un frontend monopage (SPA) :
- index.html avec un design propre et minimal (pas de framework, juste HTML/CSS/JS)
- Un formulaire pour ajouter des favoris (url, title, description)
- Une barre de recherche qui interroge l'endpoint de recherche avec une entrée debouncée
- Une liste de favoris affichant le titre, l'url, les tags et un bouton de suppression
- Une barre latérale de filtrage par tag qui affiche tous les tags avec leurs comptes
- Utilisez fetch() pour les appels API. Responsive mobile. Aucune étape de build nécessaire.
Servez le répertoire public/ comme fichiers statiques depuis Express.

OpenCode générera le frontend complet — structure HTML, style CSS et JavaScript pour les interactions API — en une seule fois. L'avantage de construire cela dans le terminal avec un agent AI est qu'il peut tester immédiatement si le frontend se connecte à l'API.

Tester le Full Stack

Démarrez le serveur, ouvrez http://localhost:3000 dans un navigateur, et vérifiez
que l'ajout d'un favori depuis le formulaire, la recherche et le filtrage par tag
fonctionnent tous correctement.

Phase 8 : Ajout de tests avec un agent personnalisé (5 minutes)

Créer un agent de test personnalisé

C'est ici qu'intervient la fonctionnalité d'agents personnalisés de OpenCode. Au lieu d'utiliser l'agent Build générique pour les tests, nous allons en créer un spécialisé.

Ajoutez ceci à votre opencode.json :

{
  "agents": {
    "test": {
      "name": "Rédacteur de Tests",
      "instructions": "Vous êtes un spécialiste des tests. Écrivez des tests complets en utilisant Vitest. Concentrez-vous sur les cas limites et les chemins d'erreur. Ne modifiez jamais le code source — créez et éditez uniquement des fichiers de test.",
      "tools": ["read", "write", "terminal"]
    }
  }
}

Maintenant, passez à l'agent de test :

/agent test

Générer des tests

Écrivez des tests complets pour l'API de favoris en utilisant Vitest et supertest.
Couvrez :
- La création d'un favori avec des données valides
- La création d'un favori avec des champs obligatoires manquants
- La récupération de tous les favoris avec pagination
- La recherche avec FTS5 (requêtes correspondantes et non correspondantes)
- L'ajout et la suppression de tags
- La suppression d'un favori supprime ses associations de tags
Utilisez une base de données SQLite en mémoire pour l'isolation des tests.

Exécuter les tests

Installez vitest et supertest comme dépendances de développement, ajoutez un script
de test à package.json, puis lancez la suite de tests.

Que s'est-il passé (Fonctionnalité : agents personnalisés)

Les agents personnalisés vous permettent de créer des personas ciblés avec des instructions spécifiques et un accès aux outils. L'agent de test que nous avons créé ne peut que lire des fichiers, écrire des fichiers de test et exécuter des commandes terminal — il ne peut pas modifier le code source. Cette contrainte évite le problème courant de l'AI qui "répare" votre code source lorsque les tests échouent au lieu de réparer les tests.

Vous pouvez créer des agents pour n'importe quel flux de travail spécialisé : revue de code, documentation, migrations de base de données, scripts DevOps. La documentation des agents OpenCode contient plus d'exemples.

Bonus : Connexion d'un serveur MCP pour des fonctionnalités améliorées

Si vous souhaitez étendre votre gestionnaire de favoris, vous pouvez connecter des outils externes via des serveurs MCP (Model Context Protocol).

Exemple : Ajout d'un serveur MCP de prévisualisation de lien

Imaginez que vous souhaitiez que OpenCode récupère automatiquement les métadonnées (titre, description, favicon) à partir des URL lors de la création de favoris. Vous pouvez connecter un serveur MCP qui effectue la récupération HTTP :

Ajoutez ceci à votre opencode.json :

{
  "mcp": {
    "link-preview": {
      "type": "local",
      "command": ["npx", "link-preview-mcp-server"]
    }
  }
}

Maintenant, OpenCode dispose d'un nouvel outil : il peut récupérer les métadonnées d'une URL dans le cadre de son flux de travail. Lorsque vous lui demandez d'"ajouter un favori pour https://example.com et de remplir automatiquement le titre et la description", il utilisera le serveur MCP pour récupérer ces données.

Serveurs MCP distants

Pour les services cloud, utilisez des serveurs MCP distants avec gestion automatique de l'OAuth :

{
  "mcp": {
    "cloud-storage": {
      "type": "remote",
      "url": "https://mcp.example.com/storage",
      "headers": {
        "Authorization": "Bearer ${STORAGE_TOKEN}"
      }
    }
  }
}

OpenCode détecte les réponses 401 et initie automatiquement le flux OAuth si le serveur prend en charge l'enregistrement dynamique des clients (Dynamic Client Registration).

Bonus : Utilisation de OpenCode dans la CI/CD

OpenCode dispose d'un mode CLI qui s'exécute sans la TUI — parfait pour l'automatisation. Vous pouvez l'utiliser dans GitHub Actions ou n'importe quel pipeline CI :

# Exécuter un seul prompt et quitter
opencode -p "Examinez les modifications du dernier commit pour détecter d'éventuels problèmes de sécurité" --no-tui

# Utiliser un modèle spécifique
opencode -m "claude-sonnet-4-6" -p "Générez une entrée de changelog pour cette version" --no-tui

Pour notre gestionnaire de favoris, vous pourriez ajouter une étape CI qui exécute OpenCode pour réviser automatiquement les PR. L'intégration GitHub de OpenCode fournit une version plus rationalisée de ce flux de travail.

La structure complète du projet

Après avoir suivi ce tutoriel, votre projet devrait ressembler à ceci :

bookmark-manager/
  opencode.json          # configuration du projet OpenCode + agents personnalisés + MCP
  package.json
  tsconfig.json
  src/
    index.ts             # point d'entrée du serveur Express
    db.ts                # module de base de données SQLite avec FTS5
    routes/
      bookmarks.ts       # endpoints CRUD + recherche
      tags.ts            # endpoints de gestion des tags
  public/
    index.html           # frontend monopage
  tests/
    bookmarks.test.ts    # suite de tests de l'API
  data/
    bookmarks.db         # base de données SQLite (gitignorée)
  .opencode/
    plans/               # plans issus des sessions en mode Plan

Ce que vous avez appris

En construisant un projet réel, vous avez pratiqué ces capacités de OpenCode :

Fonctionnalité	Où vous l'avez utilisé
Installation	Phase 1 — npm, Homebrew ou curl
Modèles Zen (gratuit)	Phase 1 — choisir un modèle sans clé API
Mode Build	Phases 2-7 — développement complet avec accès aux fichiers et au terminal
Mode Plan	Phase 5 — analyse du code et planification de la recherche avant l'implémentation
opencode.json	Phase 3 — config du projet avec des règles pour un comportement constant de l'AI
Agents personnalisés	Phase 8 — un agent de rédaction de tests qui ne peut pas modifier le code source
Serveurs MCP	Bonus — extension de OpenCode avec des outils externes
Mode CLI	Bonus — exécution de OpenCode en CI/CD sans la TUI

La différence clé entre OpenCode et les autres outils de codage AI est qu'il est entièrement open source, s'exécute dans votre terminal et ne stocke pas votre code ni vos données de contexte. Vous contrôlez les modèles, les données restent locales et la communauté de 800+ contributeurs le fait évoluer rapidement.

Pour les équipes utilisant plusieurs outils AI, OpenCode fonctionne bien comme complément basé sur le terminal pour les assistants d'IDE. Chez ZBuild, nous l'utilisons souvent aux côtés d'outils basés sur l'éditeur pour différentes parties du flux de travail de développement.

Prochaines étapes

Maintenant que vous avez un gestionnaire de favoris fonctionnel et une solide compréhension de OpenCode, voici quelques pistes à explorer :

Ajouter l'authentification — Utilisez l'agent Build pour ajouter une authentification basée sur JWT avec des comptes utilisateurs
Déployer en production — Demandez à OpenCode de générer un Dockerfile et de le déployer sur Fly.io ou Railway
Construire une extension de navigateur — Créez une extension Chrome qui ajoute des favoris via l'API
Explorer plus de modèles Zen — Essayez Big Pickle, MiniMax M2.1, ou lancez un modèle local via Ollama
Créer plus d'agents personnalisés — Un agent "refactor", un agent "docs" ou un agent "security audit"

La documentation de OpenCode et le repository awesome-opencode contiennent plus de plugins, de thèmes et de configurations communautaires à explorer.