Bouw een Full-Stack Bookmark Manager met OpenCode in 30 minuten (stap voor stap)

Wat we gaan bouwen

Vergeet functielijsten. De beste manier om een tool te leren kennen is door er iets mee te bouwen.

In deze tutorial gebruik je OpenCode — de open-source AI-coding agent met meer dan 120K GitHub-sterren — om vanaf nul een volledige bookmark manager te bouwen. De app krijgt:

• Een REST API met Express.js en TypeScript
• Een SQLite database met full-text search
• Een tagsysteem voor het organiseren van bookmarks
• Een eenvoudige maar functionele frontend
• Unit tests

Elke OpenCode-functie wordt geïntroduceerd op het moment dat je deze nodig hebt — niet in een abstracte sectie met functies. Aan het einde weet je hoe je OpenCode installeert, modellen configureert, de Build- en Plan-modi gebruikt, MCP-servers instelt en aangepaste agents maakt — allemaal omdat je ze hebt gebruikt om een echt project te bouwen.

Tijd: ~30 minuten Vereisten: Node.js 18+ geïnstalleerd, een terminal (macOS, Linux, of WSL op Windows) Kosten: Gratis (met OpenCode Zen-modellen)

Fase 1: OpenCode installeren en het project opzetten (5 minuten)

Installeer OpenCode

Open je terminal en voer een van deze commando's uit:

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

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

# Option 3: One-line installer
curl -fsSL https://opencode.ai/install.sh | bash

Verifieer de installatie:

opencode --version

Je zou het versienummer moeten zien. Vanaf March 2026 is de nieuwste stabiele release beschikbaar op de OpenCode GitHub repository.

Maak de projectmap aan

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

Start OpenCode voor de eerste keer

opencode

Dit opent de TUI van OpenCode — een schermvullende interactieve interface gebouwd met Bubble Tea. Je ziet onderaan een chat-input en een conversatievenster in het hoofdgedeelte.

Kies een model

Bij de eerste start zal OpenCode je vragen om een model te selecteren. Je hebt drie opties:

Gratis (Zen-modellen): Typ /models en selecteer een van de gratis Zen-modellen. Voor deze tutorial werken Grok Code Fast 1 of GLM 4.7 goed. Deze zijn gratis en vereisen geen API-sleutel.

Lokaal (Ollama): Als je Ollama hebt geïnstalleerd, zal OpenCode dit automatisch detecteren. Het aanbevolen model voor Ollama is glm-4.7:cloud.

Betaald (gebruik je eigen sleutel): Typ /connect om je Anthropic, OpenAI of Google API-sleutel te koppelen. Sleutels worden lokaal opgeslagen in ~/.local/share/opencode/auth.json.

Voor deze tutorial werkt elk model. Modellen met hogere capaciteiten (Claude Sonnet 4.6, GPT-5.4) zullen betere resultaten leveren bij complexe taken, maar de gratis Zen-modellen kunnen alles aan wat we hier bouwen.

Fase 2: Het project opzetten met Build-modus (4 minuten)

OpenCode start standaard in de Build mode. De Build mode geeft de AI-agent volledige toegang om bestanden te maken, code te bewerken en commando's uit te voeren. Dit is wat we willen voor de initiële opzet.

Je eerste prompt

Typ dit in de OpenCode-chat:

Set up a TypeScript Node.js project with Express for a bookmark manager REST API.
Use SQLite via better-sqlite3 for the database. Add TypeScript, ts-node, and
nodemon as dev dependencies. Create a src/ directory with an index.ts entry point
that starts an Express server on port 3000.

OpenCode zal:

1. Een tsconfig.json maken
2. Dependencies installeren met npm install
3. src/index.ts maken met de Express-server setup
4. package.json bijwerken met start-scripts

Bekijk de TUI — je ziet de agent terminalcommando's uitvoeren, bestanden maken en bij elke stap uitleggen wat hij doet. Dit is geen codegeneratie in een vacuüm; OpenCode heeft volledige toegang tot je bestandssysteem en terminal.

Verifieer of het werkt

Zodra OpenCode klaar is, zeg je:

Run the server and verify it starts correctly on port 3000.

OpenCode zal npx nodemon src/index.ts uitvoeren en bevestigen dat de server luistert. Je zou output moeten zien zoals Server running on http://localhost:3000.

Wat er zojuist is gebeurd (Functie: Build mode)

