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 ```bash
67 pnpm build
68 ```
69
70 This will:
71 - Build the lexicon package first (shared type definitions)
72 - Build the frontend (`packages/client`) next
73 - Finally build the backend (`packages/appview`)
74
752. Start the server:
76 ```bash
77 pnpm start
78 ```
79
80The backend server will:
81- Serve the API at `/api/*` endpoints
82- Serve the frontend static files from the client's build directory
83- Handle client-side routing by serving index.html for all non-API routes
84
85This simplifies deployment to a single process that handles both the API and serves the frontend assets.
86
87## Environment Variables
88
89Create a `.env` file in the root directory with:
90
91```
92# Required for AT Protocol authentication
93ATP_SERVICE_DID=did:plc:your-service-did
94ATP_CLIENT_ID=your-client-id
95ATP_CLIENT_SECRET=your-client-secret
96ATP_REDIRECT_URI=https://your-domain.com/oauth-callback
97
98# Optional
99PORT=3001
100SESSION_SECRET=your-session-secret
101```
102
103## Requirements
104
105- Node.js 18+
106- pnpm 9+
107- ngrok (for OAuth development)
108
109## License
110
111MIT