Zgradite Full-Stack Bookmark Manager z OpenCode v 30 minutah (korak za korakom)

Kaj gradimo

Pozabite na sezname funkcij. Najboljši način za učenje orodja je, da z njim nekaj zgradite.

V tem vodiču boste uporabili OpenCode — odprtokodnega AI coding agenta z več kot 120K+ GitHub zvezdicami — za izgradnjo celovitega upravljalnika zaznamkov iz nič. Aplikacija bo imela:

• REST API z Express.js in TypeScript
• SQLite podatkovno bazo s full-text search
• Sistem oznak za organiziranje zaznamkov
• Preprost, a funkcionalen frontend
• Unit testi

Vsaka OpenCode funkcija bo predstavljena v trenutku, ko jo potrebujete — ne v abstraktnem razdelku o funkcijah. Do konca boste vedeli, kako namestiti OpenCode, konfigurirati modele, uporabljati Build in Plan načine, nastaviti MCP strežnike in ustvariti custom agente — vse zato, ker ste jih uporabili za izgradnjo pravega projekta.

Čas: ~30 minut Predpogoji: Nameščen Node.js 18+, terminal (macOS, Linux ali WSL na Windows) Strošek: Brezplačno (z uporabo OpenCode Zen modelov)

Faza 1: Namestitev OpenCode in nastavitev projekta (5 minut)

Namestite OpenCode

Odprite svoj terminal in zaženite enega od teh ukazov:

# Možnost 1: npm (priporočeno)
npm i -g opencode-ai@latest

# Možnost 2: Homebrew (macOS/Linux)
brew install sst/tap/opencode

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

Preverite namestitev:

opencode --version

Videti bi morali številko različice. Od Marca 2026 je najnovejša stabilna izdaja na voljo v OpenCode GitHub repository.

Ustvarite projektni imenik

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

Prvi zagon OpenCode

opencode

To odpre OpenCode TUI (Terminal User Interface) — celozaslonski interaktivni vmesnik, zgrajen z Bubble Tea. Spodaj boste videli polje za vnos klepeta, v glavnem delu pa okno za pogovor.

Izberite model

Ob prvem zagonu vas bo OpenCode pozval k izbiri modela. Na voljo imate tri poti:

Brezplačno (Zen modeli): Vtipkajte /models in izberite enega od free Zen models. Za ta vodič sta primerna Grok Code Fast 1 ali GLM 4.7. Ti so brezplačni in ne zahtevajo API ključa.

Lokalno (Ollama): Če imate nameščen Ollama, ga bo OpenCode zaznal samodejno. priporočen model za Ollama je glm-4.7:cloud.

Plačljivo (prinesite svoj ključ): Vtipkajte /connect, da povežete svoj Anthropic, OpenAI ali Google API ključ. Ključi so shranjeni lokalno v ~/.local/share/opencode/auth.json.

Za ta vodič deluje katerikoli model. Modeli z višjimi zmogljivostmi (Claude Sonnet 4.6, GPT-5.4) bodo dali boljše rezultate pri kompleksnih nalogah, vendar brezplačni Zen modeli zmorejo vse, kar gradimo tukaj.

Faza 2: Ogrodje projekta z Build načinom (4 minute)

OpenCode se privzeto zažene v Build načinu. Build način daje AI agentu polni dostop do ustvarjanja datotek, urejanja kode in izvajanja ukazov. To je tisto, kar želimo za postavitev ogrodja.

Vaš prvi prompt

Vtipkajte to v OpenCode klepet:

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 bo:

1. Ustvaril tsconfig.json
2. Namestil odvisnosti z npm install
3. Ustvaril src/index.ts z nastavitvijo Express strežnika
4. Posodobil package.json z zagonskimi skriptami

Opazujte TUI — videli boste agenta, kako izvaja terminal ukaze, ustvarja datoteke in razlaga svoje korake. To ni generiranje kode v prazno; OpenCode ima polni dostop do vašega datotečnega sistema in terminala.

Preverite delovanje

Ko OpenCode konča, mu recite:

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

OpenCode bo zagnal npx nodemon src/index.ts in potrdil, da strežnik posluša. Videti bi morali izpis kot Server running on http://localhost:3000.

Kaj se je pravkar zgodilo (Funkcija: Build način)