Build mode is de standaardagent van OpenCode. Deze heeft toegang tot alle tools: lezen/schrijven van bestanden, uitvoering in de terminal en het bewerken van code. Volgens de OpenCode documentatie kun je het zien als een AI-pair-programmer met volledige toegang tot je ontwikkelomgeving.

Fase 3: Het datamodel en de database maken (4 minuten)

Ontwerp het schema

Typ deze prompt:

Create a database module at src/db.ts that:
1. Initializes a SQLite database at ./data/bookmarks.db
2. Creates a bookmarks table with: id (auto-increment), url (text, unique),
   title (text), description (text, nullable), created_at (datetime),
   updated_at (datetime)
3. Creates a tags table with: id (auto-increment), name (text, unique)
4. Creates a bookmark_tags junction table for many-to-many relationships
5. Enables WAL mode for concurrent read performance
6. Creates an FTS5 virtual table for full-text search on title and description
Export a function to get the database instance.

OpenCode zal de volledige databasemodule genereren. Let op hoe het de FTS5-configuratie (Full-Text Search 5) afhandelt — dit is een SQLite-functie die later onze zoekfunctionaliteit zal aansturen.

Initialiseer de database bij het opstarten van de server

Import the database module in index.ts and initialize it when the server starts.
Log a confirmation message.

Maak de opencode.json-configuratie

Dit is een goed moment om projectconfiguratie te introduceren. Maak een bestand aan door OpenCode te vertellen:

Create an opencode.json file in the project root with the project name
"bookmark-manager" and a rule that says "This is a TypeScript Express API
using better-sqlite3. Follow RESTful conventions. Use async/await. Return
JSON responses with consistent error formatting."

Dit maakt het projectconfiguratiebestand aan dat OpenCode bij het opstarten leest. Het geeft de AI blijvende context over je project — programmeerstandaarden, architectuurbeslissingen en beperkingen — zodat je deze niet in elke prompt hoeft te herhalen.

Fase 4: De REST API-endpoints bouwen (5 minuten)

Genereer de routes

Create a routes module at src/routes/bookmarks.ts with these endpoints:
- POST /api/bookmarks — create a bookmark (validate url and title are present)
- GET /api/bookmarks — list all bookmarks with pagination (page, limit params)
- GET /api/bookmarks/:id — get a single bookmark with its tags
- PUT /api/bookmarks/:id — update a bookmark
- DELETE /api/bookmarks/:id — delete a bookmark and its tag associations
Use proper HTTP status codes. Return JSON with a consistent shape:
{ success: boolean, data: any, error?: string }

Registreer de routes

Import the bookmark routes in index.ts and register them. Also add
express.json() middleware and a global error handler.

Testen met curl

Start the server, then create a test bookmark using curl:
curl -X POST http://localhost:3000/api/bookmarks \
  -H "Content-Type: application/json" \
  -d '{"url": "https://opencode.ai", "title": "OpenCode - AI Coding Agent"}'
Then fetch all bookmarks to verify it was saved.

OpenCode zal deze commando's in je terminal uitvoeren en je de antwoorden tonen. Dit is waar de tool uitblinkt — je verlaat de terminal nooit en de AI verifieert zijn eigen werk.

Fase 5: Zoekfunctie toevoegen met FTS5 (4 minuten)

Maak kennis met de Plan-modus

Voordat we de zoekfunctie bouwen, gebruiken we de Plan mode om de implementatie te overdenken. Schakel over van modus:

/plan

Nu ben je in de Plan mode. De AI kan je code lezen en analyseren, maar kan geen bestanden wijzigen. Dit is handig voor het plannen voordat je wijzigingen aanbrengt.

Analyze my current database schema and FTS5 table. Plan how to implement a
search endpoint that queries the FTS5 table and returns bookmarks ranked by
relevance. Consider edge cases: empty queries, special characters, partial
matches.

OpenCode zal je code onderzoeken, een plan schrijven naar .opencode/plans/ en zijn aanpak uitleggen zonder bestanden aan te raken. Lees het plan, pas het indien nodig aan en schakel dan terug:

/build

Implementeer de zoekfunctie

Based on the plan, implement a GET /api/bookmarks/search?q=query endpoint
that uses the FTS5 virtual table for full-text search. Include snippet
highlighting and relevance ranking. Handle edge cases from the plan.

