Community Distributed Library
A community distributed library is a decentralized sharing network: neighbours lend each other
what they already own. Items stay in the homes of their owners, with no building and no central
stock, until someone asks for one. The library is the shared part: a
catalogue, requests, handoff times picked from both people's week, a record of who holds what, and
reminders.
https://github.com/user-attachments/assets/e9172665-5d60-4f19-84c0-8964d6a620a8
A minute on what a library is and how to open one for your street; more on
Run your own library.
What you can do next:
- Run a library for your street. Follow docs/self-hosting.md, or open
this folder in Claude Code and type
/open-a-library. You need a domain on Cloudflare and a
Cloudflare API token; one command does the rest.
- Work on the code. Start at Run locally, and read
CONTRIBUTING.md for how changes are made here.
- Build on a library. Everything the web app does is also open as an
API, MCP server and webhooks.
Released into the public domain under the Unlicense.
One codebase, many libraries
One codebase runs any number of libraries. Each library is its own deployment on Cloudflare, with its
own members, data and address; the person who runs one or more of them is its operator. A library
lends either books or things (packages/contracts/src/library-types.ts). Libraries are
invite-only and closed to search engines. Everything runs on Cloudflare, email included.
Layout
npm workspaces. Each service is its own Cloudflare Worker with its own storage, and services talk
over service bindings.
apps/web/ the library web app: Next.js App Router on vinext, a PWA, one Worker per library
apps/landing/ the front page at the bare domain (static)
apps/video/ the explainer video, landscape and portrait (Remotion); not deployed
services/core/ system of record and the public /v1 API (Hono, D1)
services/mcp/ OAuth 2.1 server and MCP tools for AI assistants, calling core's /v1
services/notify/ email through Cloudflare Email Sending, Web Push (RFC 8291/8292); no storage
services/convo/ loan message threads, own D1, deleted 90 days after a loan closes
services/metadata/ ISBN lookup (Open Library, then Google Books) and its cache; shared
services/reports/ where browsers report CSP violations and network errors; shared
packages/contracts/ Zod schemas, the OpenAPI document, library types
packages/tools/ what an assistant can do: one list of tools, for MCP and the pages (WebMCP)
packages/design/ design tokens, logo, principles, frontend conventions
scripts/ list of libraries, deploy, checks, local dev, pulling a database down
Naming: shared things say cdl (@cdl/*, cdl-metadata, cdl-reports, cdl-landing); a
library's own Workers and stores are <slug>-<service>, for example our-street-core.
Run locally
Node version is in .nvmrc.
npm install
npm run dev # applies migrations, then API :8787, MCP :8788, web :3000
npm run db:seed # in a second terminal, once: one library and two members
Open http://localhost:3000/login and sign in as [email protected] (admin, English) or
[email protected] (member, Hebrew). Locally the API runs with DEV_AUTH, so the form goes straight to
the sign-in link instead of emailing it. Scripts can also send X-Member-Id: <member id>.
| Command | Does |
|---|
npm run db:seed:things | Switches the local library to things and lists a few |
npm run library:books / npm run library:things | Switches the local library type |
npm run db:pull -- core --library <slug> | Replaces a local database with a production copy; tokens and sessions are removed (stop the dev server first) |
services/core/scripts/role.sh <email> moderator | Gives a role locally (--remote <slug> for a live library) |
npm run dev:api, npm run dev:mcp, npm run dev:web | Runs one side alone |
npm run dev in apps/landing | The front page on :3001 |
The local databases are cdl-core, cdl-convo and cdl-metadata, whichever library you pull.
Check
npm run typecheck
npm test # vitest everywhere; core runs in workerd against a migrated D1
npm run test:e2e -w @cdl/web # Playwright: phone, desktop and things projects, axe in both languages
npm run format # Prettier; CI fails on any diff
npm run check:libraries
npm test first runs scripts/check-hosts.mjs, which makes sure no Worker serves on workers.dev or
a preview URL. The browser tests switch the local library to books, run the things project last, and
leave it lending books; npm run library:things puts it back if you were working on things.
CI (.github/workflows/ci.yml) runs on every push and pull request, in two jobs: one runs types,
Prettier, typecheck, the builds, the library check and every test; the other runs the browser tests against a
local stack. CI does not deploy.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
