Web portal for the Pubky ecosystem — a publisher and social feed for the decentralized web.
Note: This component is NOT part of Pubky Core. It is part of the Pubky social app stack (along with Pubky Nexus).
Overview
pubky.app is a social media-like web application built on top of Pubky Core. It serves as the flagship example of how to build applications using the Pubky SDK for authentication and data storage, combined with Nexus for data aggregation and indexing, turning distributed data into fast-loading feeds and a navigable social graph.
- GitHub: https://github.com/pubky/pubky-app
- Platform: Web (Next.js progressive web app)
- Status: Active development
The application follows a local-first architecture where writes commit to local IndexedDB immediately for instant UI feedback, then sync to the homeserver in the background.
Tech Stack
- Next.js 16 / React 19 / TypeScript — Core framework
- Tailwind CSS 4 / Shadcn UI / Radix UI — Styling and components
- Zustand — Global state management
- Dexie — IndexedDB wrapper for local-first persistence
- TanStack Query — Data fetching with caching
- @synonymdev/pubky — WASM SDK for homeserver communication
- pubky-app-specs — Shared data specifications
Key Features
- Social feeds (home, hot/trending, search) via Nexus
- Profiles, posts, bookmarks, notifications
- QR Code Authentication via Pubky Ring
- Offline support — PWA with service worker caching and local-first writes
Codebase Structure
The codebase is organized in layers with strict separation of concerns:
| Layer | Responsibility |
|---|---|
| Controllers | Entry point for UI actions |
| Coordinators | System-initiated actions (polling, auth changes, TTL) |
| Application | Business logic orchestration |
| Services | IO boundaries (local, homeserver, nexus) |
| Models | Dexie-based IndexedDB persistence |
| Stores | UI state via Zustand |
Data Flow
- Writes go to homeserver via SDK
- Nexus polls homeserver for changes via the
/events/endpoint - Nexus indexes and aggregates data
- Reads come from Nexus for performance
- Local Dexie cache provides offline access
All user data is stored under /pub/pubky.app/ on the homeserver following the pubky-app-specs schema.
See the repository for routes, environment configuration, and development setup.