Rakenna Full-Stack Bookmark Manager OpenCode-työkalulla 30 minuutissa (Step-by-Step)

Mitä olemme rakentamassa

Unohda ominaisuusluettelot. Paras tapa oppia työkalu on rakentaa jotain sen avulla.

Tässä opetusohjelmassa käytät OpenCode — avoimen lähdekoodin AI-koodausagenttia, jolla on 120K+ GitHub-tähteä — rakentaaksesi täydellisen kirjanmerkkien hallintasovelluksen tyhjästä. Sovelluksessa on:

• REST API Express.js:llä ja TypeScriptillä
• SQLite-tietokanta täystekstihaulla
• Tunnistejärjestelmä kirjanmerkkien järjestämiseen
• Yksinkertainen mutta toimiva frontend
• Unit tests

Jokainen OpenCode-ominaisuus esitellään sillä hetkellä, kun tarvitset sitä — ei abstraktissa ominaisuusosiossa. Lopuksi tiedät, miten asentaa OpenCode, konfiguroida malleja, käyttää Build- ja Plan-tiloja, asettaa MCP-palvelimia ja luoda mukautettuja agentteja — kaikki siksi, että käytit niitä todellisen projektin rakentamiseen.

Aika: ~30 minuuttia Esivaatimukset: Node.js 18+ asennettuna, terminaali (macOS, Linux tai WSL Windowsissa) Kustannukset: Ilmainen (käyttäen OpenCode Zen -malleja)

Vaihe 1: OpenCode-asennus ja projektin pystytys (5 minuuttia)

Asenna OpenCode

Avaa terminaali ja aja yksi näistä komennoista:

# 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

Varmista asennus:

opencode --version

Sinun pitäisi nähdä versionumero. March 2026 mennessä uusin vakaa julkaisu on saatavilla OpenCode GitHub repository -sivulla.

Luo projektihakemisto

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

Käynnistä OpenCode ensimmäistä kertaa

opencode

Tämä avaa OpenCode TUI (Terminal User Interface) -käyttöliittymän — kokoruudun interaktiivisen liittymän, joka on rakennettu Bubble Tea -kirjastolla. Näet chat-syötteen alareunassa ja keskusteluruudun pääalueella.

Valitse malli

Ensimmäisellä käynnistyskerralla OpenCode pyytää sinua valitsemaan mallin. Sinulla on kolme polkua:

Ilmainen (Zen-mallit): Kirjoita /models ja valitse yksi ilmaisista Zen-malleista. Tässä opetusohjelmassa Grok Code Fast 1 tai GLM 4.7 toimivat hyvin. Nämä ovat ilmaisia eivätkä vaadi API-avainta.

Paikallinen (Ollama): Jos sinulla on Ollama asennettuna, OpenCode tunnistaa sen automaattisesti. Suositeltu malli Ollamalle on glm-4.7:cloud.

Maksullinen (oma avain): Kirjoita /connect liittääksesi Anthropic, OpenAI tai Google API-avaimesi. Avaimet tallennetaan paikallisesti polkuun ~/.local/share/opencode/auth.json.

Tässä opetusohjelmassa mikä tahansa malli toimii. Kehittyneemmät mallit (Claude Sonnet 4.6, GPT-5.4) tuottavat parempia tuloksia monimutkaisissa tehtävissä, mutta ilmaiset Zen-mallit suoriutuvat kaikesta, mitä tässä rakennamme.

Vaihe 2: Projektin rungon luominen Build-tilassa (4 minuuttia)

OpenCode käynnistyy oletusarvoisesti Build-tilassa. Build-tila antaa AI-agentille täydet oikeudet luoda tiedostoja, muokata koodia ja ajaa komentoja. Tätä haluamme rungon luomiseen.

Ensimmäinen kehotteesi

Kirjoita tämä OpenCode-chattiin:

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 tekee seuraavaa:

1. Luo tsconfig.json
2. Asentaa riippuvuudet komennolla npm install
3. Luo src/index.ts Express-palvelimen asetuksilla
4. Päivittää package.json käynnistysskripteillä

Seuraa TUI-käyttöliittymää — näet agentin suorittavan terminaalikomentoja, luovan tiedostoja ja selittävän, mitä se tekee kussakin vaiheessa. Tämä ei ole koodin generointia tyhjiössä; OpenCode-työkalulla on täysi pääsy tiedostojärjestelmääsi ja terminaaliisi.

Varmista, että se toimii

Kun OpenCode on valmis, sano sille:

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

OpenCode ajaa komennon npx nodemon src/index.ts ja vahvistaa, että palvelin kuuntelee. Sinun pitäisi nähdä tuloste kuten Server running on http://localhost:3000.

