Zbuduj Full-Stack Bookmark Manager z OpenCode w 30 minut (krok po kroku)

Co budujemy

Zapomnij o listach funkcji. Najlepszym sposobem na naukę narzędzia jest zbudowanie czegoś za jego pomocą.

W tym samouczku użyjesz OpenCode — otwartoźródłowego agenta kodującego AI z ponad 120K+ gwiazdkami na GitHub — aby zbudować od podstaw kompletny menedżer zakładek. Aplikacja będzie posiadać:

• API REST z Express.js i TypeScript
• Bazę danych SQLite z wyszukiwaniem pełnotekstowym
• System tagów do organizowania zakładek
• Prosty, ale funkcjonalny frontend
• Testy jednostkowe

Każda funkcja OpenCode zostanie wprowadzona w momencie, gdy będzie potrzebna — a nie w abstrakcyjnej sekcji funkcji. Do końca dowiesz się, jak zainstalować OpenCode, konfigurować modele, używać trybów Build i Plan, konfigurować serwery MCP i tworzyć niestandardowych agentów — a wszystko to dlatego, że użyłeś ich do zbudowania prawdziwego projektu.

Czas: ~30 minut Wymagania wstępne: Zainstalowany Node.js 18+, terminal (macOS, Linux lub WSL w systemie Windows) Koszt: Za darmo (używając modeli OpenCode Zen)

Faza 1: Instalacja OpenCode i konfiguracja projektu (5 minut)

Zainstaluj OpenCode

Otwórz terminal i uruchom jedno z tych poleceń:

# Opcja 1: npm (zalecane)
npm i -g opencode-ai@latest

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

# Opcja 3: Jednoliniowy instalator
curl -fsSL https://opencode.ai/install.sh | bash

Zweryfikuj instalację:

opencode --version

Powinieneś zobaczyć numer wersji. Według stanu na Marzec 2026, najnowsza stabilna wersja jest dostępna w repozytorium GitHub OpenCode.

Utwórz katalog projektu

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

Uruchom OpenCode po raz pierwszy

opencode

Spowoduje to otwarcie TUI (Terminal User Interface) OpenCode — pełnoekranowego interaktywnego interfejsu zbudowanego z Bubble Tea. Zobaczysz pole wprowadzania czatu na dole i panel rozmowy w głównym obszarze.

Wybierz model

Przy pierwszym uruchomieniu OpenCode poprosi Cię o wybranie modelu. Masz trzy ścieżki:

Darmowe (modele Zen): Wpisz /models i wybierz jeden z darmowych modeli Zen. W tym samouczku dobrze sprawdzą się Grok Code Fast 1 lub GLM 4.7. Są one darmowe i nie wymagają klucza API.

Lokalne (Ollama): Jeśli masz zainstalowaną Ollama, OpenCode wykryje ją automatycznie. Zalecany model dla Ollama to glm-4.7:cloud.

Płatne (własny klucz): Wpisz /connect, aby połączyć swój klucz API Anthropic, OpenAI lub Google. Klucze są przechowywane lokalnie w ~/.local/share/opencode/auth.json.

W tym samouczku zadziała dowolny model. Modele o wyższych możliwościach (Claude Sonnet 4.6, GPT-5.4) dadzą lepsze wyniki w złożonych zadaniach, ale darmowe modele Zen poradzą sobie ze wszystkim, co tutaj budujemy.

Faza 2: Tworzenie szkieletu projektu w trybie Build (4 minuty)

OpenCode domyślnie uruchamia się w trybie Build. Tryb Build daje agentowi AI pełny dostęp do tworzenia plików, edycji kodu i uruchamiania poleceń. Tego właśnie chcemy do stworzenia szkieletu.

Twój pierwszy prompt

Wpisz to w czacie 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. Utworzy tsconfig.json
2. Zainstaluje zależności za pomocą npm install
3. Utworzy src/index.ts z konfiguracją serwera Express
4. Zaktualizuje package.json o skrypty startowe

Obserwuj TUI — zobaczysz, jak agent wykonuje polecenia terminala, tworzy pliki i wyjaśnia, co robi na każdym kroku. To nie jest generowanie kodu w próżni; OpenCode ma pełny dostęp do Twojego systemu plików i terminala.

Zweryfikuj, czy działa

Gdy OpenCode skończy, powiedz mu:

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

OpenCode uruchomi npx nodemon src/index.ts i potwierdzi, że serwer nasłuchuje. Powinieneś zobaczyć dane wyjściowe typu Server running on http://localhost:3000.

Co się właśnie stało (Funkcja: Tryb Build)

Tryb Build to domyślny agent OpenCode. Ma on dostęp do wszystkich narzędzi: odczytu/zapisu plików, wykonywania poleceń w terminalu i edycji kodu. Zgodnie z dokumentacją OpenCode, możesz myśleć o nim jak o programiście parowym AI z pełnym dostępem do Twojego środowiska programistycznego.