Build način je OpenCode privzeti agent. Ima dostop do vseh orodij: branje/pisanje datotek, izvajanje v terminalu in urejanje kode. Glede na OpenCode documentation si ga lahko predstavljate kot AI pair programmer-ja s polnim dostopom do vašega razvojnega okolja.

Faza 3: Ustvarjanje podatkovnega modela in podatkovne baze (4 minute)

Zasnova sheme

Vtipkajte ta 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 bo generiral celoten podatkovni modul. Bodite pozorni na to, kako upravlja z nastavitvijo FTS5 (Full-Text Search 5) — to je SQLite funkcija, ki bo pozneje omogočila naše iskanje.

Inicializacija podatkovne baze ob zagonu strežnika

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

Ustvarite opencode.json konfiguracijo

To je primeren trenutek za predstavitev projektne konfiguracije. Ustvarite datoteko tako, da rečete 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."

To ustvari project configuration file, ki ga OpenCode prebere ob zagonu. AI-ju daje trajen kontekst o vašem projektu — standarde kodiranja, arhitekturne odločitve in omejitve — tako da vam jih ni treba ponavljati v vsakem promptu.

Faza 4: Izgradnja REST API končnih točk (5 minut)

Generiranje poti (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 }

Registracija poti

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

Testiranje s 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 bo izvedel te ukaze v vašem terminalu in vam pokazal odgovore. Tukaj orodje zares zablesti — nikoli ne zapustite terminala, AI pa sam preveri svoje delo.

Faza 5: Dodajanje iskanja s FTS5 (4 minute)

Predstavitev Plan načina

Preden zgradimo iskanje, uporabimo Plan način za premislek o implementaciji. Preklopite načina:

/plan

Zdaj ste v Plan načinu. AI lahko bere vašo kodo in jo analizira, ne more pa spreminjati datotek. To je uporabno za načrtovanje pred izvajanjem sprememb.

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 bo pregledal vašo kodo, zapisal načrt v .opencode/plans/ in razložil svoj pristop brez spreminjanja datotek. Preberite načrt, ga po potrebi prilagodite in nato preklopite nazaj:

/build

Implementacija iskanja

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.

Testiranje iskanja

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

Kaj se je pravkar zgodilo (Funkcija: Plan način)

Workflow Plan/Build je način, kako izkušeni razvijalci uporabljajo OpenCode pri kompleksnih nalogah. Najprej načrtujte, nato preglejte pristop in nazadnje gradite. Datoteke načrtov se shranijo v .opencode/plans/ in se na njih lahko sklicujete pozneje preko build agenta. To preprečuje, da bi AI sprejemal velike strukturne odločitve sproti.

Faza 6: Implementacija sistema oznak (4 minute)

Ustvarjanje končnih točk za oznake

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.

Testiranje poteka oznak

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.

Faza 7: Izgradnja preprostega frontenda (5 minut)

Generiranje frontenda

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 bo v enem koraku generiral celoten frontend — HTML strukturo, CSS stiliziranje in JavaScript za interakcijo z API. Prednost gradnje tega v terminalu z AI agentom je, da lahko takoj preveri, ali se frontend poveže z API.

Testiranje celotnega sklada (Full 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.

Faza 8: Dodajanje testov s Custom agentom (5 minut)

Ustvarjanje Custom testnega agenta

Tukaj nastopi funkcija OpenCode custom agents. Namesto uporabe generičnega Build agenta za testiranje, bomo ustvarili specializiranega.

Dodajte to v svoj 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"]
    }
  }
}

Zdaj preklopite na testnega agenta:

/agent test

Generiranje testov

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.

Zagon testov

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

Kaj se je pravkar zgodilo (Funkcija: Custom agenti)

Custom agenti vam omogočajo ustvarjanje usmerjenih person s specifičnimi navodili in dostopom do orodij. Testni agent, ki smo ga ustvarili, lahko samo bere datoteke, piše testne datoteke in izvaja terminal ukaze — ne more spreminjati izvorne kode. Ta omejitev preprečuje pogosto težavo, ko AI "popravlja" vašo izvorno kodo ob neuspešnih testih, namesto da bi popravil teste.

Agente lahko ustvarite za kateri koli specializiran workflow: code review, dokumentacijo, migracije podatkovnih baz, DevOps skripte. OpenCode agents documentation vsebuje več primerov.

Bonus: Povezava z MCP strežnikom za razširjeno funkcionalnost