Mitä juuri tapahtui (Ominaisuus: Build-tila)

Build-tila on OpenCode-työkalun oletusagentti. Sillä on pääsy kaikkiin työkaluihin: tiedostojen luku/kirjoitus, terminaalin suoritus ja koodin muokkaus. OpenCode-dokumentaation mukaan voit ajatella sitä AI-pariohjelmoijana, jolla on täysi pääsy kehitysympäristöösi.

Vaihe 3: Tietomallin ja tietokannan luominen (4 minuuttia)

Suunnittele skeema

Kirjoita tämä kehote:

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 generoi täydellisen tietokantamoduulin. Kiinnitä huomiota siihen, miten se käsittelee FTS5 (Full-Text Search 5) -asetukset — tämä on SQLite-ominaisuus, joka antaa virtaa hakutoiminnallisuudellemme myöhemmin.

Alusta tietokanta palvelimen käynnistyessä

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

Luo opencode.json-konfiguraatio

Tämä on hyvä hetki esitellä projektin konfigurointi. Luo tiedosto sanomalla OpenCode-työkalulle:

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

Tämä luo projektin konfiguraatiotiedoston, jonka OpenCode lukee käynnistyksen yhteydessä. Se antaa AI:lle pysyvän kontekstin projektistasi — koodausstandardit, arkkitehtuuripäätökset ja rajoitukset — jotta sinun ei tarvitse toistaa niitä jokaisessa kehotteessa.

Vaihe 4: REST API -päätepisteiden rakentaminen (5 minuuttia)

Generoi reitit

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 }

Rekisteröi reitit

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

Testaa curl-komennolla

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 suorittaa nämä komennot terminaalissasi ja näyttää vastaukset. Tässä työkalu loistaa — sinun ei tarvitse koskaan poistua terminaalista, ja AI varmistaa oman työnsä.

Vaihe 5: Haun lisääminen FTS5:llä (4 minuuttia)

Esittelyssä Plan-tila

Ennen haun rakentamista käytetään Plan-tilaa toteutuksen pohtimiseen. Vaihda tilaa:

/plan

Nyt olet Plan-tilassa. AI voi lukea koodiasi ja analysoida sitä, mutta ei voi muokata mitään tiedostoja. Tämä on hyödyllistä suunnitteluun ennen muutosten tekemistä.

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 tutkii koodisi, kirjoittaa suunnitelman polkuun .opencode/plans/ ja selittää lähestymistapansa koskematta tiedostoihin. Lue suunnitelma, muokkaa tarvittaessa ja vaihda sitten takaisin:

/build

Toteuta haku

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.

Testaa haku

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

Mitä juuri tapahtui (Ominaisuus: Plan-tila)

Plan/Build-työnkulku on tapa, jolla kokeneet kehittäjät käyttävät OpenCode-työkalua monimutkaisissa tehtävissä. Suunnittele ensin, tarkista lähestymistapa ja rakenna sitten. Suunnitelmatiedostot tallennetaan polkuun .opencode/plans/ ja niihin voidaan viitata myöhemmin Build-agentin toimesta. Tämä estää AI:ta tekemästä suuria rakenteellisia päätöksiä lennosta.

Vaihe 6: Tunnistejärjestelmän toteuttaminen (4 minuuttia)

Luo tunnisteiden päätepisteet

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.

Testaa tunnisteiden työnkulku

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.

Vaihe 7: Yksinkertaisen frontendin rakentaminen (5 minuuttia)

Generoi 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 generoi täydellisen frontendin — HTML-rakenteen, CSS-tyylit ja JavaScriptin API-vuorovaikutuksia varten — yhdellä kertaa. Terminaalissa AI-agentin kanssa rakentamisen etu on, että se voi välittömästi testata, yhdistyykö frontend API-rajapintaan.

Testaa koko pino

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.

Vaihe 8: Testien lisääminen mukautetulla agentilla (5 minuuttia)

Luo mukautettu testiagentti

Tässä OpenCode-työkalun mukautetut agentit -ominaisuus tulee käyttöön. Sen sijaan, että käyttäisimme yleistä Build-agenttia testaamiseen, luomme erikoistuneen agentun.

Lisää tämä opencode.json-tiedostoosi:

{
  "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"]
    }
  }
}

Vaihda nyt testiagenttiin:

/agent test

Generoi testit

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.

Aja testit

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

Mitä juuri tapahtui (Ominaisuus: Mukautetut agentit)

