⚡️⚡️⚡️ Self-hosted collaborative bookmark manager to collect, read, annotate, and fully preserve what matters, all in one place.
AGENTS.md
Linkwarden is a self-hosted, collaborative bookmark manager that collects, reads, annotates and preserves webpages. This file is the orientation map for agents working in this repository: what the pieces are, how they talk to each other, which commands to run, and where the public-facing sites live.
Repository layout
Yarn 4 workspaces monorepo (apps/* and packages/*). No Turborepo; orchestration is plain root-level scripts.
Apps
| Path | Workspace | What it is |
|---|---|---|
apps/web |
@linkwarden/web |
Next.js app (Pages Router). Serves the UI and the whole REST API. |
apps/worker |
@linkwarden/worker |
Long-running Node/tsx process. Preservation, AI tagging, search indexing, RSS polling, data migrations. |
apps/mobile |
@linkwarden/mobile |
Expo / React Native app (expo-router, NativeWind) for iOS and Android. |
apps/extension |
@linkwarden/extension |
Vite + React browser extension (Chrome, Firefox, Safari). |
Packages
Shared code, all plain TypeScript source with main: index.ts (no build step; consumers transpile them).
| Path | Workspace | What it is |
|---|---|---|
packages/prisma |
@linkwarden/prisma |
schema.prisma, migrations, generated client, seed. The single source of truth for the data model. |
packages/types |
@linkwarden/types |
Shared TypeScript types (global.ts is the big one). |
packages/lib |
@linkwarden/lib |
Server and client helpers: Zod schemas (schemaValidation.ts), constants, SSRF guards (ssrf.ts, safeFetch.ts), Meilisearch client, mailer, RSS handling, format helpers. |
packages/filesystem |
@linkwarden/filesystem |
Storage abstraction. Writes to local disk or S3-compatible object storage depending on whether S3 env vars are set. |
packages/router |
@linkwarden/router |
TanStack Query hooks (useLinks, useCollections, useTags, ...). Shared by web and mobile, which is why it lives outside apps/web. |
Dependency direction: prisma → types → lib/filesystem → router → apps. Nothing in packages/ imports from apps/.
Architecture
Request path (web)
apps/web/pages/api/v1/**(plus a smallv2/for the new dashboard) are thin Next API route handlers. They authenticate viaverifyUser/getTokenFromRequest(NextAuth session or API token), parse and coerce query params, and check demo mode.- Business logic lives in
apps/web/lib/api/controllers/<resource>/. Routes stay dumb; controllers return{ status, response }. - Permissions for shared collections go through
apps/web/lib/api/getPermission.tsandgetAccessibleCollectionIds.ts. Any new link or collection query must respect collection membership, not just ownership. - Client components never call
axiosdirectly; they use the hooks inpackages/router, so web and mobile share cache keys, optimistic updates and invalidation rules.
Preservation path (worker)
The web app only records intent. The worker does the heavy lifting.
apps/worker/index.tsis a supervisor that respawnsworker.tson exit.worker.tsruns the migration worker once, then starts the loops:linkProcessing,autoTagPreservedLinks,linkIndexing,rssPolling(interval fromARCHIVE_SCRIPT_INTERVAL, default 10s).linkProcessingclaims a batch of unpreserved links (lib/getLinkBatch.ts,getLinkBatchFairly.tsspreads work across users), drives a headless Chromium throughlib/preservationScheme/*to produce a screenshot, PDF, readability text, preview image and single-file HTML (Rustmonolithbinary), and optionally pushes to the Wayback Machine.- Artifacts are written through
@linkwarden/filesystem, so they land on disk or in S3 without the callers caring. - AI tagging uses the Vercel AI SDK with pluggable providers (Ollama, OpenAI and compatible, Azure, Anthropic, OpenRouter, Perplexity), selected by env vars.
linkIndexingpushes link text into Meilisearch; full text search in the web app reads from there.
Infrastructure dependencies
PostgreSQL (Prisma), Meilisearch (search), Chromium via Playwright plus the monolith binary (preservation), optional S3-compatible storage, optional SMTP, optional Stripe and Apple/Google IAP for the Cloud offering.
Commands
Run everything from the repo root. Root scripts wrap dotenv -- so the root .env is loaded for you; running a workspace script directly usually will not see those vars.
Setup
yarn install # also runs prisma generate via postinstall + patch-package
yarn prisma:deploy # apply migrations (use prisma:dev to create one)
Develop
yarn concurrently:dev # web + worker together (the usual one)
yarn web:dev # web only, localhost:3000
yarn worker:dev # worker only, tsx watch
yarn prisma:studio # inspect the database
Build and run production locally
yarn web:build # next build
yarn concurrently:start # web + worker in production mode
yarn docker:build # docker compose up --build (postgres + meilisearch + app)
Note: yarn web:build writes into apps/web/.next, which will disturb a yarn web:start already serving from it.
Prisma
yarn prisma:generate, yarn prisma:dev, yarn prisma:deploy, yarn prisma:studio. Never hand-edit files in packages/prisma/migrations/.
Test
yarn test # vitest (watch), unit tests colocated as *.test.ts
yarn coverage # vitest run --coverage
yarn workspace @linkwarden/web e2e # Playwright E2E in apps/web/e2e
Mobile and extension (from their workspaces)
yarn workspace @linkwarden/mobile ios | android | start
yarn workspace @linkwarden/extension dev:chrome | dev:firefox | build
Other: yarn format (Prettier across workspaces), yarn workspace @linkwarden/worker typecheck.
Configuration
A single root .env feeds every workspace. .env.sample is the documented list and should be updated whenever a new variable is introduced. Groups worth knowing: core (DATABASE_URL, NEXTAUTH_URL, NEXTAUTH_SECRET), storage (STORAGE_FOLDER or the SPACES_* S3 vars), preservation limits and browser behaviour (*_MAX_BUFFER, BROWSER_*, MAX_WORKERS, DISABLE_BROWSER), search (MEILI_HOST, MEILI_MASTER_KEY), AI provider keys, and SSRF controls (ALLOW_PRIVATE_NETWORK_ACCESS, ALLOW_INSECURE_TLS).
Branching and CI
dev is the integration branch; main is release. PRs into main are only accepted from dev (enforced by check-branch.yml). CI in .github/workflows/: Playwright on push and PR, release containers published to ghcr.io/linkwarden/linkwarden on tag, an edge container and extension builds on manual dispatch, mobile build and submit via EAS on manual dispatch, and an i18n automation job for Crowdin PRs.
Translations are managed in Crowdin (crowdin.yml); edit apps/web/public/locales/en/* only, the other locales sync from Crowdin.
Sibling repositories
These are separate GitHub repos, not workspaces here. Two of them are checked out next to this one as additional working directories.
| Site | Repo | Stack | Hosting |
|---|---|---|---|
Docs, docs.linkwarden.app |
linkwarden/docs (../docs) |
Docusaurus 3. Markdown under docs/ (getting-started, usage, self-hosting, billing, developers), plus API reference generated from openapi/linkwarden.yaml by docusaurus-plugin-openapi-docs. Algolia search. |
GitHub Pages on push to main (yarn docusaurus gen-api-docs all then yarn build). |
Landing page and blog, linkwarden.app |
linkwarden/website (../website) |
Next.js 13 Pages Router, static export (output: "export"). Landing, /pricing, /compare/*, legal pages, and the blog at /blog rendered from Markdown in apps/website/content/blog/ (articles/, releases/, authors.yml) via next-mdx-remote. scripts/generate-feeds.mjs builds the RSS feed and sitemap before each build. |
GitHub Pages on push to main, plus a nightly cron rebuild. |
Practical consequence: changing an API route or adding an env var is usually a two-repo job. Update the code here, then update openapi/linkwarden.yaml or the relevant page in ../docs. Release notes go to ../website/apps/website/content/blog/releases/.
The browser extension lives in this monorepo (apps/extension); the older standalone linkwarden/browser-extension repo that the README links to is the predecessor.
Conventions
- TypeScript throughout, Prettier formatted, 2-space indent.
- Validate request bodies with the Zod schemas in
packages/lib/schemaValidation.tsrather than ad-hoc checks. - Any outbound fetch of a user-supplied URL goes through
safeFetch/ the SSRF helpers. This is a security boundary; do not bypass it. - Server-side data access belongs in a controller under
apps/web/lib/api/controllers/, client-side data access in apackages/routerhook. Logic needed by both web and mobile belongs inpackages/liborpackages/router, not inapps/web. - UI is Tailwind plus DaisyUI with some Radix primitives on web, NativeWind on mobile. Prefer existing components in
apps/web/components/over new one-off ones. - Styling and copy: plain, direct tone. When something is blocked by a site (paywalls, bot protection), describe it as that site's restriction.