Purl

Save the links worth keeping. Share the ones worth passing on.

Live preview: https://purl.live

Purl is a calm place to save and share the links you find — a home for your "pearls". You paste URLs: web pages, PDFs, YouTube videos, and audio. Purl resolves each item's metadata (title, favicon, description, thumbnail) and keeps everything in one place, available from the app, a REST API, and an MCP server.

Purl is free, with one limit: each account can save up to 1,000 links (MAX_SAVED_LINKS in src/lib/limits.ts).

The product goal: one place to keep the links you care about, and an easy way to share the ones worth passing on.

Implemented today

• Marketing site — Landing page (hero with a live preview), docs for the REST API and MCP server, privacy and terms.
• Authentication — Google and GitHub sign-in on the landing page via Better Auth (Apple too when its env vars are set). Every account gets a unique username, editable in Settings, where you can also connect or disconnect sign-in methods; avatars come from the OAuth provider's profile photo.
• Save & organize
  • Add items by URL with automatic content-type detection (web, PDF, YouTube, audio).
  • Links grouped by relative time (e.g. Today, This week, Last month).
  • Preview metadata (title, description, favicon, thumbnail where available).
• Hardened outbound fetch — Server-side safeFetch with optional proxy/DNS controls (see AGENTS.md). An egress proxy can be configured via SAFE_OUTBOUND_HTTP_PROXY.
• Realtime list sync — Supabase Realtime so saves and updates propagate across tabs/devices quickly.
• Link actions — Open original, copy URL, edit metadata, delete.
• REST API & MCP — /api/v1 (links and folders) and an MCP server (save_link, list_saved_items, get_link, move_link, list_folders, create_folder, update_folder, delete_folder) with API-key or OAuth auth.
• Operational extras — Optional Upstash-backed API rate limiting, Vitest coverage for critical paths.
• PWA (installable app) — Web App Manifest plus a Serwist service worker (src/app/sw.ts) that builds to public/sw.js (generated on pnpm build, gitignored). Enables Install in Chrome/Edge and similar where the platform supports it, with runtime caching via Serwist's Next.js defaults and a static offline shell at /~offline. Serwist is disabled in pnpm dev to avoid service-worker cache surprises during development — use pnpm build && pnpm start (or your production URL) to exercise installability and the SW.

Save flow

Saving a link is fully synchronous — there is no background processing.

1. Input — POST /api/links with a URL (also /api/v1/links and the MCP save_link tool).
2. Classify & decorate — Server-side detectContentType (SSRF-safe HEAD / sniff) plus scrapeLinkMetadata (Open Graph HTML, PDF Content-Disposition / size, YouTube oEmbed). Saving an existing URL again refreshes its metadata and moves it to the top.
3. Persist — A Link row with title, favicon, thumbnail, domain, and contentType (WEB, PDF, YOUTUBE, or AUDIO).
4. Sync — broadcastLinksChanged notifies other tabs/devices via Supabase Realtime.

Not implemented yet

These are called out explicitly because the repo is going public:

• Settings breadth — Settings cover username, sign-in methods, and account deletion; broader account preferences (notification settings, etc.) are not implemented yet.

Marketing vs. product: The landing page copy mentions ideas such as collections and a weekly digest. Those are not built in the current schema or app — treat them as roadmap, not shipped features.

Tech stack

• Web: Next.js (App Router), React, TypeScript
• UI: Tailwind CSS, shadcn/ui
• Auth: Better Auth
• Database: PostgreSQL + Prisma
• Email (optional in dev): Resend for feedback emails
• Realtime: Supabase client (anon + service role on server)
• PWA: Serwist (@serwist/next), web manifest + precache / offline fallback

CI / GitHub Actions

Automation lives under .github/workflows/. Every PR and manual release is gated by these pipelines.

PR checks — pr-checks.yml

Runs on pull_request to develop and main: Setup & validation → Prisma (generate client + type fixes) → Lint and type check (in parallel) → Tests and production build (in parallel, after lint and type check pass). Concurrency is per-PR so new pushes cancel stale runs.

Release — release.yml

Runs on workflow_dispatch (manual): Merge develop into main, then build validation so production is only promoted after a green build.

Security

Purl is built around untrusted input (arbitrary URLs). A few layers matter in production:

This is the beginning of the README. Read the rest at the original. Read the full README ↗