Faza 3: Tworzenie modelu danych i bazy danych (4 minuty)

Zaprojektuj schemat

Wpisz ten 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 wygeneruje pełny moduł bazy danych. Zwróć uwagę, jak radzi sobie z konfiguracją FTS5 (Full-Text Search 5) — jest to funkcja SQLite, która później zasili naszą funkcjonalność wyszukiwania.

Zainicjuj bazę danych przy starcie serwera

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

Utwórz konfigurację opencode.json

To dobry moment na wprowadzenie konfiguracji projektu. Utwórz plik, mówiąc do 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."

Tworzy to plik konfiguracyjny projektu, który OpenCode odczytuje przy starcie. Daje to AI trwały kontekst dotyczący Twojego projektu — standardy kodowania, decyzje architektoniczne i ograniczenia — dzięki czemu nie musisz ich powtarzać w każdym prompcie.

Faza 4: Budowanie endpointów API REST (5 minut)

Wygeneruj trasy

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 }

Zarejestruj trasy

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

Testuj za pomocą 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 wykona te polecenia w Twoim terminalu i pokaże Ci odpowiedzi. To tutaj narzędzie błyszczy — nigdy nie opuszczasz terminala, a AI samo weryfikuje swoją pracę.

Faza 5: Dodawanie wyszukiwania z FTS5 (4 minuty)

Wprowadzenie do trybu Plan

Zanim zbudujemy wyszukiwanie, użyjmy trybu Plan, aby przemyśleć implementację. Przełącz tryby:

/plan

Jesteś teraz w trybie Plan. AI może czytać Twój kod i analizować go, ale nie może modyfikować żadnych plików. Jest to przydatne do planowania przed wprowadzaniem zmian.

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 przeanalizuje Twój kod, zapisze plan w .opencode/plans/ i wyjaśni swoje podejście bez dotykania plików. Przeczytaj plan, dostosuj go w razie potrzeby, a następnie przełącz się z powrotem:

/build

Zaimplementuj wyszukiwanie

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.

Testuj wyszukiwanie

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

Co się właśnie stało (Funkcja: Tryb Plan)

Przepływ pracy Plan/Build to sposób, w jaki doświadczeni programiści używają OpenCode przy złożonych zadaniach. Najpierw zaplanuj, przejrzyj podejście, a potem buduj. Pliki planów są zapisywane w .opencode/plans/ i mogą być przywoływane później przez agenta budującego. Zapobiega to podejmowaniu przez AI dużych decyzji strukturalnych na bieżąco.

Faza 6: Implementacja systemu tagów (4 minuty)

Utwórz endpointy tagów

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.

Testuj przepływ tagów

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: Budowanie prostego frontendu (5 minut)

Wygeneruj 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 wygeneruje kompletny frontend — strukturę HTML, stylizację CSS i JavaScript do interakcji z API — w jednym przebiegu. Zaletą budowania tego w terminalu z agentem AI jest to, że może on natychmiast przetestować, czy frontend łączy się z API.

Testuj cały stos

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: Dodawanie testów za pomocą niestandardowego agenta (5 minut)

Utwórz niestandardowego agenta testowego

W tym miejscu pojawia się funkcja niestandardowych agentów OpenCode. Zamiast używać ogólnego agenta Build do testowania, stworzymy wyspecjalizowanego agenta.

Dodaj to do swojego 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"]
    }
  }
}

Teraz przełącz się na agenta testowego:

/agent test

Wygeneruj testy

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.

Uruchom testy

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

Co się właśnie stało (Funkcja: Niestandardowi agenci)

Niestandardowi agenci pozwalają tworzyć skoncentrowane persony ze specyficznymi instrukcjami i dostępem do narzędzi. Agent testowy, którego stworzyliśmy, może tylko czytać pliki, pisać pliki testowe i uruchamiać polecenia terminala — nie może modyfikować kodu źródłowego. To ograniczenie zapobiega powszechnemu problemowi AI „naprawiającego” Twój kod źródłowy, gdy testy kończą się niepowodzeniem, zamiast naprawiać testy.

Możesz tworzyć agentów dla dowolnego wyspecjalizowanego przepływu pracy: przeglądu kodu, dokumentacji, migracji baz danych, skryptów DevOps. Dokumentacja agentów OpenCode zawiera więcej przykładów.

Bonus: Podłączanie serwera MCP dla rozszerzonej funkcjonalności

Jeśli chcesz rozbudować swój menedżer zakładek, możesz podłączyć zewnętrzne narzędzia za pomocą serwerów MCP (Model Context Protocol).

Przykład: Dodawanie serwera MCP do podglądu linków

