···11+# CLAUDE.md
22+33+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
44+55+## Project Overview
66+77+This is an ATProto OAuth application monorepo with separate frontend and backend packages. The backend is built with Elysia (Bun web framework) and the frontend with React Router v7.
88+99+**Current Status**: OAuth foundation layer is complete on the backend. Frontend scaffold is ready for feature development. This is a full-stack ATProto microblogging application.
1010+1111+## Monorepo Structure
1212+1313+This project is organized as a Bun workspace monorepo:
1414+1515+```
1616+atproto-elysia/
1717+├── packages/
1818+│ ├── server/ # Elysia API backend (OAuth, database, API endpoints)
1919+│ │ ├── src/ # Server source code
2020+│ │ ├── data/ # SQLite database files
2121+│ │ ├── CLAUDE.md # Server-specific documentation
2222+│ │ └── package.json # Server dependencies
2323+│ └── client/ # React Router v7 frontend (UI, routing, components)
2424+│ ├── app/ # React Router application code
2525+│ ├── CLAUDE.md # Client-specific documentation
2626+│ └── package.json # Client dependencies
2727+├── package.json # Workspace root configuration
2828+├── tsconfig.json # Base TypeScript configuration
2929+├── CLAUDE.md # This file (monorepo-wide documentation)
3030+└── README.md # Project setup and usage instructions
3131+```
3232+3333+**Intended Architecture** (not fully implemented yet):
3434+```
3535+React Router Frontend (packages/client)
3636+ ↓ HTTP API calls
3737+Elysia API Server (packages/server) ← Backend complete
3838+ ↓ Job enqueueing
3939+Bun SQLite Queue (Job Queue) ← Not implemented
4040+ ↓ Job processing
4141+Worker Processes (Background Jobs) ← Not implemented
4242+ ↓ ATProto operations
4343+ATProto Network via @atproto/api
4444+```
4545+4646+## Common Commands
4747+4848+### Workspace Commands (from root)
4949+- `bun install` - Install dependencies for all packages
5050+- `bun run dev` - Start server development mode (port 3000)
5151+- `bun run dev:server` - Start server only
5252+- `bun run dev:client` - Start client only (port 5173)
5353+- `bun run build` - Build both server and client for production
5454+- `bun run typecheck` - Type check all packages
5555+5656+### Server Commands (from packages/server)
5757+- `bun run dev` - Start development server with hot reload on port 3000
5858+- `bun run start` - Start production server
5959+- `bun run debug` - Start server with Bun debugger
6060+- `bunx kysely-codegen --dialect bun-sqlite --env-file .env.local --out-file ./src/db/schema.d.ts` - Regenerate database schema types
6161+- `bunx --bun kysely-ctl migrate` - Run database migrations manually
6262+6363+### Client Commands (from packages/client)
6464+- `bun run dev` - Start development server with hot reload (port 5173)
6565+- `bun run build` - Build production bundle
6666+- `bun run start` - Serve production build
6767+- `bun run typecheck` - Run TypeScript type checking
6868+6969+### Typical Development Workflow
7070+1. **Terminal 1** (Server): `cd packages/server && bun run dev`
7171+2. **Terminal 2** (Client): `cd packages/client && bun run dev`
7272+3. **Access**: Open http://localhost:5173 in browser (client proxies to server)
7373+7474+## Architecture
7575+7676+### Core Stack
7777+7878+**Backend (packages/server)**:
7979+- **Runtime**: Bun
8080+- **Web Framework**: Elysia (type-safe, fast web framework)
8181+- **Database**: SQLite with Kysely query builder
8282+- **OAuth**: ATProto OAuth Client (Node implementation)
8383+- **TypeScript**: Strict mode enabled with path aliases
8484+8585+**Frontend (packages/client)**:
8686+- **Runtime**: Bun
8787+- **Framework**: React Router v7 (file-based routing, SSR-ready)
8888+- **UI Library**: React 19
8989+- **Styling**: Tailwind CSS v4
9090+- **Build Tool**: Vite
9191+- **TypeScript**: Strict mode enabled
9292+9393+**Deployment Strategy**:
9494+- Server and client deploy separately
9595+- Server: Node/Bun hosting (Fly.io, Railway, etc.)
9696+- Client: Static hosting (Vercel, Netlify, Cloudflare Pages)
9797+- CORS configured to allow client → server communication
9898+9999+### OAuth Flow Architecture
100100+101101+**Server implements ATProto OAuth** (see `packages/server/CLAUDE.md` for details):
102102+1. **Login**: Redirect to `/oauth/login?handle={handle}` on server
103103+2. **Callback**: Server handles OAuth callback, sets httpOnly cookie
104104+3. **Session**: Client calls `/oauth/state` to verify authentication status
105105+106106+**Client integration** (see `packages/client/CLAUDE.md` for implementation):
107107+- Use `credentials: 'include'` in all fetch requests to send session cookie
108108+- Protected routes check auth status via loader functions
109109+- Server CORS configured to accept credentials from client origin
110110+111111+### Database Architecture (Server)
112112+113113+**Location**: `packages/server/data/` (SQLite with WAL mode)
114114+115115+**Tables**:
116116+- `oauth_sessions` - OAuth session storage
117117+- `oauth_states` - OAuth state during authorization
118118+- `accounts` - User accounts with DID, handle, role
119119+120120+**Details**: See `packages/server/CLAUDE.md` for full database documentation
121121+122122+### Environment Variables
123123+124124+**Server** (`packages/server/.env.local`):
125125+- `PORT` - Server port (default: 3000)
126126+- `DATABASE_URL` - SQLite database path
127127+- `AUTH_SECRET` - Cookie signing secret
128128+- `BASE_URL` - OAuth redirect base URL (production)
129129+130130+**Client** (`packages/client/.env.local`):
131131+- `VITE_API_URL` - Server API URL (e.g., http://localhost:3000)
132132+133133+## Package-Specific Documentation
134134+135135+For detailed implementation information, refer to the package-specific CLAUDE.md files:
136136+137137+- **Server**: `packages/server/CLAUDE.md`
138138+ - OAuth flow implementation
139139+ - Database patterns and migrations
140140+ - API endpoint creation
141141+ - RBAC implementation guide
142142+ - ATProto API integration
143143+144144+- **Client**: `packages/client/CLAUDE.md`
145145+ - React Router v7 routing patterns
146146+ - API integration with server
147147+ - Authentication flow
148148+ - Component architecture
149149+ - Styling with Tailwind CSS
150150+151151+## Working with the Monorepo
152152+153153+### Adding New Features
154154+155155+**Backend API Endpoint**:
156156+1. Navigate to `packages/server`
157157+2. Create route handler in `src/` (or add to existing routes)
158158+3. Test with `bun run dev`
159159+4. See `packages/server/CLAUDE.md` for patterns
160160+161161+**Frontend Feature**:
162162+1. Navigate to `packages/client`
163163+2. Create route in `app/routes/` (file-based routing)
164164+3. Create components in `app/components/`
165165+4. Test with `bun run dev`
166166+5. See `packages/client/CLAUDE.md` for patterns
167167+168168+### Type Sharing Between Packages
169169+170170+If you need to share types from server to client:
171171+1. Add workspace dependency in `packages/client/package.json`:
172172+ ```json
173173+ "dependencies": {
174174+ "@atproto-elysia/server": "workspace:*"
175175+ }
176176+ ```
177177+2. Import types (not runtime code):
178178+ ```typescript
179179+ import type { Account } from '@atproto-elysia/server/src/db/schema'
180180+ ```
181181+182182+## Future Expansion
183183+184184+### Planned Features
185185+- **Job Queue & Workers**: Background processing for posts, firehose consumption, timelines
186186+- **Two-Layer Session System**: Separate app sessions for RBAC and session revocation
187187+- **Real-time Features**: WebSocket support for notifications and live updates
188188+- **Media Upload**: Image and video upload with ATProto blob storage
189189+- **Timeline Algorithm**: Personalized feed ranking and filtering
190190+- **Search**: Full-text search for posts and user profiles
191191+192192+See package-specific CLAUDE.md files for detailed implementation plans.
193193+194194+## Getting Started
195195+196196+1. **Clone and install**:
197197+ ```bash
198198+ git clone <repo-url>
199199+ cd atproto-elysia
200200+ bun install
201201+ ```
202202+203203+2. **Configure environment**:
204204+ - Copy `packages/server/.env.local.example` to `packages/server/.env.local` (if exists)
205205+ - Copy `packages/client/.env.local.example` to `packages/client/.env.local` (if exists)
206206+ - Or create from scratch using the examples in this file
207207+208208+3. **Start development**:
209209+ ```bash
210210+ # Terminal 1: Start server
211211+ cd packages/server
212212+ bun run dev
213213+214214+ # Terminal 2: Start client
215215+ cd packages/client
216216+ bun run dev
217217+ ```
218218+219219+4. **Access the application**:
220220+ - Client: http://localhost:5173
221221+ - Server API: http://localhost:3000
222222+ - API Docs: http://localhost:3000/swagger
223223+224224+## Troubleshooting
225225+226226+- **Port conflicts**: Change `PORT` in server .env.local or client will use next available port
227227+- **CORS errors**: Ensure server CORS is configured to allow client origin
228228+- **Type errors**: Run `bun install` at root to sync workspace dependencies
229229+- **Database issues**: Delete `packages/server/data/*.db*` files and restart server to reset
230230+231231+For package-specific issues, see the CLAUDE.md file in that package.
+241-7
README.md
···11-# Elysia with Bun runtime
11+# ATProto OAuth Application
22+33+A full-stack ATProto microblogging application with OAuth authentication. Built with Elysia (backend) and React Router v7 (frontend) in a Bun workspace monorepo.
44+55+## Project Structure
66+77+```
88+atproto-elysia/
99+├── packages/
1010+│ ├── server/ # Elysia API backend
1111+│ │ ├── src/ # Server source code
1212+│ │ ├── data/ # SQLite database
1313+│ │ └── CLAUDE.md # Server documentation
1414+│ └── client/ # React Router v7 frontend
1515+│ ├── app/ # React Router app
1616+│ └── CLAUDE.md # Client documentation
1717+├── package.json # Workspace configuration
1818+└── CLAUDE.md # Project-wide documentation
1919+```
2020+2121+## Tech Stack
2222+2323+**Backend**:
2424+- Bun runtime
2525+- Elysia web framework
2626+- SQLite + Kysely ORM
2727+- ATProto OAuth Client
22833-## Getting Started
44-To get started with this template, simply paste this command into your terminal:
2929+**Frontend**:
3030+- React Router v7
3131+- React 19
3232+- Tailwind CSS v4
3333+- Vite
3434+3535+## Quick Start
3636+3737+### Prerequisites
3838+- [Bun](https://bun.sh) v1.0+
3939+4040+### Installation
4141+4242+1. Clone the repository:
4343+ ```bash
4444+ git clone <repository-url>
4545+ cd atproto-elysia
4646+ ```
4747+4848+2. Install dependencies:
4949+ ```bash
5050+ bun install
5151+ ```
5252+5353+3. Configure environment variables:
5454+5555+ **Server** (`packages/server/.env.local`):
5656+ ```env
5757+ PORT=3000
5858+ DATABASE_URL=./data/dev.db
5959+ AUTH_SECRET=your-secret-key-here
6060+ BASE_URL=http://localhost:3000
6161+ ```
6262+6363+ **Client** (`packages/client/.env.local`):
6464+ ```env
6565+ VITE_API_URL=http://localhost:3000
6666+ ```
6767+6868+### Development
6969+7070+Run both server and client in separate terminals:
7171+7272+**Terminal 1 - Server**:
573```bash
66-bun create elysia ./elysia-example
7474+cd packages/server
7575+bun run dev
776```
87799-## Development
1010-To start the development server run:
7878+**Terminal 2 - Client**:
1179```bash
8080+cd packages/client
1281bun run dev
1382```
14831515-Open http://localhost:3000/ with your browser to see the result.8484+Then open:
8585+- **Frontend**: http://localhost:5173
8686+- **API**: http://localhost:3000
8787+- **API Docs**: http://localhost:3000/swagger
8888+8989+### Alternative: Run from Root
9090+9191+You can also use workspace scripts from the root:
9292+9393+```bash
9494+# Start server only
9595+bun run dev
9696+9797+# Start client only
9898+bun run dev:client
9999+100100+# Build both packages
101101+bun run build
102102+103103+# Type check all packages
104104+bun run typecheck
105105+```
106106+107107+## Project Commands
108108+109109+### Root Commands
110110+```bash
111111+bun install # Install all workspace dependencies
112112+bun run dev # Start server
113113+bun run dev:server # Start server (explicit)
114114+bun run dev:client # Start client
115115+bun run build # Build both packages
116116+bun run typecheck # Type check all packages
117117+```
118118+119119+### Server Commands (packages/server)
120120+```bash
121121+bun run dev # Start development server (port 3000)
122122+bun run start # Start production server
123123+bun run debug # Start with debugger
124124+bun run codegen # Regenerate database types
125125+bun run migrate # Run database migrations
126126+```
127127+128128+### Client Commands (packages/client)
129129+```bash
130130+bun run dev # Start development server (port 5173)
131131+bun run build # Build for production
132132+bun run start # Preview production build
133133+bun run typecheck # Type check
134134+```
135135+136136+## Features
137137+138138+### Current
139139+- ✅ ATProto OAuth authentication
140140+- ✅ Session management with cookies
141141+- ✅ User account tracking
142142+- ✅ React Router v7 frontend scaffold
143143+- ✅ Tailwind CSS styling
144144+- ✅ TypeScript throughout
145145+146146+### Planned
147147+- 🚧 User authentication UI
148148+- 🚧 ATProto feed display
149149+- 🚧 Post creation
150150+- 🚧 User profiles
151151+- 🚧 Real-time updates
152152+- 🚧 Background job processing
153153+154154+## Architecture
155155+156156+### Backend (packages/server)
157157+- **Framework**: Elysia (fast, type-safe web framework)
158158+- **Database**: SQLite with Kysely query builder
159159+- **OAuth**: ATProto OAuth implementation
160160+- **API**: RESTful endpoints with OpenAPI docs
161161+162162+### Frontend (packages/client)
163163+- **Framework**: React Router v7 (with framework mode)
164164+- **Routing**: File-based routes in `app/routes/`
165165+- **Styling**: Tailwind CSS v4
166166+- **Build**: Vite
167167+168168+### Communication
169169+- Client ↔ Server: HTTP REST API
170170+- Authentication: httpOnly cookies
171171+- CORS: Configured for separate origins
172172+173173+## Deployment
174174+175175+### Server
176176+Deploy to Node/Bun compatible hosting:
177177+- [Fly.io](https://fly.io)
178178+- [Railway](https://railway.app)
179179+- [Render](https://render.com)
180180+181181+### Client
182182+Deploy to static hosting:
183183+- [Vercel](https://vercel.com)
184184+- [Netlify](https://netlify.com)
185185+- [Cloudflare Pages](https://pages.cloudflare.com)
186186+187187+### Environment Variables
188188+Configure production environment variables in your hosting provider:
189189+- Server: Set `BASE_URL`, `AUTH_SECRET`, `DATABASE_URL`
190190+- Client: Set `VITE_API_URL` to production server URL
191191+192192+## Documentation
193193+194194+Detailed documentation is available in CLAUDE.md files:
195195+- **Root**: `CLAUDE.md` - Monorepo overview and workflow
196196+- **Server**: `packages/server/CLAUDE.md` - Backend architecture and patterns
197197+- **Client**: `packages/client/CLAUDE.md` - Frontend architecture and patterns
198198+199199+## Development Workflow
200200+201201+### Adding a Backend Feature
202202+1. Navigate to `packages/server`
203203+2. Create/modify routes in `src/`
204204+3. Add database migrations if needed
205205+4. Test with `bun run dev`
206206+5. See `packages/server/CLAUDE.md` for patterns
207207+208208+### Adding a Frontend Feature
209209+1. Navigate to `packages/client`
210210+2. Create route file in `app/routes/`
211211+3. Create components as needed
212212+4. Style with Tailwind CSS
213213+5. Test with `bun run dev`
214214+6. See `packages/client/CLAUDE.md` for patterns
215215+216216+### Database Migrations
217217+```bash
218218+cd packages/server
219219+220220+# Create migration file manually in src/db/migrations/
221221+# Then regenerate types:
222222+bun run codegen
223223+```
224224+225225+## Troubleshooting
226226+227227+**Port already in use**:
228228+- Change `PORT` in `packages/server/.env.local`
229229+- Client will auto-increment port if 5173 is taken
230230+231231+**CORS errors**:
232232+- Ensure server CORS allows client origin
233233+- Check `VITE_API_URL` matches server URL
234234+235235+**Type errors**:
236236+- Run `bun install` at root to sync workspace
237237+- Run `bun run typecheck` to find issues
238238+239239+**Database issues**:
240240+- Delete `packages/server/data/*.db*` files
241241+- Restart server to recreate database
242242+243243+## License
244244+245245+MIT
246246+247247+## Contributing
248248+249249+See CLAUDE.md for development guidelines and architecture patterns.
···11+# CLAUDE.md - Client Package
22+33+This file provides guidance to Claude Code (claude.ai/code) when working with the client package in this monorepo.
44+55+## Package Overview
66+77+This is the client package of the ATProto OAuth application monorepo. It's a React Router v7 application that provides the frontend interface for the ATProto microblogging application.
88+99+**Current Status**: Initial React Router v7 scaffold created. Ready for feature development.
1010+1111+**Monorepo Structure**:
1212+```
1313+atproto-elysia/ (root)
1414+├── packages/
1515+│ ├── server/ # Elysia API backend
1616+│ └── client/ # This package (React Router v7 frontend)
1717+├── package.json # Workspace root configuration
1818+└── CLAUDE.md # Monorepo-wide documentation
1919+```
2020+2121+**Architecture**:
2222+```
2323+React Router (Frontend) - This package
2424+ ↓ HTTP API calls
2525+Elysia API Server (Backend) - packages/server
2626+ ↓ OAuth & Database
2727+ATProto Network via @atproto/api
2828+```
2929+3030+## Common Commands
3131+3232+### Development
3333+- `bun run dev` - Start development server with hot reload (default port: 5173)
3434+- `bun run build` - Build production bundle
3535+- `bun run start` - Start production server (serves built bundle)
3636+- `bun run typecheck` - Run TypeScript type checking
3737+3838+### Running from Root
3939+- `cd packages/client && bun run dev` - Direct package commands
4040+- `bun run dev:client` - Run via workspace scripts (from root)
4141+4242+## Architecture
4343+4444+### Core Stack
4545+- **Runtime**: Bun
4646+- **Framework**: React Router v7 (with framework mode)
4747+- **UI Library**: React 19
4848+- **Styling**: Tailwind CSS v4
4949+- **Build Tool**: Vite
5050+- **TypeScript**: Strict mode enabled with path aliases
5151+- **Deployment Target**: Static hosting (Vercel, Netlify, Cloudflare Pages)
5252+5353+### Project Structure
5454+5555+```
5656+packages/client/
5757+├── app/ # React Router application code
5858+│ ├── routes/ # File-based routing (routes._index.tsx, etc.)
5959+│ ├── components/ # React components (to be added)
6060+│ ├── lib/ # Utilities and helpers (to be added)
6161+│ ├── styles/ # Global styles (to be added)
6262+│ ├── root.tsx # Root layout component
6363+│ └── entry.client.tsx # Client entry point
6464+├── public/ # Static assets (served as-is)
6565+├── build/ # Production build output (gitignored)
6666+├── package.json # Package dependencies and scripts
6767+├── tsconfig.json # TypeScript configuration
6868+├── vite.config.ts # Vite bundler configuration
6969+├── react-router.config.ts # React Router framework configuration
7070+├── .env.local # Environment variables (not in git)
7171+└── CLAUDE.md # This file
7272+```
7373+7474+### React Router v7 Features
7575+7676+**File-Based Routing**:
7777+- Routes defined in `app/routes/` directory
7878+- Example: `app/routes/_index.tsx` → `/`
7979+- Example: `app/routes/about.tsx` → `/about`
8080+- Nested routes: `app/routes/posts.$id.tsx` → `/posts/:id`
8181+8282+**Data Loading**:
8383+- Use `loader` functions for server/build-time data fetching
8484+- Use `clientLoader` for client-side data fetching
8585+- Use `action` functions for form submissions and mutations
8686+8787+**Layout System**:
8888+- `app/root.tsx` - Root layout wrapper
8989+- Nested layouts via route modules
9090+- Outlet component for child route rendering
9191+9292+### API Integration
9393+9494+**Environment Configuration**:
9595+- `VITE_API_URL` - Server API base URL (configured in `.env.local`)
9696+- Development default: `http://localhost:3000`
9797+- Production: Set to your deployed server URL
9898+9999+**Making API Calls**:
100100+```typescript
101101+// In a loader or action
102102+export async function loader() {
103103+ const response = await fetch(`${import.meta.env.VITE_API_URL}/api/endpoint`)
104104+ const data = await response.json()
105105+ return data
106106+}
107107+108108+// In a component (client-side)
109109+export default function MyComponent() {
110110+ const handleAction = async () => {
111111+ const response = await fetch(`${import.meta.env.VITE_API_URL}/api/endpoint`, {
112112+ method: 'POST',
113113+ headers: { 'Content-Type': 'application/json' },
114114+ body: JSON.stringify({ /* data */ })
115115+ })
116116+ // Handle response
117117+ }
118118+}
119119+```
120120+121121+**Type Sharing** (when needed):
122122+- Can import types from server package via workspace dependencies
123123+- Add to dependencies: `"@atproto-elysia/server": "workspace:*"`
124124+- Import: `import type { AccountType } from '@atproto-elysia/server/src/db/schema'`
125125+126126+### Styling
127127+128128+**Tailwind CSS v4**:
129129+- Configured via Vite plugin (`@tailwindcss/vite`)
130130+- Use utility classes directly in JSX
131131+- Global styles in `app/styles/` (to be created)
132132+- Tailwind config: Uses default configuration (can be customized)
133133+134134+**Example**:
135135+```tsx
136136+export default function Button({ children }) {
137137+ return (
138138+ <button className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600">
139139+ {children}
140140+ </button>
141141+ )
142142+}
143143+```
144144+145145+### Authentication Flow
146146+147147+**OAuth Integration with Server**:
148148+1. **Login**: Redirect user to server's `/oauth/login?handle={handle}`
149149+2. **Callback**: Server handles OAuth callback, sets session cookie
150150+3. **Session Check**: Client calls server's `/oauth/state` to verify authentication
151151+4. **Protected Routes**: Use loaders to check auth state before rendering
152152+153153+**Example Protected Route**:
154154+```typescript
155155+// app/routes/dashboard.tsx
156156+export async function loader() {
157157+ const response = await fetch(`${import.meta.env.VITE_API_URL}/oauth/state`, {
158158+ credentials: 'include' // Important: sends cookies
159159+ })
160160+161161+ if (!response.ok) {
162162+ // Not authenticated, redirect to login
163163+ throw redirect('/login')
164164+ }
165165+166166+ const userData = await response.json()
167167+ return userData
168168+}
169169+```
170170+171171+## Key Implementation Details
172172+173173+### Fetch Configuration
174174+- **Always use `credentials: 'include'`** when calling server API to send session cookies
175175+- CORS is configured on server to allow client origin
176176+- Cookies are httpOnly and set by server
177177+178178+### Environment Variables
179179+- All client env vars must be prefixed with `VITE_` to be exposed to client code
180180+- Access via `import.meta.env.VITE_*`
181181+- Never commit `.env.local` to git
182182+183183+### TypeScript Configuration
184184+- Path aliases configured in `tsconfig.json`
185185+- Vite handles path resolution via `vite-tsconfig-paths` plugin
186186+- Type generation via `react-router typegen` command
187187+188188+### Build & Deployment
189189+- Production build outputs to `build/` directory
190190+- Build includes both client and server bundles (for SSR)
191191+- For separate deployment (static hosting), use client bundle only
192192+- Deployment targets: Vercel, Netlify, Cloudflare Pages, etc.
193193+194194+## Development Workflow
195195+196196+### Starting Development
197197+1. **Start server** (in separate terminal):
198198+ ```bash
199199+ cd packages/server
200200+ bun run dev
201201+ ```
202202+203203+2. **Start client**:
204204+ ```bash
205205+ cd packages/client
206206+ bun run dev
207207+ ```
208208+209209+3. **Access app**: Open `http://localhost:5173` in browser
210210+211211+### Adding New Features
212212+1. Create route files in `app/routes/`
213213+2. Create components in `app/components/`
214214+3. Add API calls using `fetch` with `VITE_API_URL`
215215+4. Style with Tailwind CSS utility classes
216216+5. Test locally with both client and server running
217217+218218+### Type Safety
219219+- Run `bun run typecheck` regularly during development
220220+- React Router generates route types automatically
221221+- Use TypeScript's strict mode features
222222+223223+## Monorepo Integration
224224+225225+### Server Communication
226226+- **API Base URL**: Configured via `VITE_API_URL` environment variable
227227+- **CORS**: Server must allow client origin (configured in server package)
228228+- **Cookies**: Server sets httpOnly session cookies, client sends via `credentials: 'include'`
229229+230230+### Deployment Strategy
231231+- **Client**: Deploy to static hosting (Vercel, Netlify, Cloudflare Pages)
232232+- **Server**: Deploys separately to Node/Bun hosting (Fly.io, Railway, etc.)
233233+- **Environment**: Set `VITE_API_URL` to production server URL in deployment config
234234+- **CORS**: Ensure production server CORS allows production client domain
235235+236236+### Workspace Dependencies
237237+- Can add server package as dependency if type sharing is needed
238238+- Avoid importing server runtime code (only types)
239239+240240+## Future Expansion
241241+242242+### Planned Features
243243+- **Authentication UI**: Login page, user profile, session management
244244+- **ATProto Feed**: Display posts from ATProto network
245245+- **Post Creation**: Create new posts with text and media
246246+- **Timeline**: Personalized feed based on follows
247247+- **Notifications**: Real-time notifications for interactions
248248+- **User Profiles**: View and edit user profiles
249249+- **Search**: Search for users and posts
250250+251251+### State Management
252252+- Consider adding state management library if app complexity grows
253253+- Options: Zustand, Jotai, Redux Toolkit, or React Context
254254+- For now, use React Router loaders and React state
255255+256256+### Testing
257257+- Add testing framework (Vitest recommended)
258258+- Component testing with React Testing Library
259259+- E2E testing with Playwright
260260+261261+### Performance Optimization
262262+- Implement code splitting for routes (automatic with React Router)
263263+- Optimize images and assets
264264+- Add loading states and skeleton screens
265265+- Implement virtual scrolling for long lists
···11+# Welcome to React Router!
22+33+A modern, production-ready template for building full-stack React applications using React Router.
44+55+[](https://stackblitz.com/github/remix-run/react-router-templates/tree/main/default)
66+77+## Features
88+99+- 🚀 Server-side rendering
1010+- ⚡️ Hot Module Replacement (HMR)
1111+- 📦 Asset bundling and optimization
1212+- 🔄 Data loading and mutations
1313+- 🔒 TypeScript by default
1414+- 🎉 TailwindCSS for styling
1515+- 📖 [React Router docs](https://reactrouter.com/)
1616+1717+## Getting Started
1818+1919+### Installation
2020+2121+Install the dependencies:
2222+2323+```bash
2424+npm install
2525+```
2626+2727+### Development
2828+2929+Start the development server with HMR:
3030+3131+```bash
3232+npm run dev
3333+```
3434+3535+Your application will be available at `http://localhost:5173`.
3636+3737+## Building for Production
3838+3939+Create a production build:
4040+4141+```bash
4242+npm run build
4343+```
4444+4545+## Deployment
4646+4747+### Docker Deployment
4848+4949+To build and run using Docker:
5050+5151+```bash
5252+docker build -t my-app .
5353+5454+# Run the container
5555+docker run -p 3000:3000 my-app
5656+```
5757+5858+The containerized application can be deployed to any platform that supports Docker, including:
5959+6060+- AWS ECS
6161+- Google Cloud Run
6262+- Azure Container Apps
6363+- Digital Ocean App Platform
6464+- Fly.io
6565+- Railway
6666+6767+### DIY Deployment
6868+6969+If you're familiar with deploying Node applications, the built-in app server is production-ready.
7070+7171+Make sure to deploy the output of `npm run build`
7272+7373+```
7474+├── package.json
7575+├── package-lock.json (or pnpm-lock.yaml, or bun.lockb)
7676+├── build/
7777+│ ├── client/ # Static assets
7878+│ └── server/ # Server-side code
7979+```
8080+8181+## Styling
8282+8383+This template comes with [Tailwind CSS](https://tailwindcss.com/) already configured for a simple default starting experience. You can use whatever CSS framework you prefer.
8484+8585+---
8686+8787+Built with ❤️ using React Router.
···11+import type { Config } from "@react-router/dev/config";
22+33+export default {
44+ // Config options...
55+ // Server-side render by default, to enable SPA mode set this to `false`
66+ ssr: true,
77+} satisfies Config;
···11{
22 "compilerOptions": {
33- /* Visit https://aka.ms/tsconfig to read more about this file */
44-55- /* Projects */
66- // "incremental": true, /* Save .tsbuildinfo files to allow for incremental compilation of projects. */
77- // "composite": true, /* Enable constraints that allow a TypeScript project to be used with project references. */
88- // "tsBuildInfoFile": "./.tsbuildinfo", /* Specify the path to .tsbuildinfo incremental compilation file. */
99- // "disableSourceOfProjectReferenceRedirect": true, /* Disable preferring source files instead of declaration files when referencing composite projects. */
1010- // "disableSolutionSearching": true, /* Opt a project out of multi-project reference checking when editing. */
1111- // "disableReferencedProjectLoad": true, /* Reduce the number of projects loaded automatically by TypeScript. */
1212-1313- /* Language and Environment */
1414- "target": "ES2021" /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */,
1515- // "lib": [], /* Specify a set of bundled library declaration files that describe the target runtime environment. */
1616- "jsx": "preserve" /* Specify what JSX code is generated. */,
1717- // "experimentalDecorators": true, /* Enable experimental support for TC39 stage 2 draft decorators. */
1818- // "emitDecoratorMetadata": true, /* Emit design-type metadata for decorated declarations in source files. */
1919- // "jsxFactory": "", /* Specify the JSX factory function used when targeting React JSX emit, e.g. 'React.createElement' or 'h'. */
2020- // "jsxFragmentFactory": "", /* Specify the JSX Fragment reference used for fragments when targeting React JSX emit e.g. 'React.Fragment' or 'Fragment'. */
2121- // "jsxImportSource": "", /* Specify module specifier used to import the JSX factory functions when using 'jsx: react-jsx*'. */
2222- // "reactNamespace": "", /* Specify the object invoked for 'createElement'. This only applies when targeting 'react' JSX emit. */
2323- // "noLib": true, /* Disable including any library files, including the default lib.d.ts. */
2424- // "useDefineForClassFields": true, /* Emit ECMAScript-standard-compliant class fields. */
2525- // "moduleDetection": "auto", /* Control what method is used to detect module-format JS files. */
2626-2727- /* Modules */
2828- "module": "ES2022" /* Specify what module code is generated. */,
2929- // "rootDir": "./", /* Specify the root folder within your source files. */
3030- "moduleResolution": "node" /* Specify how TypeScript looks up a file from a given module specifier. */,
3131- // "baseUrl": "./", /* Specify the base directory to resolve non-relative module names. */
3232- // "paths": {}, /* Specify a set of entries that re-map imports to additional lookup locations. */
3333- // "rootDirs": [], /* Allow multiple folders to be treated as one when resolving modules. */
3434- // "typeRoots": [], /* Specify multiple folders that act like './node_modules/@types'. */
3535- "types": [
3636- "bun-types"
3737- ] /* Specify type package names to be included without being referenced in a source file. */,
3838- // "allowUmdGlobalAccess": true, /* Allow accessing UMD globals from modules. */
3939- // "moduleSuffixes": [], /* List of file name suffixes to search when resolving a module. */
4040- "resolveJsonModule": true /* Enable importing .json files. */,
4141- // "noResolve": true, /* Disallow 'import's, 'require's or '<reference>'s from expanding the number of files TypeScript should add to a project. */
4242-4343- /* JavaScript Support */
4444- // "allowJs": true, /* Allow JavaScript files to be a part of your program. Use the 'checkJS' option to get errors from these files. */
4545- // "checkJs": true, /* Enable error reporting in type-checked JavaScript files. */
4646- // "maxNodeModuleJsDepth": 1, /* Specify the maximum folder depth used for checking JavaScript files from 'node_modules'. Only applicable with 'allowJs'. */
4747-4848- /* Emit */
4949- // "declaration": true, /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
5050- // "declarationMap": true, /* Create sourcemaps for d.ts files. */
5151- // "emitDeclarationOnly": true, /* Only output d.ts files and not JavaScript files. */
5252- // "sourceMap": true, /* Create source map files for emitted JavaScript files. */
5353- // "outFile": "./", /* Specify a file that bundles all outputs into one JavaScript file. If 'declaration' is true, also designates a file that bundles all .d.ts output. */
5454- // "outDir": "./", /* Specify an output folder for all emitted files. */
5555- // "removeComments": true, /* Disable emitting comments. */
5656- // "noEmit": true, /* Disable emitting files from a compilation. */
5757- // "importHelpers": true, /* Allow importing helper functions from tslib once per project, instead of including them per-file. */
5858- // "importsNotUsedAsValues": "remove", /* Specify emit/checking behavior for imports that are only used for types. */
5959- // "downlevelIteration": true, /* Emit more compliant, but verbose and less performant JavaScript for iteration. */
6060- // "sourceRoot": "", /* Specify the root path for debuggers to find the reference source code. */
6161- // "mapRoot": "", /* Specify the location where debugger should locate map files instead of generated locations. */
6262- // "inlineSourceMap": true, /* Include sourcemap files inside the emitted JavaScript. */
6363- // "inlineSources": true, /* Include source code in the sourcemaps inside the emitted JavaScript. */
6464- // "emitBOM": true, /* Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files. */
6565- // "newLine": "crlf", /* Set the newline character for emitting files. */
6666- // "stripInternal": true, /* Disable emitting declarations that have '@internal' in their JSDoc comments. */
6767- // "noEmitHelpers": true, /* Disable generating custom helper functions like '__extends' in compiled output. */
6868- // "noEmitOnError": true, /* Disable emitting files if any type checking errors are reported. */
6969- // "preserveConstEnums": true, /* Disable erasing 'const enum' declarations in generated code. */
7070- // "declarationDir": "./", /* Specify the output directory for generated declaration files. */
7171- // "preserveValueImports": true, /* Preserve unused imported values in the JavaScript output that would otherwise be removed. */
7272-7373- /* Interop Constraints */
7474- // "isolatedModules": true, /* Ensure that each file can be safely transpiled without relying on other imports. */
7575- // "allowSyntheticDefaultImports": true, /* Allow 'import x from y' when a module doesn't have a default export. */
7676- "esModuleInterop": true /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */,
7777- // "preserveSymlinks": true, /* Disable resolving symlinks to their realpath. This correlates to the same flag in node. */
7878- "forceConsistentCasingInFileNames": true /* Ensure that casing is correct in imports. */,
7979-8080- /* Type Checking */
8181- "strict": true /* Enable all strict type-checking options. */,
8282- // "noImplicitAny": true, /* Enable error reporting for expressions and declarations with an implied 'any' type. */
8383- // "strictNullChecks": true, /* When type checking, take into account 'null' and 'undefined'. */
8484- // "strictFunctionTypes": true, /* When assigning functions, check to ensure parameters and the return values are subtype-compatible. */
8585- // "strictBindCallApply": true, /* Check that the arguments for 'bind', 'call', and 'apply' methods match the original function. */
8686- // "strictPropertyInitialization": true, /* Check for class properties that are declared but not set in the constructor. */
8787- // "noImplicitThis": true, /* Enable error reporting when 'this' is given the type 'any'. */
8888- // "useUnknownInCatchVariables": true, /* Default catch clause variables as 'unknown' instead of 'any'. */
8989- // "alwaysStrict": true, /* Ensure 'use strict' is always emitted. */
9090- // "noUnusedLocals": true, /* Enable error reporting when local variables aren't read. */
9191- // "noUnusedParameters": true, /* Raise an error when a function parameter isn't read. */
9292- // "exactOptionalPropertyTypes": true, /* Interpret optional property types as written, rather than adding 'undefined'. */
9393- // "noImplicitReturns": true, /* Enable error reporting for codepaths that do not explicitly return in a function. */
9494- // "noFallthroughCasesInSwitch": true, /* Enable error reporting for fallthrough cases in switch statements. */
9595- // "noUncheckedIndexedAccess": true, /* Add 'undefined' to a type when accessed using an index. */
9696- // "noImplicitOverride": true, /* Ensure overriding members in derived classes are marked with an override modifier. */
9797- // "noPropertyAccessFromIndexSignature": true, /* Enforces using indexed accessors for keys declared using an indexed type. */
9898- // "allowUnusedLabels": true, /* Disable error reporting for unused labels. */
9999- // "allowUnreachableCode": true, /* Disable error reporting for unreachable code. */
100100-101101- /* Completeness */
102102- // "skipDefaultLibCheck": true, /* Skip type checking .d.ts files that are included with TypeScript. */
103103- "skipLibCheck": true /* Skip type checking all .d.ts files. */,
104104- "baseUrl": ".",
105105- "paths": {
106106- "@/*": ["src/*"],
107107- "~/*": ["public/*"]
108108- }
109109- }
33+ /* Base configuration for monorepo */
44+ "target": "ES2021",
55+ "module": "ES2022",
66+ "moduleResolution": "node",
77+ "resolveJsonModule": true,
88+ "esModuleInterop": true,
99+ "forceConsistentCasingInFileNames": true,
1010+ "strict": true,
1111+ "skipLibCheck": true
1212+ },
1313+ "files": [],
1414+ "references": [
1515+ { "path": "./packages/server" },
1616+ { "path": "./packages/client" }
1717+ ]
11018}