Test de zoekfunctie

Create three more test bookmarks with different titles and descriptions,
then test the search endpoint with a query that should match two of them.

Wat er zojuist is gebeurd (Functie: Plan mode)

De Plan/Build-workflow is hoe ervaren ontwikkelaars OpenCode gebruiken voor complexe taken. Eerst plannen, de aanpak beoordelen en dan bouwen. De planbestanden worden opgeslagen in .opencode/plans/ en kunnen later worden geraadpleegd door de build-agent. Dit voorkomt dat de AI gaandeweg grote structurele beslissingen neemt.

Fase 6: Het tagsysteem implementeren (4 minuten)

Maak tag-endpoints aan

Create a routes module at src/routes/tags.ts with:
- POST /api/tags — create a new tag
- GET /api/tags — list all tags with bookmark counts
- POST /api/bookmarks/:id/tags — add a tag to a bookmark
- DELETE /api/bookmarks/:id/tags/:tagId — remove a tag from a bookmark
- GET /api/bookmarks?tag=tagname — filter bookmarks by tag (update existing
  list endpoint to support this query parameter)
Register the tag routes in index.ts.

Test de tag-flow

Create two tags: "dev-tools" and "tutorials". Add the "dev-tools" tag to
the OpenCode bookmark. Then fetch bookmarks filtered by the "dev-tools" tag.

Fase 7: Een eenvoudige frontend bouwen (5 minuten)

Genereer de frontend

Create a public/ directory with a single-page frontend:
- index.html with a clean, minimal design (no framework, just HTML/CSS/JS)
- A form to add bookmarks (url, title, description)
- A search bar that queries the search endpoint with debounced input
- A list of bookmarks showing title, url, tags, and a delete button
- A tag filter sidebar that shows all tags with counts
- Use fetch() for API calls. Mobile responsive. No build step needed.
Serve the public/ directory as static files from Express.

OpenCode zal de volledige frontend genereren — HTML-structuur, CSS-styling en JavaScript voor API-interacties — in één keer. Het voordeel van het bouwen hiervan in de terminal met een AI-agent is dat deze onmiddellijk kan testen of de frontend verbinding maakt met de API.

Test de volledige stack

Start the server, open http://localhost:3000 in a description, and verify
that adding a bookmark from the form, searching, and filtering by tag all
work correctly.

Fase 8: Tests toevoegen met een aangepaste agent (5 minuten)

Maak een aangepaste test-agent

Dit is waar de functie aangepaste agents van OpenCode om de hoek komt kijken. In plaats van de generieke Build-agent te gebruiken voor het testen, maken we een gespecialiseerde.

Voeg dit toe aan je opencode.json:

{
  "agents": {
    "test": {
      "name": "Test Writer",
      "instructions": "You are a testing specialist. Write comprehensive tests using Vitest. Focus on edge cases and error paths. Never modify source code — only create and edit test files.",
      "tools": ["read", "write", "terminal"]
    }
  }
}

Schakel nu over naar de test-agent:

/agent test

Genereer tests

Write comprehensive tests for the bookmark API using Vitest and supertest.
Cover:
- Creating a bookmark with valid data
- Creating a bookmark with missing required fields
- Fetching all bookmarks with pagination
- Searching with FTS5 (matching and non-matching queries)
- Adding and removing tags
- Deleting a bookmark removes its tag associations
Use an in-memory SQLite database for test isolation.

Voer de tests uit

Install vitest and supertest as dev dependencies, add a test script to
package.json, then run the test suite.

Wat er zojuist is gebeurd (Functie: Custom Agents)

Met aangepaste agents kun je gerichte persona's maken met specifieke instructies en toegang tot tools. De test-agent die we hebben gemaakt, kan alleen bestanden lezen, testbestanden schrijven en terminalcommando's uitvoeren — hij kan de broncode niet wijzigen. Deze beperking voorkomt het veelvoorkomende probleem dat AI je broncode "repareert" wanneer tests falen, in plaats van de tests te repareren.

Je kunt agents maken voor elke gespecialiseerde workflow: code review, documentatie, databasemigraties, DevOps-scripts. De OpenCode agents documentatie bevat meer voorbeelden.

Bonus: Een MCP-server verbinden voor verbeterde functionaliteit

Als je je bookmark manager wilt uitbreiden, kun je externe tools verbinden via MCP (Model Context Protocol) servers.

