{"id":31737863,"url":"https://github.com/codestackr/tanstack-start-mongodb","last_synced_at":"2025-10-09T09:45:16.089Z","repository":{"id":318697808,"uuid":"1072386128","full_name":"codeSTACKr/tanstack-start-mongodb","owner":"codeSTACKr","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-08T16:51:48.000Z","size":3722,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-08T18:45:27.342Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codeSTACKr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-08T16:41:30.000Z","updated_at":"2025-10-08T16:50:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/codeSTACKr/tanstack-start-mongodb","commit_stats":null,"previous_names":["codestackr/tanstack-start-mongodb"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/codeSTACKr/tanstack-start-mongodb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeSTACKr%2Ftanstack-start-mongodb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeSTACKr%2Ftanstack-start-mongodb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeSTACKr%2Ftanstack-start-mongodb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeSTACKr%2Ftanstack-start-mongodb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codeSTACKr","download_url":"https://codeload.github.com/codeSTACKr/tanstack-start-mongodb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeSTACKr%2Ftanstack-start-mongodb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001118,"owners_count":26083022,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-09T09:45:14.402Z","updated_at":"2025-10-09T09:45:16.082Z","avatar_url":"https://github.com/codeSTACKr.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MongoDB + TanStack Start Demo\n\nA full-stack demonstration of **MongoDB** integration with **TanStack Start**, featuring end-to-end type safety, serverless-optimized connection pooling, and modern React patterns.\n\n![TanStack Start + MongoDB](https://img.shields.io/badge/TanStack-Start-FF4154?style=flat-square) ![MongoDB](https://img.shields.io/badge/MongoDB-Native-47A248?style=flat-square) ![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178C6?style=flat-square)\n\n![Home Page Screenshot](public/screenshot.png)\n🔗 [Live Demo](https://tanstack-start-mongodb.netlify.app/)\n\n## ✨ Features\n\n- 🔒 **End-to-end type safety** from MongoDB → Server functions → React components\n- 🚀 **Serverless-optimized** connection pooling (prevents connection exhaustion)\n- ⚡ **Optimistic updates** with TanStack Query for instant UI feedback\n- 🎯 **Smart caching** with stale-while-revalidate strategies\n- 🎨 **Modern UI** with Shadcn components, Tailwind CSS 4, and dark/light/system themes\n- 📦 **No ORM** - native MongoDB driver for full control and flexibility\n- 🔄 **Full CRUD** operations with a complete todo app example\n\n## 🛠️ Tech Stack\n\n- **[TanStack Start](https://tanstack.com/start)** - Full-stack React framework\n- **[TanStack Router](https://tanstack.com/router)** - Type-safe routing with SSR\n- **[TanStack Query](https://tanstack.com/query)** - Data fetching \u0026 caching\n- **[MongoDB](https://www.mongodb.com/)** - Native driver, no ORM\n- **[React](https://react.dev/)** - UI library\n- **[TypeScript](https://www.typescriptlang.org/)** - Type safety\n- **[Zod](https://zod.dev/)** - Runtime validation\n- **[Tailwind CSS](https://tailwindcss.com/)** - Styling\n- **[Shadcn UI](https://ui.shadcn.com/)** - Component library\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Node.js** 22+ and **pnpm** installed\n- **MongoDB** instance (local or [MongoDB Atlas](https://account.mongodb.com/account/login/?utm_campaign=devrel\u0026utm_source=third-party-content\u0026utm_medium=cta\u0026utm_content=tanstack-start-todo-demo\u0026utm_term=jesse.hall))\n\n### Installation\n\n1. **Clone and install:**\n\n   ```bash\n   git clone \u003cyour-repo-url\u003e\n   cd tanstack-start-mongodb\n   pnpm install\n   ```\n\n2. **Configure MongoDB:**\n\n   ```bash\n   cp .env.example .env\n   ```\n\n   Edit `.env` and set your MongoDB connection string:\n\n   ```bash\n   # For local MongoDB\n   MONGODB_URI=mongodb://localhost:27017/tanstack-todos\n\n   # Or for MongoDB Atlas\n   MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/tanstack-todos\n   ```\n\n3. **Start development server:**\n\n   ```bash\n   pnpm dev\n   ```\n\n   Open [http://localhost:3000](http://localhost:3000)\n\n## 📁 Project Structure\n\n```\nsrc/\n├── config/\n│   └── mongodb.ts           # Centralized MongoDB configuration\n├── server/\n│   ├── todos.ts             # Server functions (CRUD operations)\n│   ├── mongodb-status.ts    # Connection status check\n│   └── theme.ts             # SSR theme detection\n├── lib/\n│   ├── mongodb.ts           # Serverless-optimized connection singleton\n│   ├── types.ts             # Type definitions + Zod schemas\n│   └── utils.ts             # Utility functions\n├── queries/\n│   └── todos.ts             # TanStack Query factories\n├── hooks/\n│   └── useTodos.ts          # Custom hooks with optimistic updates\n├── routes/\n│   ├── __root.tsx           # Root layout with devtools\n│   ├── index.tsx            # Landing page\n│   └── todos.tsx            # Todo demo page\n├── components/\n│   ├── TodoList.tsx         # Main todo container\n│   ├── TodoItem.tsx         # Individual todo with actions\n│   ├── AddTodoForm.tsx      # Input form\n│   └── ui/                  # Shadcn UI components\n└── integrations/\n    └── tanstack-query/      # Query client setup\n```\n\n## 📜 Available Scripts\n\n```bash\n# Development\npnpm dev              # Start development server (port 3000)\npnpm build            # Build for production\npnpm serve            # Preview production build\n\n# Code Quality\npnpm lint             # Lint code with ESLint\npnpm format           # Format code with Prettier\npnpm check            # Format and fix all issues\n\n# Database\npnpm init-db          # Initialize MongoDB indexes\n\n# UI Components\npnpx shadcn@latest add \u003ccomponent\u003e    # Add Shadcn components\n```\n\n## 🌐 Deployment\n\nThis application uses a **multi-branch deployment strategy** with platform-specific configurations:\n\n### Branch Structure\n\n| Branch | Purpose | Platform |\n|--------|---------|----------|\n| `main` | Base implementation | Generic serverless |\n| `netlify` | Netlify deployment | [Netlify](https://netlify.com) |\n| `cloudflare` | Basic Cloudflare deployment | [Cloudflare Workers](https://workers.cloudflare.com/) |\n| `cloudflare-durable-objects` | Advanced Cloudflare deployment | Cloudflare Workers + Durable Objects |\n\n### Deploying to Netlify\n\n1. **Switch to netlify branch:**\n   ```bash\n   git checkout netlify\n   ```\n\n2. **Install dependencies:**\n   ```bash\n   pnpm install\n   ```\n\n3. **Deploy to Netlify:**\n   ```bash\n   pnpm netlify deploy --build\n   ```\n\n4. **Set environment variables in Netlify:**\n   - `MONGODB_URI` - Your MongoDB connection string\n\n**Features:**\n- Uses `@netlify/vite-plugin-tanstack-start`\n- Node.js 22+ runtime\n- Official TanStack Start partner\n\n### Deploying to Cloudflare Workers\n\n#### Basic Deployment (`cloudflare` branch)\n\n1. **Switch to cloudflare branch:**\n   ```bash\n   git checkout cloudflare\n   ```\n\n2. **Install dependencies:**\n   ```bash\n   pnpm install\n   ```\n   \n3. **Deploy to Cloudflare:**\n   ```bash\n   pnpm build\n   pnpm wrangler deploy\n   ```\n\n4. **Set environment variables:**\n   ```bash\n   pnpm wrangler secret put MONGODB_URI\n   ```\n\n**Features:**\n- Uses `@cloudflare/vite-plugin`\n- Node.js compatibility v2\n- Official TanStack Start partner\n\n#### Advanced Deployment (`cloudflare-durable-objects` branch)\n\n1. **Switch to cloudflare-durable-objects branch:**\n   ```bash\n   git checkout cloudflare-durable-objects\n   ```\n\n2. **Install dependencies:**\n   ```bash\n   pnpm install\n   ```\n\n3. **Deploy with Durable Objects:**\n   ```bash\n   pnpm build\n   pnpm wrangler deploy\n   ```\n\n4. **Set environment variables:**\n   ```bash\n   pnpm wrangler secret put MONGODB_URI\n   ```\n\n**Features:**\n- MongoDB connection managed via Durable Objects\n- Better state persistence across Workers instances\n- Custom server entry point\n- Ideal for production Cloudflare deployments\n\n### Other Platforms\n\nThe `main` branch supports deployment to:\n\n- **[Vercel](https://vercel.com)** - Standard serverless deployment\n- **[AWS Lambda](https://aws.amazon.com/lambda/)** - Standard serverless deployment\n- **Node.js hosting** - Railway, Render, Fly.io, etc.\n- Any platform with Node.js 22+ and MongoDB access\n\nSet the `MONGODB_URI` environment variable in your platform's settings.\n\n## 🏗️ Architecture Highlights\n\n### Serverless-Optimized MongoDB Connection\n\nThe application implements connection pooling best practices for serverless:\n\n- **Singleton pattern** with global caching across function invocations\n- **Connection reuse** to prevent connection exhaustion\n- **Promise caching** for concurrent connection requests\n- **Optimized pool settings**: maxPoolSize: 10, idle timeout: 5s\n- **User-friendly error handling** for common MongoDB issues\n\nSee `src/lib/mongodb.ts` and `src/config/mongodb.ts` for implementation.\n\n### Type-Safe Server Functions\n\nUses TanStack Start's `createServerFn` for type-safe server operations:\n\n```typescript\n// Automatic type inference from server to client\nexport const getTodos = createServerFn().handler(async () =\u003e {\n  const collection = await getTodosCollection()\n  return await collection.find({}).sort({ createdAt: -1 }).toArray()\n})\n```\n\n- Full TypeScript type safety\n- Zod validation with `.inputValidator()`\n- No HTTP overhead for internal calls\n- Seamless client-server communication\n\n### Optimistic Updates with TanStack Query\n\nAll mutations implement optimistic updates for instant UI feedback:\n\n```typescript\n// Update UI immediately, rollback on error\nconst { mutate } = useUpdateTodo()\nmutate({ id: todo.id, completed: !todo.completed })\n```\n\n- Instant UI updates before server confirmation\n- Automatic rollback on errors\n- Cache synchronization with `onSettled`\n- Retry logic with exponential backoff\n\n### Theme System\n\nSSR-compatible theme support with zero flash:\n\n- Dark, light, and system theme modes\n- Theme stored in cookies for SSR consistency\n- Blocking script prevents theme flash on page load\n- Smooth transitions between themes\n\n## 📚 Learn More\n\n- [TanStack Start Documentation](https://tanstack.com/start)\n- [TanStack Router Documentation](https://tanstack.com/router)\n- [TanStack Query Documentation](https://tanstack.com/query)\n- [MongoDB Node.js Driver](https://www.mongodb.com/docs/drivers/node/current/?utm_campaign=devrel\u0026utm_source=third-party-content\u0026utm_medium=cta\u0026utm_content=tanstack-start-todo-demo\u0026utm_term=jesse.hall)\n- [Shadcn UI](https://ui.shadcn.com/)\n\n## 📝 Contributing\n\nSee `CLAUDE.md` for detailed architecture documentation and development patterns.\n\n## 📄 License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodestackr%2Ftanstack-start-mongodb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodestackr%2Ftanstack-start-mongodb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodestackr%2Ftanstack-start-mongodb/lists"}