311 lines
6.6 KiB
Markdown
311 lines
6.6 KiB
Markdown
# TaylorDB + tRPC Full-Stack Monorepo
|
|
|
|
A production-ready pnpm monorepo combining React frontend and Express backend with tRPC for type-safe API communication. Built for AI-assisted development platforms.
|
|
|
|
## 📦 Monorepo Structure
|
|
|
|
```
|
|
taylordb-clientserver-template/
|
|
├── pnpm-workspace.yaml # Workspace configuration
|
|
├── package.json # @repo/frontend (root)
|
|
├── server/
|
|
│ ├── package.json # @repo/server
|
|
│ ├── index.ts # Express + tRPC server
|
|
│ ├── router.ts # tRPC procedures
|
|
│ ├── trpc.ts # tRPC configuration
|
|
│ └── taylordb/
|
|
│ ├── types.ts # Auto-generated TaylorDB types
|
|
│ └── query-builder.ts # TaylorDB CRUD operations
|
|
├── src/ # React frontend
|
|
└── ...
|
|
```
|
|
|
|
## 🚀 Quick Start
|
|
|
|
```bash
|
|
# Install all workspace dependencies
|
|
pnpm install
|
|
|
|
# Run both frontend and backend
|
|
pnpm dev:full
|
|
|
|
# Or run separately
|
|
pnpm dev # Frontend only (port 5173)
|
|
pnpm dev:server # Backend only (port 3001)
|
|
```
|
|
|
|
Visit:
|
|
|
|
- **Frontend**: http://localhost:5173
|
|
- **Backend**: http://localhost:3001
|
|
- **Demo Page**: http://localhost:5173/trpc-demo
|
|
|
|
## 📚 Workspaces
|
|
|
|
### @repo/frontend (Root)
|
|
|
|
The React + Vite frontend application
|
|
|
|
**Location**: `/` (root directory)
|
|
|
|
**Tech Stack**:
|
|
|
|
- React 19 with TypeScript
|
|
- Vite 7 for bundling
|
|
- TailwindCSS 4 for styling
|
|
- shadcn/ui components
|
|
- React Router v6
|
|
- tRPC React Query client
|
|
|
|
**Scripts**:
|
|
|
|
```bash
|
|
pnpm dev # Start dev server
|
|
pnpm build # Build for production
|
|
pnpm lint # Run ESLint
|
|
```
|
|
|
|
### @repo/server
|
|
|
|
The Express + tRPC backend API
|
|
|
|
**Location**: `/server`
|
|
|
|
**Tech Stack**:
|
|
|
|
- Express 5 web server
|
|
- tRPC 11 for type-safe APIs
|
|
- TaylorDB query builder
|
|
- Zod for validation
|
|
- TypeScript 5
|
|
|
|
**Scripts**:
|
|
|
|
```bash
|
|
pnpm --filter @repo/server dev # Start with hot reload
|
|
pnpm --filter @repo/server build # Build TypeScript
|
|
pnpm --filter @repo/server start # Run production build
|
|
```
|
|
|
|
## 🛠️ Available Scripts
|
|
|
|
### Root Commands (run from anywhere)
|
|
|
|
```bash
|
|
# Development
|
|
pnpm dev:full # Run both workspaces concurrently
|
|
pnpm dev # Frontend only
|
|
pnpm dev:server # Backend only
|
|
|
|
# Building
|
|
pnpm build # Build frontend
|
|
pnpm build:server # Build backend
|
|
pnpm build:all # Build both
|
|
|
|
# Other
|
|
pnpm lint # Lint all code
|
|
pnpm generate:schema # Generate TaylorDB types
|
|
```
|
|
|
|
### Workspace-Specific Commands
|
|
|
|
```bash
|
|
# Run command in specific workspace
|
|
pnpm --filter @repo/frontend <command>
|
|
pnpm --filter @repo/server <command>
|
|
|
|
# Examples
|
|
pnpm --filter @repo/server dev
|
|
pnpm --filter @repo/frontend build
|
|
```
|
|
|
|
## 🔧 Configuration Files
|
|
|
|
### pnpm-workspace.yaml
|
|
|
|
Defines workspace packages:
|
|
|
|
```yaml
|
|
packages:
|
|
- "server"
|
|
- "."
|
|
```
|
|
|
|
### Package Names
|
|
|
|
- Frontend: `@repo/frontend`
|
|
- Backend: `@repo/server`
|
|
|
|
All packages are marked as `private: true` (not published to npm)
|
|
|
|
## 📡 API Communication
|
|
|
|
### tRPC Router Export
|
|
|
|
The backend exports its router type from `server/router.ts`:
|
|
|
|
```typescript
|
|
export type AppRouter = typeof appRouter;
|
|
```
|
|
|
|
### Frontend tRPC Client
|
|
|
|
The frontend imports the type for end-to-end type safety:
|
|
|
|
```typescript
|
|
import type { AppRouter } from "../../server/router";
|
|
export const trpc = createTRPCReact<AppRouter>();
|
|
```
|
|
|
|
**Note**: This works because both packages are in the same monorepo, allowing direct TypeScript imports without shared packages.
|
|
|
|
## 🗄️ TaylorDB Integration
|
|
|
|
### Setup
|
|
|
|
1. Copy `.env.example` to `.env`
|
|
2. Add your TaylorDB credentials:
|
|
```bash
|
|
TAYLORDB_BASE_URL=your_base_url
|
|
TAYLORDB_BASE_ID=your_base_id
|
|
TAYLORDB_API_KEY=your_api_key
|
|
```
|
|
3. Generate types: `pnpm generate:schema`
|
|
|
|
### CRUD Operations
|
|
|
|
50+ type-safe procedures available:
|
|
|
|
- **Weight Tracking**: Full CRUD + statistics
|
|
- **Goals Management**: Create, read, update, delete
|
|
- **Strength Workouts**: Exercise logging
|
|
- **Cardio Exercises**: Duration, distance, speed tracking
|
|
- **Calories/Nutrition**: Daily totals and aggregations
|
|
- **Settings**: Key-value configuration
|
|
|
|
See [TAYLORDB_INTEGRATION.md](file:///Users/thetaung/Desktop/taylordb-clientserver-template/TAYLORDB_INTEGRATION.md) for detailed examples.
|
|
|
|
## 🏗️ Monorepo Benefits
|
|
|
|
### For This Project
|
|
|
|
✅ **Shared Types**: Frontend and backend share TypeScript types directly
|
|
✅ **Single Repository**: One git repo, one pnpm-lock.yaml
|
|
✅ **Coordinated Builds**: Build both projects together
|
|
✅ **Simplified Setup**: One `pnpm install` for everything
|
|
✅ **Workspace Commands**: Target specific packages easily
|
|
|
|
### Compared to Separate Repos
|
|
|
|
- ⚡ Faster development (no publishing to npm for type updates)
|
|
- 🔒 Type safety guaranteed at development time
|
|
- 📝 Simpler dependency management
|
|
- 🔄 Atomic commits across frontend and backend
|
|
|
|
## 📦 Dependency Management
|
|
|
|
### Installing Dependencies
|
|
|
|
**For frontend**:
|
|
|
|
```bash
|
|
# From root
|
|
pnpm add <package>
|
|
|
|
# Or explicitly
|
|
pnpm --filter @repo/frontend add <package>
|
|
```
|
|
|
|
**For backend**:
|
|
|
|
```bash
|
|
pnpm --filter @repo/server add <package>
|
|
```
|
|
|
|
**For both**:
|
|
|
|
```bash
|
|
pnpm add <package> -w # Add to root workspace
|
|
```
|
|
|
|
### Workspace Dependencies
|
|
|
|
Workspaces can depend on each other using `workspace:*`:
|
|
|
|
```json
|
|
{
|
|
"dependencies": {
|
|
"@repo/shared": "workspace:*"
|
|
}
|
|
}
|
|
```
|
|
|
|
## 🚢 Deployment
|
|
|
|
### Option 1: Deploy Separately
|
|
|
|
- Frontend → Vercel/Netlify (static site from `dist/`)
|
|
- Backend → Railway/Render/Fly.io (Node.js app)
|
|
|
|
Build commands:
|
|
|
|
```bash
|
|
pnpm build # Frontend
|
|
pnpm build:server # Backend
|
|
```
|
|
|
|
### Option 2: Deploy Together
|
|
|
|
Serve frontend from backend:
|
|
|
|
```bash
|
|
pnpm build:all # Build both
|
|
# Configure Express to serve frontend static files
|
|
```
|
|
|
|
### Environment Variables
|
|
|
|
Set these in your deployment platform:
|
|
|
|
- `TAYLORDB_BASE_URL`
|
|
- `TAYLORDB_BASE_ID`
|
|
- `TAYLORDB_API_KEY`
|
|
- `FRONTEND_URL` (for CORS)
|
|
- `VITE_TRPC_URL` (frontend)
|
|
|
|
## 🎯 Next Steps
|
|
|
|
1. **Add Shared Package** (optional):
|
|
|
|
```bash
|
|
mkdir packages/shared
|
|
# Create package.json for shared utilities/types
|
|
```
|
|
|
|
2. **Add Tests**:
|
|
|
|
```bash
|
|
pnpm --filter @repo/server add -D vitest
|
|
pnpm --filter @repo/frontend add -D vitest
|
|
```
|
|
|
|
3. **CI/CD**:
|
|
- Use `pnpm install --frozen-lockfile` in CI
|
|
- Run `pnpm build:all` for deployment
|
|
- Cache `node_modules` and `.pnpm-store`
|
|
|
|
## 📚 Learn More
|
|
|
|
- [pnpm Workspaces](https://pnpm.io/workspaces)
|
|
- [tRPC Documentation](https://trpc.io)
|
|
- [TaylorDB](https://taylordb.io)
|
|
- [Monorepo Handbook](https://monorepo.tools)
|
|
|
|
## 📄 License
|
|
|
|
MIT - Use freely for any project!
|
|
|
|
---
|
|
|
|
**Built with ❤️ for AI-assisted development platforms**
|