Wyobraź sobie, że chcesz, aby OpenCode automatycznie pobierał metadane (tytuł, opis, favicon) z adresów URL podczas tworzenia zakładek. Możesz podłączyć serwer MCP, który zajmuje się pobieraniem przez HTTP:

Dodaj to do swojego opencode.json:

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

Teraz OpenCode ma dostępne nowe narzędzie: może pobierać metadane URL jako część swojego przepływu pracy. Kiedy poprosisz go o „dodanie zakładki dla https://example.com i automatyczne wypełnienie tytułu i opisu”, użyje serwera MCP do pobrania tych danych.

Zdalne serwery MCP

W przypadku usług chmurowych używaj zdalnych serwerów MCP z automatyczną obsługą OAuth:

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

OpenCode wykrywa odpowiedzi 401 i automatycznie inicjuje przepływ OAuth, jeśli serwer obsługuje Dynamic Client Registration.

Bonus: Używanie OpenCode w CI/CD

OpenCode posiada tryb CLI, który działa bez TUI — idealny do automatyzacji. Możesz go używać w GitHub Actions lub dowolnym potoku CI:

# Uruchom pojedynczy prompt i wyjdź
opencode -p "Review the changes in the last commit for security issues" --no-tui

# Użyj konkretnego modelu
opencode -m "claude-sonnet-4-6" -p "Generate a changelog entry for this release" --no-tui

Dla naszego menedżera zakładek możesz dodać krok CI, który uruchamia OpenCode w celu automatycznego przeglądu PR. Integracja z GitHub OpenCode zapewnia bardziej usprawnioną wersję tego przepływu pracy.

Kompletna struktura projektu

Po wykonaniu tego samouczka Twój projekt powinien wyglądać następująco:

bookmark-manager/
  opencode.json          # Konfiguracja projektu OpenCode + agenci + MCP
  package.json
  tsconfig.json
  src/
    index.ts             # Punkt wejścia serwera Express
    db.ts                # Moduł bazy danych SQLite z FTS5
    routes/
      bookmarks.ts       # Endpointy CRUD + wyszukiwanie
      tags.ts            # Endpointy zarządzania tagami
  public/
    index.html           # Jednostronicowy frontend
  tests/
    bookmarks.test.ts    # Zestaw testów API
  data/
    bookmarks.db         # Baza danych SQLite (gitignored)
  .opencode/
    plans/               # Plany z sesji trybu Plan

Czego się nauczyłeś

Budując prawdziwy projekt, przećwiczyłeś następujące możliwości OpenCode:

Kluczową różnicą między OpenCode a innymi narzędziami do kodowania AI jest to, że jest on całkowicie otwartoźródłowy, działa w Twoim terminalu i nie przechowuje Twojego kodu ani danych kontekstowych. Ty kontrolujesz modele, dane pozostają lokalnie, a społeczność ponad 800+ współtwórców sprawia, że narzędzie szybko ewoluuje.

Dla zespołów korzystających z wielu narzędzi AI, OpenCode dobrze sprawdza się jako oparte na terminalu uzupełnienie asystentów IDE. W ZBuild często używamy go wraz z narzędziami opartymi na edytorze do różnych części procesu programowania.

Następne kroki

Teraz, gdy masz działający menedżer zakładek i solidne zrozumienie OpenCode, oto kilka kierunków do eksploracji:

1. Dodaj uwierzytelnianie — Użyj agenta Build, aby dodać uwierzytelnianie oparte na JWT z kontami użytkowników.
2. Wdróż na produkcję — Poproś OpenCode o wygenerowanie pliku Dockerfile i wdrożenie go na Fly.io lub Railway.
3. Zbuduj rozszerzenie przeglądarki — Utwórz rozszerzenie Chrome, które dodaje zakładki przez API.
4. Eksploruj więcej modeli Zen — Wypróbuj Big Pickle, MiniMax M2.1 lub uruchom lokalny model przez Ollama.
5. Twórz więcej niestandardowych agentów — Agenta „refaktoryzującego”, agenta „dokumentacji” lub agenta „audytu bezpieczeństwa”.

Dokumentacja OpenCode oraz repozytorium awesome-opencode zawierają więcej wtyczek, motywów i konfiguracji społeczności do odkrycia.

Źródła

• OpenCode — Oficjalna Dokumentacja
• OpenCode — Repozytorium GitHub
• OpenCode — Modele Zen
• OpenCode — Dokumentacja Agentów
• OpenCode — Serwery MCP
• OpenCode — Tryb CLI
• OpenCode — Konfiguracja
• OpenCode — Integracja z GitHub
• Ollama — Integracja z OpenCode
• awesome-opencode — Zasoby Społeczności
• Composio — MCP z OpenCode
• Computing for Geeks — Konfiguracja OpenCode AI