Če želite razširiti svoj upravljalnik zaznamkov, lahko povežete zunanja orodja preko MCP (Model Context Protocol) strežnikov.

Primer: Dodajanje MCP strežnika za predogled povezav

Predstavljajte si, da želite, da OpenCode samodejno pridobi metapodatke (naslov, opis, favicon) iz URL-jev ob ustvarjanju zaznamkov. Lahko povežete MCP strežnik, ki izvaja HTTP pridobivanje:

Dodajte to v svoj opencode.json:

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

Zdaj ima OpenCode na voljo novo orodje: kot del svojega workflow-a lahko pridobiva metapodatke URL-jev. Ko ga prosite, naj "doda zaznamek za https://example.com in samodejno izpolni naslov in opis", bo uporabil MCP strežnik za pridobitev teh podatkov.

Oddaljeni MCP strežniki

Za storitve v oblaku uporabite oddaljene MCP strežnike s samodejnim upravljanjem OAuth:

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

OpenCode zazna 401 odgovore in samodejno sproži OAuth flow, če strežnik podpira Dynamic Client Registration.

Bonus: Uporaba OpenCode v CI/CD

OpenCode ima CLI mode, ki deluje brez TUI — idealno za avtomatizacijo. Uporabite ga lahko v GitHub Actions ali katerikoli CI pipelinu:

# Zaženite en prompt in zapustite
opencode -p "Review the changes in the last commit for security issues" --no-tui

# Uporabite specifičen model
opencode -m "claude-sonnet-4-6" -p "Generate a changelog entry for this release" --no-tui

Za naš upravljalnik zaznamkov bi lahko dodali CI korak, ki samodejno uporabi OpenCode za pregled PR-jev. OpenCode GitHub integration omogoča bolj optimizirano različico tega workflow-a.

Celotna struktura projekta

Po končanem vodiču bi moral vaš projekt izgledati takole:

bookmark-manager/
  opencode.json          # OpenCode konfiguracija projekta + custom agenti + MCP
  package.json
  tsconfig.json
  src/
    index.ts             # Vstopna točka za Express strežnik
    db.ts                # SQLite podatkovni modul s FTS5
    routes/
      bookmarks.ts       # CRUD + search končne točke
      tags.ts            # Končne točke za upravljanje oznak
  public/
    index.html           # Single-page frontend
  tests/
    bookmarks.test.ts    # API testna suita
  data/
    bookmarks.db         # SQLite podatkovna baza (gitignored)
  .opencode/
    plans/               # Načrti iz sej v Plan načinu

Kaj ste se naučili

Z izgradnjo pravega projekta ste vadili naslednje OpenCode zmogljivosti:

Ključna razlika med OpenCode in drugimi AI orodji za kodiranje je v tem, da je popolnoma odprtokoden, deluje v vašem terminalu in ne shranjuje vaše kode ali podatkov o kontekstu. Vi nadzorujete modele, podatki ostanejo lokalno, skupnost z več kot 800+ prispevniki pa skrbi za hiter razvoj.

Za ekipe, ki uporabljajo več AI orodij, OpenCode deluje odlično kot terminalska dopolnitev IDE asistentom. Pri ZBuild ga pogosto uporabljamo skupaj z orodji v urejevalnikih za različne dele razvojnega workflow-a.

Naslednji koraki

Zdaj, ko imate delujoč upravljalnik zaznamkov in solidno razumevanje OpenCode, je tukaj nekaj smeri za nadaljnje raziskovanje:

1. Dodajte avtentikacijo — Uporabite Build agenta za dodajanje JWT avtentikacije z uporabniškimi računi
2. Namestitev v produkcijo — Prosite OpenCode, naj generira Dockerfile in ga namesti na Fly.io ali Railway
3. Zgradite razširitev za brskalnik — Ustvarite Chrome razširitev, ki dodaja zaznamke preko API-ja
4. Raziščite več Zen modelov — Preizkusite Big Pickle, MiniMax M2.1 ali zaženite lokalni model preko Ollama
5. Ustvarite več custom agentov — Agent za "refactor", agent za "dokumentacijo" ali agent za "varnostni pregled"

OpenCode documentation in awesome-opencode repository vsebujeta več vtičnikov, tem in konfiguracij skupnosti za raziskovanje.

Viri

• 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