chadtmiller.com/spaces-bookclub
Book club: a Svelte demo app for atproto spaces (@atproto/lex-space)
Book club: an atproto spaces app
A Svelte app on @atproto/lex-space. Members of a club share book reviews that only other members can read. Every member keeps their reviews in their own repo, on their own PDS. The club's authority (its creator) hosts the member list and decides who may read.
Everything runs locally: a PLC directory, two PDSes, a lexicon authority and a handle resolver, all in one Node process.
flowchart LR
app[Svelte app<br/>127.0.0.1:5173]
plc[PLC directory<br/>:2582]
hr[Handle resolver<br/>:2580]
pds1[PDS 1 :2583<br/>alice, carol<br/>lexicon authority]
pds2[PDS 2 :random<br/>bob]
app -- OAuth, own repo --> pds1
app -- OAuth, own repo --> pds2
app -- space credential:<br/>other members' repos --> pds1
app -- space credential --> pds2
app -- DID docs --> plc
app -- handles --> hr
pds1 & pds2 -- resolve NSIDs --> pds1
Prerequisites
../atprotochecked out onpermissioned-data-alphaand built (pnpm install && pnpm run buildat its root). The@atproto/*dependencies arelink:ed from it: they are not published yet.- Node ≥ 22.
Run
pnpm install
pnpm network # terminal 1: PLC, PDSes, accounts, lexicons
pnpm dev # terminal 2: http://127.0.0.1:5173
Use 127.0.0.1, not localhost: OAuth loopback clients redirect there.
Test accounts, all with password password: alice.test and carol.test (PDS 1), and bob.test2 (PDS 2). The network is in memory: restarting it wipes everything, so sign out first or the app will restore a dead session.
Try it
- Sign in as alice and create a club. Post a review, then add
bob.test2as a member and copy the club's invite link from Invite. - Sign out and open the link. Sign in as bob: the app joins the club once he's back. Bob reads alice's review from PDS 1 with a space credential, then posts his own review into his repo on PDS 2.
- Sign in as carol and try to join. She gets
SpaceNotFound. - As alice, remove bob. His next load fails with
SpaceNotFound.
How it fits together
| File | What |
|---|---|
lexicons/com/example/bookclub/club.json | The space type: TID keys, holding info and review records |
lexicons/com/example/bookclub/info.json | A club's name and description: one record (self) in the host's repo |
lexicons/com/example/bookclub/review.json | The review record |
src/lexicons/ | Generated by lex build (pnpm lex, run before dev, build and check) |
src/lib/atproto.ts | OAuth client and scopes, plus BookClubApp, which wraps every space call |
src/styles/tokens.css | Design tokens: a primitive palette, and the semantic tokens components use (remapped for dark mode) |
src/components/ | UI, in atomic design layers: atoms → molecules → organisms (including every action dialog) → templates → pages |
dev/network.ts | Local network, accounts, lexicon publishing, and the handle resolver |
Scopes. These are requested in src/lib/atproto.ts:
space:com.example.bookclub.club?authority=*: read every club the user is in, and write the collections the space type declares.space:com.example.bookclub.club?manage=create&manage=update&manage=delete: create clubs with the user as authority, and manage their members and lifecycle.
At consent, the PDS resolves the space type's lexicon to name it and to expand the first scope into its collections. That is why dev/network.ts publishes lexicons/ from the lexicon authority's repo, which both PDSes resolve every NSID against. On the real network, the NSID's domain owner publishes the lexicons instead.
Reading. SpaceClient.allRecords() reads every repo in the club's writer set. It fetches each repo from its own PDS and verifies it against the MAC from that PDS before returning any records. Reads of the user's own repo go through their OAuth session. Reads of other members' repos use a space credential, which the club's authority PDS issues in exchange for a delegation token from the user's PDS. lex-space handles all of this.
Discovery. listSpaces on the user's PDS only lists clubs the user created or has written to: membership is recorded on the authority's PDS. A new member therefore joins with an invite link, /join/<authority DID>/<space key> (see src/lib/invite.ts), which maps back to the space URI. The link survives the OAuth redirect in localStorage, and the app remembers the club until the member's first review.
Names. A space has no name of its own: its key is part of its URI, so it can't change. The club's name and description are an info record the host writes into their repo in the space, which every member already reads. Renaming is a put of that record. The sidebar needs each club's name before it's opened, which costs a credential per club; names are cached in localStorage (cleared on sign-out, since they're private to members).