the statusphere demo reworked into a vite/react app in a monorepo
1# Statusphere React
2
3A status sharing application built with React and the AT Protocol.
4
5This is a React implementation of the [example application](https://atproto.com/guides/applications) covering:
6
7- Signin via OAuth
8- Fetch information about users (profiles)
9- Listen to the network firehose for new data
10- Publish data on the user's account using a custom schema
11
12## Structure
13
14- `packages/appview` - Express.js backend that serves API endpoints
15- `packages/client` - React frontend using Vite
16
17## Development
18
19```bash
20# Install dependencies
21pnpm install
22
23# Option 1: Local development (login won't work due to OAuth requirements)
24pnpm dev
25
26# Option 2: Development with OAuth login support (recommended)
27pnpm dev:oauth
28```
29
30### OAuth Development
31
32Due to OAuth requirements, HTTPS is needed for development. We've made this easy:
33
34- `pnpm dev:oauth` - Sets up everything automatically:
35 1. Starts ngrok to create an HTTPS tunnel
36 2. Configures environment variables with the ngrok URL
37 3. Starts both the API server and client app
38 4. Handles proper shutdown of all processes
39
40This all-in-one command makes OAuth development seamless.
41
42### Additional Commands
43
44```bash
45# Build commands
46pnpm build # Build in correct order: lexicon → client → appview
47pnpm build:lexicon # Build only the lexicon package (type definitions)
48pnpm build:client # Build only the frontend
49pnpm build:appview # Build only the backend
50
51# Start commands
52pnpm start # Start the server (serves API and frontend)
53pnpm start:client # Start frontend development server only
54pnpm start:dev # Start both backend and frontend separately (development only)
55
56# Other utilities
57pnpm typecheck # Run type checking
58pnpm format # Format all code
59```
60
61## Deployment
62
63For production deployment:
64
651. Build all packages in the correct order:
66
67 ```bash
68 pnpm build
69 ```
70
71 This will:
72
73 - Build the lexicon package first (shared type definitions)
74 - Build the frontend (`packages/client`) next
75 - Finally build the backend (`packages/appview`)
76
772. Start the server:
78 ```bash
79 pnpm start
80 ```
81
82The backend server will:
83
84- Serve the API at `/api/*` endpoints
85- Serve the frontend static files from the client's build directory
86- Handle client-side routing by serving index.html for all non-API routes
87
88This simplifies deployment to a single process that handles both the API and serves the frontend assets.
89
90## Environment Variables
91
92Create a `.env` file in the root directory with:
93
94```
95# Required for AT Protocol authentication
96ATP_SERVICE_DID=did:plc:your-service-did
97ATP_CLIENT_ID=your-client-id
98ATP_CLIENT_SECRET=your-client-secret
99ATP_REDIRECT_URI=https://your-domain.com/oauth-callback
100
101# Optional
102PORT=3001
103SESSION_SECRET=your-session-secret
104```
105
106## Requirements
107
108- Node.js 18+
109- pnpm 9+
110- ngrok (for OAuth development)
111
112## License
113
114MIT