Costruisci un Bookmark Manager Full-Stack con OpenCode in 30 Minuti (Passo dopo Passo)

Cosa stiamo costruendo

Dimenticate gli elenchi di funzionalità. Il modo migliore per imparare uno strumento è costruire qualcosa con esso.

In questo tutorial, utilizzerete OpenCode — l'agente di coding AI open-source con oltre 120K+ stelle GitHub — per costruire un gestore di segnalibri completo da zero. L'app avrà:

• Un'API REST con Express.js e TypeScript
• Un database SQLite con ricerca full-text
• Un sistema di tag per organizzare i segnalibri
• Un frontend semplice ma funzionale
• Unit tests

Ogni funzionalità di OpenCode viene introdotta nel momento in cui ne avete bisogno — non in una sezione astratta sulle funzionalità. Alla fine, saprete come installare OpenCode, configurare i modelli, usare le modalità Build e Plan, impostare i server MCP e creare agenti personalizzati — tutto perché li avrete usati per costruire un progetto reale.

Tempo: ~30 minuti Prerequisiti: Node.js 18+ installato, un terminale (macOS, Linux o WSL su Windows) Costo: Gratuito (usando i modelli OpenCode Zen)

Fase 1: Installazione di OpenCode e configurazione del progetto (5 minuti)

Installazione di OpenCode

Aprite il vostro terminale ed eseguite uno di questi comandi:

# 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

Verificate l'installazione:

opencode --version

Dovreste vedere il numero di versione. A partire dal March 2026, l'ultima release stabile è disponibile sulla OpenCode GitHub repository.

Creazione della directory del progetto

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

Avvio di OpenCode per la prima volta

opencode

Questo apre la TUI (Terminal User Interface) di OpenCode — un'interfaccia interattiva a schermo intero costruita con Bubble Tea. Vedrete un input di chat in basso e un riquadro di conversazione nell'area principale.

Scelta di un modello

Al primo avvio, OpenCode vi chiederà di selezionare un modello. Avete tre percorsi:

Gratuito (modelli Zen): Digitate /models e selezionate uno dei modelli Zen gratuiti. Per questo tutorial, Grok Code Fast 1 o GLM 4.7 funzionano bene. Questi sono gratuiti e non richiedono alcuna API key.

Locale (Ollama): Se avete Ollama installato, OpenCode lo rileverà automaticamente. Il modello consigliato per Ollama è glm-4.7:cloud.

A pagamento (portate la vostra chiave): Digitate /connect per collegare la vostra Anthropic, OpenAI o Google API key. Le chiavi sono memorizzate localmente in ~/.local/share/opencode/auth.json.

Per questo tutorial, qualsiasi modello funziona. I modelli con capacità superiori (Claude Sonnet 4.6, GPT-5.4) produrranno risultati migliori su compiti complessi, ma i modelli Zen gratuiti gestiscono tutto ciò che stiamo costruendo qui.

Fase 2: Scaffolding del progetto con la modalità Build (4 minuti)

OpenCode si avvia in modalità Build per impostazione predefinita. La modalità Build dà all'agente AI pieno accesso per creare file, modificare codice ed eseguire comandi. Questo è ciò che vogliamo per lo scaffolding.

Il vostro primo prompt

Digitate questo nella chat di OpenCode:

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:

1. Creerà un tsconfig.json
2. Installerà le dipendenze con npm install
3. Creerà src/index.ts con la configurazione del server Express
4. Aggiornerà package.json con gli script di avvio

Osservate la TUI — vedrete l'agente eseguire comandi nel terminale, creare file e spiegare cosa fa in ogni passaggio. Questa non è generazione di codice nel vuoto; OpenCode ha pieno accesso al vostro filesystem e al terminale.

Verifica del funzionamento

Una volta che OpenCode ha finito, ditegli:

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

OpenCode eseguirà npx nodemon src/index.ts e confermerà che il server è in ascolto. Dovreste vedere un output come Server running on http://localhost:3000.

Cosa è appena successo (Funzionalità: Build Mode)

La modalità Build è l'agente predefinito di OpenCode. Ha accesso a tutti gli strumenti: lettura/scrittura di file, esecuzione nel terminale e modifica del codice. Secondo la OpenCode documentation, potete pensarlo come un programmatore AI in coppia con pieno accesso al vostro ambiente di sviluppo.

Fase 3: Creazione del modello dati e del database (4 minuti)

Progettazione dello schema

Digitate questo 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 genererà il modulo database completo. Prestate attenzione a come gestisce la configurazione FTS5 (Full-Text Search 5) — questa è una funzionalità di SQLite che alimenterà la nostra funzione di ricerca più avanti.

Inizializzazione del database all'avvio del server

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

Creazione della configurazione opencode.json

Questo è un buon momento per introdurre la configurazione del progetto. Create un file dicendo a OpenCode:

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."

Questo crea il file di configurazione del progetto che OpenCode legge all'avvio. Fornisce all'AI un contesto persistente sul vostro progetto — standard di codifica, decisioni architettoniche e vincoli — in modo da non doverli ripetere in ogni prompt.

Fase 4: Costruzione degli endpoint dell'API REST (5 minuti)

Generazione delle rotte

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 }

Registrazione delle rotte

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

Test con 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 eseguirà questi comandi nel vostro terminale e vi mostrerà le risposte. È qui che lo strumento brilla — non lasciate mai il terminale e l'AI verifica il proprio lavoro.

Fase 5: Aggiunta della ricerca con FTS5 (4 minuti)

Introduzione alla modalità Plan

Prima di costruire la ricerca, usiamo la modalità Plan per riflettere sull'implementazione. Cambiate modalità:

/plan

Ora siete in modalità Plan. L'AI può leggere il vostro codice e analizzarlo ma non può modificare alcun file. Questo è utile per pianificare prima di apportare modifiche.

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 esaminerà il vostro codice, scriverà un piano in .opencode/plans/ e spiegherà il suo approccio senza toccare alcun file. Leggete il piano, regolate se necessario, quindi tornate indietro:

/build

Implementazione della ricerca

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 della ricerca

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

Cosa è appena successo (Funzionalità: Plan Mode)

Il workflow Plan/Build è il modo in cui gli sviluppatori esperti usano OpenCode per compiti complessi. Pianificare prima, revisionare l'approccio, poi costruire. I file di piano sono salvati in .opencode/plans/ e possono essere referenziati in seguito dall'agente di build. Questo impedisce all'AI di prendere decisioni strutturali importanti al volo.

Fase 6: Implementazione del sistema di tag (4 minuti)

Creazione degli endpoint per i tag

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 del flusso dei tag

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: Costruzione di un frontend semplice (5 minuti)

Generazione del 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 genererà il frontend completo — struttura HTML, stile CSS e JavaScript per le interazioni API — in un unico passaggio. Il vantaggio di costruire questo nel terminale con un agente AI è che può testare immediatamente se il frontend si connette all'API.

Test dell'intero 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: Aggiunta di test con un agente personalizzato (5 minuti)

Creazione di un agente di test personalizzato

È qui che entra in gioco la funzionalità degli agenti personalizzati di OpenCode. Invece di usare l'agente Build generico per i test, ne creeremo uno specializzato.

Aggiungete questo al vostro 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"]
    }
  }
}

Ora passate all'agente di test:

/agent test

Generazione dei test

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.

Esecuzione dei test

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

Cosa è appena successo (Funzionalità: Custom Agents)

Gli agenti personalizzati permettono di creare persona focalizzate con istruzioni specifiche e accesso agli strumenti. L'agente di test che abbiamo creato può solo leggere file, scrivere file di test ed eseguire comandi nel terminale — non può modificare il codice sorgente. Questo vincolo impedisce il problema comune dell'AI che "corregge" il codice sorgente quando i test falliscono invece di correggere i test.

Potete creare agenti per qualsiasi workflow specializzato: revisione del codice, documentazione, migrazioni di database, script DevOps. La OpenCode agents documentation contiene altri esempi.

Bonus: Connessione di un server MCP per funzionalità avanzate

Se volete estendere il vostro gestore di segnalibri, potete connettere strumenti esterni tramite server MCP (Model Context Protocol).

Esempio: Aggiunta di un server MCP per l'anteprima dei link

Immaginate di volere che OpenCode recuperi automaticamente i metadati (titolo, descrizione, favicon) dagli URL quando create i segnalibri. Potete connettere un server MCP che esegue il recupero HTTP:

Aggiungete questo al vostro opencode.json:

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

Ora OpenCode ha un nuovo strumento disponibile: può recuperare i metadati degli URL come parte del suo workflow. Quando gli chiederete di "aggiungere un segnalibro per https://example.com e compilare automaticamente titolo e descrizione", utilizzerà il server MCP per recuperare quei dati.

Server MCP remoti

Per i servizi cloud, usate server MCP remoti con gestione automatica di OAuth:

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

OpenCode rileva le risposte 401 e avvia automaticamente il flusso OAuth se il server supporta la registrazione dinamica dei client (Dynamic Client Registration).

Bonus: Utilizzo di OpenCode in CI/CD

OpenCode ha una modalità CLI che funziona senza la TUI — perfetta per l'automazione. Potete usarla in GitHub Actions o in qualsiasi pipeline CI:

# 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

Per il nostro gestore di segnalibri, potresti aggiungere un passaggio CI che esegue OpenCode per revisionare automaticamente le PR. L'OpenCode GitHub integration fornisce una versione più snella di questo workflow.

La struttura completa del progetto

Dopo aver seguito questo tutorial, il vostro progetto dovrebbe apparire così:

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

Cosa avete imparato

Costruendo un progetto reale, avete fatto pratica con queste capacità di OpenCode:

La differenza chiave tra OpenCode e altri strumenti di codifica AI è che è interamente open source, gira nel vostro terminale e non memorizza i vostri dati di codice o contesto. Voi controllate i modelli, i dati rimangono locali e la comunità di oltre 800 contributori lo fa evolvere velocemente.

Per i team che usano più strumenti AI, OpenCode funziona bene come complemento basato su terminale agli assistenti IDE. Presso ZBuild, lo usiamo spesso insieme a strumenti basati su editor per diverse parti del workflow di sviluppo.

Passaggi successivi

Ora che avete un gestore di segnalibri funzionante e una solida comprensione di OpenCode, ecco alcune direzioni da esplorare:

1. Aggiungere l'autenticazione — Usate l'agente Build per aggiungere l'autenticazione basata su JWT con account utente
2. Distribuire in produzione — Chiedete a OpenCode di generare un Dockerfile e di distribuire su Fly.io o Railway
3. Costruire un'estensione del browser — Create un'estensione per Chrome che aggiunga segnalibri tramite l'API
4. Esplorare altri modelli Zen — Provate Big Pickle, MiniMax M2.1, o eseguite un modello locale tramite Ollama
5. Creare più agenti personalizzati — Un agente di "refactoring", un agente di "documentazione" o un agente di "audit di sicurezza"

La documentazione di OpenCode e la repository awesome-opencode contengono altri plugin, temi e configurazioni della comunità da esplorare.

Fonti

• 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