Mukautetut agentit antavat sinun luoda keskittyneitä persoonia tietyillä ohjeilla ja työkaluilla. Luomamme testiagentti voi vain lukea tiedostoja, kirjoittaa testitiedostoja ja ajaa terminaalikomentoja — se ei voi muokata lähdekoodia. Tämä rajoitus estää yleisen ongelman, jossa AI "korjaa" lähdekoodisi testien epäonnistuessa sen sijaan, että se korjaisi testit.

Voit luoda agentteja mihin tahansa erikoistuneeseen työnkulkuun: koodin katselmointiin, dokumentaatioon, tietokantamigraatioihin, DevOps-skripteihin. OpenCode-agenttien dokumentaatiossa on lisää esimerkkejä.

Bonus: MCP-palvelimen yhdistäminen lisätoiminnallisuuksia varten

Jos haluat laajentaa kirjanmerkkien hallintaasi, voit yhdistää ulkoisia työkaluja MCP (Model Context Protocol) -palvelinten kautta.

Esimerkki: Link Preview MCP -palvelimen lisääminen

Kuvittele, että haluat OpenCode-työkalun hakevan automaattisesti metatiedot (otsikko, kuvaus, suosikkikuvake) URL-osoitteista kirjanmerkkejä luodessa. Voit yhdistää MCP-palvelimen, joka suorittaa HTTP-hakuja:

Lisää tämä opencode.json-tiedostoosi:

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

Nyt OpenCode-työkalulla on uusi työkalu käytettävissä: se voi hakea URL-metatietoja osana työnkulkuaan. Kun pyydät sitä "lisäämään kirjanmerkin osoitteelle https://example.com ja täyttämään otsikon ja kuvauksen automaattisesti", se käyttää MCP-palvelinta kyseisen tiedon hakemiseen.

Etäkäyttöiset MCP-palvelimet

Käytä pilvipalveluille etäkäyttöisiä MCP-palvelimia, joissa on automaattinen OAuth-käsittely:

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

OpenCode tunnistaa 401-vastaukset ja aloittaa OAuth-prosessin automaattisesti, jos palvelin tukee Dynamic Client Registration -ominaisuutta.

Bonus: OpenCode-työkalun käyttö CI/CD-putkessa

OpenCode-työkalulla on CLI-tila, joka toimii ilman TUI-käyttöliittymää — täydellinen automaatioon. Voit käyttää sitä GitHub Actionsissa tai missä tahansa CI-putkessa:

# 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

Kirjanmerkkien hallintasovellustamme varten voisit lisätä CI-vaiheen, joka ajaa OpenCode-työkalun katselmoimaan PR-pyyntöjä automaattisesti. OpenCode GitHub integration tarjoaa virtaviivaisemman version tästä työnkulusta.

Täydellinen projektirakenne

Tämän opetusohjelman jälkeen projektisi pitäisi näyttää tältä:

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

Mitä opit

Rakentamalla todellisen projektin harjoittelit näitä OpenCode-ominaisuuksia:

Keskeinen ero OpenCode-työkalun ja muiden AI-koodaustyökalujen välillä on se, että se on kokonaan avointa lähdekoodia, se toimii terminaalissasi eikä tallenna koodiasi tai kontekstitietojasi. Sinä hallitset malleja, tiedot pysyvät paikallisina ja yli 800 osallistujan yhteisö kehittää sitä nopeasti.

Tiimeille, jotka käyttävät useita AI-työkaluja, OpenCode toimii hyvin terminaalipohjaisena täydennyksenä IDE-assistenteille. ZBuild-yrityksessä käytämme sitä usein editoripohjaisten työkalujen rinnalla kehitystyön eri osissa.

Seuraavat vaiheet

Nyt kun sinulla on toimiva kirjanmerkkien hallintasovellus ja vahva ymmärrys OpenCode-työkalusta, tässä on suuntia, joihin voit jatkaa:

1. Lisää autentikointi — Käytä Build-agenttia lisätäksesi JWT-pohjainen autentikointi käyttäjätileillä
2. Julkaise tuotantoon — Pyydä OpenCode-työkalua generoimaan Dockerfile ja julkaise Fly.io- tai Railway-palveluun
3. Rakenna selainlaajennus — Luo Chrome-laajennus, joka lisää kirjanmerkkejä API:n kautta
4. Tutki lisää Zen-malleja — Kokeile Big Pickle, MiniMax M2.1, tai aja paikallista mallia Ollama-ohjelmistolla
5. Luo lisää mukautettuja agentteja — "Refactor"-agentti, "Docs"-agentti tai "Security Audit" -agentti

OpenCode documentation ja awesome-opencode repository tarjoavat lisää plugineja, teemoja ja yhteisön konfiguraatioita tutkittavaksi.

Lähteet

• 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