Voorbeeld: Een Link Preview MCP-server toevoegen

Stel je voor dat je wilt dat OpenCode automatisch metadata (titel, beschrijving, favicon) van URL's ophaalt bij het maken van bookmarks. Je kunt een MCP-server verbinden die HTTP-fetching uitvoert:

Voeg dit toe aan je opencode.json:

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

Nu heeft OpenCode een nieuwe tool beschikbaar: het kan URL-metadata ophalen als onderdeel van zijn workflow. Wanneer je vraagt om "add a bookmark for https://example.com and auto-fill the title and description," zal het de MCP-server gebruiken om die gegevens op te halen.

Externe MCP-servers

Gebruik voor cloudservices externe MCP-servers met automatische OAuth-afhandeling:

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

OpenCode detecteert 401-antwoorden en start de OAuth-flow automatisch als de server Dynamic Client Registration ondersteunt.

Bonus: OpenCode gebruiken in CI/CD

OpenCode heeft een CLI mode die werkt zonder de TUI — perfect voor automatisering. Je kunt het gebruiken in GitHub Actions of elke CI-pipeline:

# Run a single prompt and exit
opencode -p "Review the changes in the last commit for security issues" --no-tui

# Use a specific model
opencode -m "claude-sonnet-4-6" -p "Generate a changelog entry for this release" --no-tui

Voor onze bookmark manager zou je een CI-stap kunnen toevoegen die OpenCode gebruikt om PR's automatisch te beoordelen. De OpenCode GitHub-integratie biedt een meer gestroomlijnde versie van deze workflow.

De volledige projectstructuur

Na het volgen van deze tutorial zou je project er zo uit moeten zien:

bookmark-manager/
  opencode.json          # OpenCode project config + custom agents + MCP
  package.json
  tsconfig.json
  src/
    index.ts             # Express server entry point
    db.ts                # SQLite database module with FTS5
    routes/
      bookmarks.ts       # CRUD + search endpoints
      tags.ts            # Tag management endpoints
  public/
    index.html           # Single-page frontend
  tests/
    bookmarks.test.ts    # API test suite
  data/
    bookmarks.db         # SQLite database (gitignored)
  .opencode/
    plans/               # Plans from Plan mode sessions

Wat je hebt geleerd

Door een echt project te bouwen, heb je geoefend met deze OpenCode-mogelijkheden:

Het belangrijkste verschil tussen OpenCode en andere AI-coding tools is dat het volledig open source is, in je terminal draait en je code of contextgegevens niet opslaat. Jij hebt de controle over de modellen, de gegevens blijven lokaal en de gemeenschap van meer dan 800 bijdragers zorgt ervoor dat het zich snel blijft ontwikkelen.

Voor teams die meerdere AI-tools gebruiken, werkt OpenCode goed als de terminal-gebaseerde aanvulling op IDE-assistenten. Bij ZBuild gebruiken we het vaak naast editor-gebaseerde tools voor verschillende onderdelen van de ontwikkelingsworkflow.

Volgende stappen

Nu je een werkende bookmark manager hebt en een goed begrip van OpenCode, zijn hier enkele richtingen om te verkennen:

1. Authenticatie toevoegen — Gebruik de Build-agent om JWT-gebaseerde authenticatie met gebruikersaccounts toe te voegen
2. Implementeren in productie — Vraag OpenCode om een Dockerfile te genereren en te implementeren op Fly.io of Railway
3. Bouw een browserextensie — Maak een Chrome-extensie die bookmarks toevoegt via de API
4. Ontdek meer Zen-modellen — Probeer Big Pickle, MiniMax M2.1, of draai een lokaal model via Ollama
5. Maak meer aangepaste agents — Een "refactor"-agent, een "docs"-agent of een "security audit"-agent

De OpenCode documentatie en de awesome-opencode repository bevatten meer plugins, thema's en community-configuraties om te verkennen.

Bronnen

• OpenCode — Official Documentation
• OpenCode — GitHub Repository
• OpenCode — Zen Models
• OpenCode — Agents Documentation
• OpenCode — MCP Servers
• OpenCode — CLI Mode
• OpenCode — Configuration
• OpenCode — GitHub Integration
• Ollama — OpenCode Integration
• awesome-opencode — Community Resources
• Composio — MCP with OpenCode
• Computing for Geeks — Setup OpenCode AI