Crate is an ATProto-native file application. A permissioned PDS stores file records, version history, and blobs. Astro and Preact provide the web app; at-astro owns OAuth, and Astro actions access the PDS directly. The web app builds as a Cloudflare Worker with static assets.

Development #

Install Just 1.43 or newer, Bun 1.3.13, and Node.js 22.12 or newer (for Astro):

just install
just dev

Astro serves the app at http://127.0.0.1:5173. Sign in with your own ATProto handle and approve access on your PDS. The PDS must implement the permissioned Spaces API described in the protocol documentation.

Run just to list commands, including just infra-preview and just infra-up for the production Pulumi DNS stack (requires the Pulumi CLI and login). just build produces the Worker and assets in dist/packages/web; it does not deploy them.

Protocol and web types #

The JSON files in lexicons/network/crate are the source of truth. The official @atproto/lex generator produces TypeScript models and validators in packages/protocol; a pinned swift-atproto generator produces the CrateModels Swift package in packages/swift-models. Generated files are checked in. Web action output types remain inferred from packages/web/src/lib/api.ts.

Bun is enough to work on the web app. Regenerating both model packages and running the full check suite also requires Swift 6.4 with XCTest (Xcode on macOS). The Swift package supports macOS 14 and iOS 17 or newer.

just generate          # JSON -> TypeScript + Swift
just validate-lexicons # Validate JSON without Swift
just check-contracts   # Regenerate into a temp directory and detect drift
just test-swift

Publish the authored schemas with just publish-lexicons after signing into Goat as the schema publisher. This requires Goat and jq, validates the Lexicons, and updates their public records. Use just publish-lexicons create for first publication. It uses Goat's generic record command with --no-validate because goat lex publish does not yet support the alpha Space schema.

Verification and Jujutsu #

just check
just build
jj status
jj diff
jj describe -m 'Describe one completed concept'
jj new

With the app running, just test-browser checks anonymous behavior and synthetic-account layout and interactions without accessing a real PDS. Install its Chromium browser with bunx playwright install chromium if needed. The authenticated lifecycle is opt-in and requires you to sign in manually:

CRATE_LIVE_PDS=1 just test-browser --grep 'user-authorized private PDS' --headed --workers=1