Catalogue — a bookmark manager

A small full-stack Next.js app for saving links, tagging them, and finding them again. Built as a learning project to cover the core App Router fundamentals: routing, Server Components, Server Actions, and data mutations — and set up to deploy live on Vercel with a free Turso (SQLite) database.

What it does

• Save a bookmark (title, URL, comma-separated tags)
• Browse all bookmarks, newest first
• Filter by tag via /tags/[tag]
• Delete a bookmark

What it teaches

Concept	Where it shows up
File-based routing	src/app/page.tsx, src/app/tags/[tag]/page.tsx
Dynamic routes	/tags/[tag] reads the tag from the URL
Server Components	Every page fetches data directly, no useEffect
Server Actions	src/app/actions/bookmarks.ts — addBookmark, removeBookmark
Mutations without API routes	Forms call Server Actions directly via the action prop
Cache invalidation	revalidatePath() after every write
A real hosted database	src/lib/db.ts — Turso (libSQL/SQLite)

Data storage

Bookmarks live in SQLite via Turso, accessed through src/lib/db.ts. Locally, if no Turso credentials are set, it automatically falls back to a SQLite file on disk (local.db) — so npm install && npm run dev works immediately with zero setup. In production, it connects to your hosted Turso database instead, which is what makes the data persist on Vercel (whose filesystem is read-only/ephemeral at runtime).

Running it locally

npm install
npm run dev

Open http://localhost:3000. No environment variables needed — it uses local.db automatically.

Deploying it for real (GitHub + Vercel + Turso, all free tier)

1. Push to GitHub

git init
git add .
git commit -m "Initial commit"

Create a new repo on github.com/new, then:

git remote add origin https://github.com/<your-username>/<repo-name>.git
git branch -M main
git push -u origin main

2. Create a free Turso database

Install the Turso CLI and sign up (free, no card required):

curl -sSfL https://get.tur.so/install.sh | bash
turso auth signup

Create the database and get its connection details:

turso db create bookmark-manager
turso db show bookmark-manager --url
turso db tokens create bookmark-manager

Save the URL (libsql://...) and the token — you'll need both in the next step.

3. Deploy to Vercel

• Go to vercel.com/new and import your GitHub repo
• Vercel auto-detects Next.js — no build config needed
• Before deploying, add two environment variables (Settings → Environment Variables):
  • TURSO_DATABASE_URL → the libsql://... URL from step 2
  • TURSO_AUTH_TOKEN → the token from step 2
• Click Deploy

That's it — every push to main redeploys automatically, and your bookmarks persist in Turso instead of disappearing between deploys.

Project structure

src/
  app/
    page.tsx              # home page — all bookmarks
    tags/[tag]/page.tsx    # bookmarks filtered by tag
    actions/bookmarks.ts   # Server Actions (add, delete)
    layout.tsx
    globals.css
  components/
    SiteHeader.tsx         # title + tag nav
    AddBookmarkForm.tsx
    BookmarkCard.tsx
    EmptyState.tsx
  lib/
    db.ts                  # Turso/SQLite data layer
.env.example               # documents TURSO_DATABASE_URL / TURSO_AUTH_TOKEN

Next steps to extend it

• Add a search box that filters by title client-side
• Add auth (NextAuth) so each user has their own bookmarks
• Auto-fetch the page title when a URL is pasted