leaflet
a tool for shared writing and social publishing
Star
Fork
Watch
leaflet CLAUDE.md
8.3 kB · 94 lines
Markdown
at feature/iframe-reader

CLAUDE.md #

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview #

Leaflet is a full-stack TypeScript web app for shared writing and social publishing, built on Bluesky (AT Protocol). Users create collaborative documents ("Leaflets") and publish them as blog posts/newsletters ("Publications") that others can follow.

Tech Stack #

  • Frontend: React 19 + Next.js 16 (App Router, Turbopack)
  • Database: PostgreSQL via Supabase + Drizzle ORM
  • Real-time sync: Replicache for optimistic updates and offline support
  • Editor: ProseMirror with Yjs CRDT
  • Social: AT Protocol (@atproto packages) for Bluesky integration
  • Jobs: Inngest for async serverless functions

Commands #

npm run dev                     # Start Next.js dev server (port 3000)
npm run start-appview-dev       # Start AT Protocol appview service
npm run start-feed-service-dev  # Start feed subscription service
npx tsc                         # TypeScript type checking (used in CI)
npm run generate-db-types       # Regenerate Supabase types after schema changes
npm run lexgen                  # Regenerate AT Protocol types from lexicons

Architecture #

Data Flow #

  1. Client mutations go through Replicache (src/replicache/mutations.ts) for optimistic local updates
  2. Server actions in actions/ persist changes to Supabase
  3. CVR sync reconciles client and server state via Replicache

Document Model #

Documents are composed of blocks (text, image, embed, code, poll, etc.). Block components live in components/Blocks/. Blocks are rendered in linear lists by components/Blocks/index.tsx and in an xy canvas by components/Canvas.tsx.

AT Protocol / Bluesky #

  • Lexicons (lexicons/) define schemas for reading and writing records to the AT Protocol network and users' PDSs
  • Appview (appview/) consumes the firehose to index published content
  • Feeds (feeds/) provides subscription feeds for publications

Lexicon Workflow #

The source of truth for lexicon schemas is the TypeScript files in lexicons/src/ (e.g. facet.ts, publication.ts, blocks.ts). The JSON files in lexicons/pub/ are generated output — do not edit them directly, as npm run lexgen will overwrite them.

To add or modify a lexicon:

  1. Edit the relevant source file in lexicons/src/
  2. Run npm run lexgen to regenerate both the JSON schemas and the TypeScript API types in lexicons/api/

Key Directories #

  • app/ - Next.js App Router pages and API routes
  • actions/ - Server actions (mutations, auth, subscriptions)
  • components/ - React components
  • src/ - Shared utilities, hooks, Replicache setup
  • appview/ - AT Protocol firehose consumer for indexing
  • feeds/ - Feed service for publication subscriptions
  • lexicons/ - AT Protocol schema definitions
  • supabase/migrations/ - Database schema

Patterns #

  • Server actions: Export async functions with 'use server' directive, return Result<T> from src/result.ts
  • Replicache mutations: Named handlers in src/replicache/mutations.ts, keep server mutations idempotent. When adding one:
    • Move/replace a fact with a single assertFact that reuses the existing fact id — never retractFact(id) then assertFact({id}). The retract+assert pair records two undo entries with an intermediate state where the fact is gone, so undo/redo flickers the block out of existence; one assertFact (cardinality-many + explicit id) captures the old value as a single clean undo entry. Reserve retractFact for genuine deletions (usually paired with deleteEntity).
    • Group a multi-mutation user action into one undo step with undoManager.withUndoGroup(async () => { ... }), awaiting every mutation inside — undo entries are recorded asynchronously in mutator bodies, so a fire-and-forget or un-awaited mutation lands as its own separate Cmd-Z step.
    • Pass ignoreUndo: true for derived/follow-up writes that shouldn't be independently undoable (e.g. async link/image enrichment after a paste, the yjs block/text doc persistence).
  • React contexts: DocumentProvider, LeafletContentProvider for page-level data
  • Inngest functions: Async jobs in app/api/inngest/functions/
  • Icons: Icon components live in components/Icons/. Each icon is a named export in its own file (e.g. RefreshSmall.tsx), imports Props from ./Props, spreads {...props} on the <svg> element, and uses fill="currentColor" instead of hardcoded colors like fill="black".
  • Popovers and menus: Use the existing Popover (components/Popover), Menu, and MenuItem (components/Menu) components — do not create new popover/menu primitives. Avoid using buttons inside Popover or Modal triggers unless using a specific button component. If button is being used as trigger, always add an "asChild" prop to the Menu or Popover
  • Supabase query plans: Never combine .order() on a table's own column with .limit() and a row-restricting embed (!inner or an embed-path filter) in one query — PostgREST compiles the embed into a LATERAL join that forces Postgres to walk the order column's index across the whole table probing the embed per row (this has caused repeated production full-table scans). Filter on the from-table's own indexed columns, start the query from the join table, or use a fenced SQL function for newest-N-across-a-join (examples: get_publication_feed_docs, get_tag_page_document_uris). CI enforces this via npm run check-query-plans; the fix recipes and plan-checked: suppression rules are documented in scripts/check-supabase-query-plans.mjs.
  • Default theme: The default theme colors (accent/background/primary/highlights) are hardcoded in several disconnected places (themeDefaults.ts, themeUtils.ts, app/globals.css :root, emails/shared.tsx, PubPresetPicker.tsx) with no shared import, so they drift easily. When changing any default color, use the update-default-theme skill (.claude/skills/update-default-theme/) which lists every place to update and keeps them in sync.
  • Custom domain settings: Custom domains are listed, verified, and assigned in three disconnected surfaces (profile settings/domains, publication dashboard PubDomainSettings.tsx, editor share menu ShareOptions/DomainOptions.tsx) that each hand-roll their own row UI over the same data. When changing domain row UI or behavior in any one of them, use the domain-settings skill (.claude/skills/domain-settings/), which lists the shared pieces and requires asking whether the change applies to the other two.
  • Publication settings: A setting in the General tab passes through several hand-maintained explicit field lists (both lexicons, normalizePublication, both builders in buildPublicationRecord.ts, four spots in SettingsContent.tsx, createPublication.ts) — none of them spread, so a field missing from one is dropped with no type error. When adding or changing a setting there, use the publication-settings skill (.claude/skills/publication-settings/), which walks the round trip and how to verify it saves and applies.

Comments #

Don't describe in a comment what the code already says, and don't capture counterfactuals — comments shouldn't be hysteretic. Don't narrate what changed, what it used to do, what you considered and rejected, or why something isn't done another way. Comment only on the non-obvious why that the code itself can't convey.

This is NOT the Next.js you know #

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.