A full-stack demonstration of MongoDB integration with TanStack Start, featuring end-to-end type safety, serverless-optimized connection pooling, and modern React patterns.
- 🔒 End-to-end type safety from MongoDB → Server functions → React components
- 🚀 Serverless-optimized connection pooling (prevents connection exhaustion)
- ⚡ Optimistic updates with TanStack Query for instant UI feedback
- 🎯 Smart caching with stale-while-revalidate strategies
- 🎨 Modern UI with Shadcn components, Tailwind CSS 4, and dark/light/system themes
- 📦 No ORM - native MongoDB driver for full control and flexibility
- 🔄 Full CRUD operations with a complete todo app example
- TanStack Start - Full-stack React framework
- TanStack Router - Type-safe routing with SSR
- TanStack Query - Data fetching & caching
- MongoDB - Native driver, no ORM
- React - UI library
- TypeScript - Type safety
- Zod - Runtime validation
- Tailwind CSS - Styling
- Shadcn UI - Component library
- Node.js 22+ and pnpm installed
- MongoDB instance (local or MongoDB Atlas)
-
Clone and install:
git clone <your-repo-url> cd tanstack-start-mongodb pnpm install
-
Configure MongoDB:
cp .env.example .env
Edit
.envand set your MongoDB connection string:# For local MongoDB MONGODB_URI=mongodb://localhost:27017/tanstack-todos # Or for MongoDB Atlas MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/tanstack-todos
-
Start development server:
pnpm dev
src/
├── config/
│ └── mongodb.ts # Centralized MongoDB configuration
├── server/
│ ├── todos.ts # Server functions (CRUD operations)
│ ├── mongodb-status.ts # Connection status check
│ └── theme.ts # SSR theme detection
├── lib/
│ ├── mongodb.ts # Serverless-optimized connection singleton
│ ├── types.ts # Type definitions + Zod schemas
│ └── utils.ts # Utility functions
├── queries/
│ └── todos.ts # TanStack Query factories
├── hooks/
│ └── useTodos.ts # Custom hooks with optimistic updates
├── routes/
│ ├── __root.tsx # Root layout with devtools
│ ├── index.tsx # Landing page
│ └── todos.tsx # Todo demo page
├── components/
│ ├── TodoList.tsx # Main todo container
│ ├── TodoItem.tsx # Individual todo with actions
│ ├── AddTodoForm.tsx # Input form
│ └── ui/ # Shadcn UI components
└── integrations/
└── tanstack-query/ # Query client setup
# Development
pnpm dev # Start development server (port 3000)
pnpm build # Build for production
pnpm serve # Preview production build
# Code Quality
pnpm lint # Lint code with ESLint
pnpm format # Format code with Prettier
pnpm check # Format and fix all issues
# Database
pnpm init-db # Initialize MongoDB indexes
# UI Components
pnpx shadcn@latest add <component> # Add Shadcn componentsThis application uses a multi-branch deployment strategy with platform-specific configurations:
| Branch | Purpose | Platform |
|---|---|---|
main |
Base implementation | Generic serverless |
netlify |
Netlify deployment | Netlify |
cloudflare |
Basic Cloudflare deployment | Cloudflare Workers |
cloudflare-durable-objects |
Advanced Cloudflare deployment | Cloudflare Workers + Durable Objects |
-
Switch to netlify branch:
git checkout netlify
-
Install dependencies:
pnpm install
-
Deploy to Netlify:
pnpm netlify deploy --build
-
Set environment variables in Netlify:
MONGODB_URI- Your MongoDB connection string
Features:
- Uses
@netlify/vite-plugin-tanstack-start - Node.js 22+ runtime
- Official TanStack Start partner
-
Switch to cloudflare branch:
git checkout cloudflare
-
Install dependencies:
pnpm install
-
Deploy to Cloudflare:
pnpm build pnpm wrangler deploy
-
Set environment variables:
pnpm wrangler secret put MONGODB_URI
Features:
- Uses
@cloudflare/vite-plugin - Node.js compatibility v2
- Official TanStack Start partner
-
Switch to cloudflare-durable-objects branch:
git checkout cloudflare-durable-objects
-
Install dependencies:
pnpm install
-
Deploy with Durable Objects:
pnpm build pnpm wrangler deploy
-
Set environment variables:
pnpm wrangler secret put MONGODB_URI
Features:
- MongoDB connection managed via Durable Objects
- Better state persistence across Workers instances
- Custom server entry point
- Ideal for production Cloudflare deployments
The main branch supports deployment to:
- Vercel - Standard serverless deployment
- AWS Lambda - Standard serverless deployment
- Node.js hosting - Railway, Render, Fly.io, etc.
- Any platform with Node.js 22+ and MongoDB access
Set the MONGODB_URI environment variable in your platform's settings.
The application implements connection pooling best practices for serverless:
- Singleton pattern with global caching across function invocations
- Connection reuse to prevent connection exhaustion
- Promise caching for concurrent connection requests
- Optimized pool settings: maxPoolSize: 10, idle timeout: 5s
- User-friendly error handling for common MongoDB issues
See src/lib/mongodb.ts and src/config/mongodb.ts for implementation.
Uses TanStack Start's createServerFn for type-safe server operations:
// Automatic type inference from server to client
export const getTodos = createServerFn().handler(async () => {
const collection = await getTodosCollection()
return await collection.find({}).sort({ createdAt: -1 }).toArray()
})- Full TypeScript type safety
- Zod validation with
.inputValidator() - No HTTP overhead for internal calls
- Seamless client-server communication
All mutations implement optimistic updates for instant UI feedback:
// Update UI immediately, rollback on error
const { mutate } = useUpdateTodo()
mutate({ id: todo.id, completed: !todo.completed })- Instant UI updates before server confirmation
- Automatic rollback on errors
- Cache synchronization with
onSettled - Retry logic with exponential backoff
SSR-compatible theme support with zero flash:
- Dark, light, and system theme modes
- Theme stored in cookies for SSR consistency
- Blocking script prevents theme flash on page load
- Smooth transitions between themes
- TanStack Start Documentation
- TanStack Router Documentation
- TanStack Query Documentation
- MongoDB Node.js Driver
- Shadcn UI
See CLAUDE.md for detailed architecture documentation and development patterns.
MIT