{"id":26462943,"url":"https://github.com/kryptobaseddev/tanstack-forge-starter","last_synced_at":"2026-04-11T14:02:15.451Z","repository":{"id":283005059,"uuid":"950189982","full_name":"kryptobaseddev/tanstack-forge-starter","owner":"kryptobaseddev","description":"Modern full-stack starter kit built with TanStack suite (Router, Query, Form, Table), tRPC, Prisma, MongoDB, and Shadcn UI. Features type-safe APIs, file-based routing, and development mode authentication.","archived":false,"fork":false,"pushed_at":"2025-03-18T19:45:39.000Z","size":1142,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-03T16:31:32.430Z","etag":null,"topics":["authentication","clerk","full-stack","mongodb","prisma","react","shadcn","starter","tailwindcss","tanstack","trpc","typescript","vite"],"latest_commit_sha":null,"homepage":"https://tanstack-forge-starter.vercel.app/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kryptobaseddev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-03-17T19:13:26.000Z","updated_at":"2025-10-11T16:54:01.000Z","dependencies_parsed_at":null,"dependency_job_id":"20e5c66c-5c26-4a70-ae81-ab8bc65f3102","html_url":"https://github.com/kryptobaseddev/tanstack-forge-starter","commit_stats":null,"previous_names":["kryptobaseddev/tanstack-forge-starter"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kryptobaseddev/tanstack-forge-starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kryptobaseddev%2Ftanstack-forge-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kryptobaseddev%2Ftanstack-forge-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kryptobaseddev%2Ftanstack-forge-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kryptobaseddev%2Ftanstack-forge-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kryptobaseddev","download_url":"https://codeload.github.com/kryptobaseddev/tanstack-forge-starter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kryptobaseddev%2Ftanstack-forge-starter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31682955,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-11T13:07:20.380Z","status":"ssl_error","status_checked_at":"2026-04-11T13:06:47.903Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["authentication","clerk","full-stack","mongodb","prisma","react","shadcn","starter","tailwindcss","tanstack","trpc","typescript","vite"],"created_at":"2025-03-19T06:38:48.750Z","updated_at":"2026-04-11T14:02:15.446Z","avatar_url":"https://github.com/kryptobaseddev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TanStackForge\n\nA modern, full-stack starter kit built on the TanStack suite, combining type-safe technologies for an exceptional developer experience.\n\nDemo of app and UI here: **[TanStackForge Demo](https://tanstack-forge-starter.vercel.app/)**\n\n## ✨ Features\n\n- 🚦 **[TanStack Router](https://tanstack.com/router)** - Type-safe file-based routing with loaders and actions\n- 🔄 **[TanStack Query](https://tanstack.com/query)** - Data fetching and caching\n- 📝 **[TanStack Form](https://tanstack.com/form)** - Powerful form management \n- 📊 **[TanStack Table](https://tanstack.com/table)** - Headless UI for building data tables\n- 🔒 **[Clerk](https://clerk.com/docs)** - Modern authentication with development mode support\n- 🔌 **[tRPC](https://trpc.io/docs)** - End-to-end type-safe APIs\n- 💾 **[Prisma ORM](https://www.prisma.io/docs/orm)** with **MongoDB** - Type-safe database access\n- 🎨 **[Shadcn UI](https://ui.shadcn.com/docs)** with **[Tailwind CSS](https://tailwindcss.com/)** - Beautiful UI components\n- ⚡ **[Vite](https://v5.vite.dev/guide)** - Lightning fast development\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n- [Node.js](https://nodejs.org/) (v18 or higher)\n- [pnpm](https://pnpm.io/) (recommended) or npm/yarn\n- MongoDB instance (see [Database Setup](#database-setup))\n- Clerk account (see [Authentication Setup](#authentication-setup))\n\n### Installation\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/yourusername/tanstack-forge.git\ncd tanstack-forge\n```\n\n2. Install dependencies:\n\n```bash\npnpm install\n```\n\n3. Set up environment variables by creating a `.env` file in the root directory:\n\n```env\n# Database\nDATABASE_URL=\"mongodb://mongo:\u003cmongokey\u003e@metro.proxy.rlwy.net:53250\"\n\n# Clerk Authentication\nVITE_CLERK_PUBLISHABLE_KEY=pk_test_********************\nCLERK_SECRET_KEY=sk_test_********************\n\n# Development Mode true bypasses Clerk authentication check and uses devAuth\nVITE_DEV_MODE=true\n```\n\n4. Push the database schema to your MongoDB instance:\n\n```bash\npnpm prisma db push\n```\n\n5. Start the development server:\n\n```bash\npnpm dev\n```\n\n6. Open [http://localhost:5173](http://localhost:5173) in your browser.\n\n## 🔧 Project Structure\n\n```\ntanstack-forge/\n├── prisma/                # Database schema and migrations\n│   └── schema.prisma     # Prisma schema definition\n├── public/               # Static assets\n├── src/\n│   ├── api/              # External API routes\n│   ├── components/       # UI components\n│   │   ├── auth/        # Authentication components\n│   │   ├── common/      # Shared components\n│   │   ├── features/    # Feature-specific components\n│   │   │   ├── posts/   # Post feature components\n│   │   │   ├── users/   # User feature components\n│   │   │   └── ...      # Other feature components\n│   │   ├── layouts/     # Layout components\n│   │   └── ui/          # Shadcn UI components\n│   ├── hooks/           # Custom React hooks\n│   ├── lib/             # Utility functions and constants\n│   │   ├── constants.ts # Application constants\n│   │   ├── prisma.ts    # Prisma client\n│   │   ├── trpc.ts      # tRPC setup\n│   │   └── utils.ts     # Utility functions\n│   ├── pages/           # Page components\n│   │   ├── about.tsx    # About page route\n│   │   ├── examples.tsx    # Examples page route\n│   │   └── features.tsx    # Features page route\n│   ├── providers/       # React context providers\n│   │   ├── auth-provider.tsx    # Authentication provider\n│   │   └── trpc-provider.tsx    # tRPC provider\n│   ├── routes/          # File-based routing\n│   │   ├── __root.tsx   # Root layout and providers\n│   │   ├── index.tsx    # Home page route (used for the features page in this starter)\n│   │   ├── about.tsx    # About page route\n│   │   └── examples.tsx    # Examples page route\n│   ├── server/          # Backend logic\n│   │   ├── context.ts   # tRPC context\n│   │   ├── router.ts    # Base router setup\n│   │   └── routers/     # Route handlers\n│   │       ├── _app.ts  # Root router\n│   │       ├── post.router.ts\n│   │       └── user.router.ts\n│   ├── types/           # TypeScript type definitions\n│   │   ├── api.types.ts       # API types\n│   │   ├── auth.types.ts      # Authentication types\n│   │   ├── common.types.ts    # Common types\n│   │   ├── form.types.ts      # Form types\n│   │   ├── post.types.ts      # Post types\n│   │   ├── router.types.ts    # Router types\n│   │   ├── table.types.ts     # Table types\n│   │   └── user.types.ts      # User types\n│   ├── index.css        # Global CSS and Tailwind imports\n│   ├── routeTree.gen.ts # Route tree generator (generated from TanStack Router)\n│   └── main.tsx         # Application entry point\n├── .env                 # Environment variables\n├── .env.example         # Example environment variables\n├── .gitignore           # Git ignore rules\n├── index.html           # HTML template\n├── package.json         # Project dependencies\n├── tailwind.config.js   # Tailwind configuration\n├── tsconfig.json        # TypeScript configuration\n└── vite.config.ts      # Vite configuration\n```\n\n## 🎨 Color Scheme and Styling\n\nTanStackForge uses a sophisticated color system defined in `src/index.css`:\n\n```css\n:root {\n  /* Main brand colors */\n  --color-primary: 263.4 70% 50.4%;    /* Purple */\n  --color-secondary: 215 27.9% 16.9%;  /* Dark blue-gray */\n  --color-accent: 215 27.9% 16.9%;     /* Accent color */\n  \n  /* Semantic colors */\n  --color-success: 142 72% 29%;    /* Green */\n  --color-warning: 38 92% 50%;     /* Yellow/Amber */\n  --color-error: 0 62.8% 30.6%;    /* Red */\n  --color-info: 199 89% 48%;       /* Blue */\n  \n  /* Base colors - Dark theme by default */\n  --background: 224 71.4% 4.1%;\n  --foreground: 210 20% 98%;\n  \n  /* Component colors */\n  --card: 224 71.4% 4.1%;\n  --card-foreground: 210 20% 98%;\n  --popover: 224 71.4% 4.1%;\n  --popover-foreground: 210 20% 98%;\n  /* ... and more component-specific colors */\n}\n```\n\n### Theme Features:\n\n- **HSL Color Format**: All colors are defined in HSL format for easy manipulation\n- **CSS Variables**: Enables dynamic theme switching and component-specific styling\n- **Semantic Colors**: Clear naming conventions for different UI states\n- **Dark Mode Ready**: Built-in dark mode support\n- **Component-Specific Colors**: Dedicated variables for different UI components\n\n## 🛣️ Routing with TanStack Router\n\nTanStackForge uses TanStack Router's file-based routing system:\n\n```\nsrc/routes/\n├── __root.tsx           # Root layout and providers\n├── index.tsx           # Home page (/)\n├── about.tsx           # About page (/about)\n└── examples/\n    └── index.tsx       # Examples page (/examples)\n```\n\n### Route Configuration\n\nRoutes are automatically generated from the file structure:\n\n```typescript\n// src/routes/__root.tsx\nexport const Route = createRootRoute({\n  component: () =\u003e (\n    \u003cAuthContextProvider\u003e\n      \u003cRootLayout\u003e\n        \u003cOutlet /\u003e\n      \u003c/RootLayout\u003e\n    \u003c/AuthContextProvider\u003e\n  ),\n});\n\n// src/routes/index.tsx\nexport const Route = createFileRoute('/')({\n  component: HomePage,\n});\n```\n\n## 🔐 Authentication\n\nTanStackForge supports two authentication modes:\n\n### Development Mode\n\nWhen `VITE_DEV_MODE=true`:\n- Uses a simplified authentication flow\n- No external auth service required\n- Perfect for development and testing\n\n### Production Mode\n\nWhen `VITE_DEV_MODE=false`:\n- Uses Clerk for secure authentication\n- Supports email/password and social logins\n- Full user management features\n\nWhen enabled, development mode:\n\n- Shows debugging information and devtools\n- Enables more detailed error messages\n- Makes tRPC panel accessible\n- Displays TanStack Query and Router devtools\n- Bypasses certain authentication checks for faster development\n\nSet to `false` for production-like behavior during development.\n\n## 🗄️ API Structure\n\nThe backend API is organized using tRPC routers:\n\n```\nsrc/server/\n├── context.ts          # Request context\n├── router.ts           # Base router setup\n└── routers/\n    ├── _app.ts        # Root router\n    ├── post.router.ts # Post-related endpoints\n    └── user.router.ts # User-related endpoints\n```\n\n### Example Router:\n\n```typescript\n// src/server/routers/user.router.ts\nexport const userRouter = router({\n  list: publicProcedure\n    .query(({ ctx }) =\u003e ctx.prisma.user.findMany()),\n  \n  byId: protectedProcedure\n    .input(z.string())\n    .query(({ ctx, input }) =\u003e ctx.prisma.user.findUnique({\n      where: { id: input }\n    })),\n});\n```\n\n## 🔌 tRPC Integration\n\nTanStackForge provides a seamless integration between tRPC, TanStack Router, and TanStack Query for end-to-end type safety.\n\n### Base Setup\n```typescript\n// src/server/router.ts\nconst t = initTRPC.context\u003cContext\u003e().create();\nexport const router = t.router;\nexport const publicProcedure = t.procedure;\nexport const protectedProcedure = t.procedure.use(({ ctx, next }) =\u003e {\n  if (!ctx.auth?.userId) {\n    throw new TRPCError({ code: 'UNAUTHORIZED' });\n  }\n  return next({\n    ctx: { auth: ctx.auth },\n  });\n});\n```\n\n### Router Implementation\n```typescript\n// src/server/routers/user.router.ts\nexport const userRouter = router({\n  me: protectedProcedure\n    .query(({ ctx }) =\u003e ctx.prisma.user.findUnique({\n      where: { clerkId: ctx.auth.userId },\n    })),\n\n  updateProfile: protectedProcedure\n    .input(z.object({\n      name: z.string().min(2).max(50).optional(),\n      role: z.nativeEnum(UserRole).optional(),\n    }))\n    .mutation(({ ctx, input }) =\u003e ctx.prisma.user.update({\n      where: { clerkId: ctx.auth.userId },\n      data: input,\n    })),\n});\n```\n\n### TanStack Router Integration\n```typescript\n// src/routes/user.tsx\nexport const Route = createFileRoute('/user')({\n  loader: () =\u003e trpc.user.me.ensureData(),\n  component: UserProfile,\n});\n```\n\n### TanStack Query Usage\n```typescript\n// In your React components\nfunction UserProfile() {\n  // Automatic type inference from your tRPC router\n  const { data: user } = api.user.me.useQuery();\n  const utils = api.useUtils();\n  \n  const { mutate: updateProfile } = api.user.updateProfile.useMutation({\n    onSuccess: () =\u003e {\n      // Invalidate and refetch\n      utils.user.me.invalidate();\n    },\n  });\n\n  return (/* ... */);\n}\n```\n\n## 📝 Type System\n\nTanStackForge emphasizes type safety across the entire stack:\n\n### Constants and Enums\n\nStore application constants and enums in `src/lib/constants.ts`:\n\n```typescript\n// src/lib/constants.ts\nexport const APP_NAME = \"TanStackForge\";\n\nexport enum UserRole {\n  ADMIN = \"ADMIN\",\n  USER = \"USER\",\n}\n\nexport enum UserStatus {\n  ACTIVE = \"ACTIVE\",\n  INACTIVE = \"INACTIVE\",\n}\n\n// Feature flags\nexport const FEATURES = {\n  DARK_MODE: true,\n  ANALYTICS: false,\n};\n```\n\n### Type Definitions\n\nStore shared type definitions in the `src/types` folder:\n\n```typescript\n// src/types/common.ts\nexport type Status = 'idle' | 'loading' | 'success' | 'error';\n\nexport interface PaginationParams {\n  page: number;\n  limit: number;\n}\n\nexport interface ApiResponse\u003cT\u003e {\n  data: T;\n  status: Status;\n  error?: string;\n}\n```\n\n### End-to-End Type Safety\n\nTanStackForge provides end-to-end type safety through:\n\n1. **Prisma Schema to TypeScript**:\n   ```prisma\n   // prisma/schema.prisma\n   model User {\n     id        String   @id @default(auto()) @map(\"_id\") @db.ObjectId\n     clerkId   String   @unique\n     name      String?\n     email     String   @unique\n     role      String   @default(\"USER\")\n     status    String   @default(\"ACTIVE\")\n     createdAt DateTime @default(now())\n     updatedAt DateTime @updatedAt\n   }\n   ```\n\n2. **tRPC with Zod Validation**:\n   ```typescript\n   // src/server/routers/user.router.ts\n   const userUpdateSchema = z.object({\n     name: z.string().min(2).max(50).optional(),\n     role: z.nativeEnum(UserRole).optional(),\n   });\n\n   export const userRouter = router({\n     updateProfile: protectedProcedure\n       .input(userUpdateSchema)\n       .mutation(async ({ ctx, input }) =\u003e {\n         return ctx.prisma.user.update({\n           where: { clerkId: ctx.auth.userId },\n           data: input,\n         });\n       }),\n   });\n   ```\n\n## 🔄 Data Flow\n\nTanStackForge implements a clean and type-safe data flow:\n\n1. **Database Layer** (Prisma with MongoDB)\n   - Models defined in `prisma/schema.prisma`\n   - Type-safe database queries via Prisma Client\n\n2. **API Layer** (tRPC)\n   - Route handlers in `src/server/routers/`\n   - Input validation with Zod\n   - Business logic processing\n   - Type-safe responses\n\n3. **Client Layer** (TanStack Query + tRPC)\n   - Auto-generated hooks from tRPC procedures\n   - Automatic cache management\n   - Optimistic updates\n   - Type-safe mutations\n\n4. **UI Layer** (React + Shadcn UI)\n   - Type-safe props and state\n   - Strongly typed event handlers\n   - Component composition with TypeScript\n\n## 🧪 Testing\n\nTanStackForge includes a comprehensive testing setup:\n\n### Unit Tests\n```typescript\n// src/__tests__/utils.test.ts\nimport { describe, it, expect } from 'vitest';\nimport { formatDate } from '@/lib/utils';\n\ndescribe('utils', () =\u003e {\n  it('formats date correctly', () =\u003e {\n    const date = new Date('2024-01-01');\n    expect(formatDate(date)).toBe('Jan 1, 2024');\n  });\n});\n```\n\n### Component Tests\n```typescript\n// src/__tests__/components/Button.test.tsx\nimport { render, screen } from '@testing-library/react';\nimport { Button } from '@/components/ui/button';\n\ndescribe('Button', () =\u003e {\n  it('renders correctly', () =\u003e {\n    render(\u003cButton\u003eClick me\u003c/Button\u003e);\n    expect(screen.getByText('Click me')).toBeInTheDocument();\n  });\n});\n```\n\n### API Tests\n```typescript\n// src/__tests__/api/user.test.ts\nimport { createInnerTRPCContext } from '@/server/context';\nimport { appRouter } from '@/server/routers/_app';\n\ndescribe('User API', () =\u003e {\n  it('returns user profile', async () =\u003e {\n    const ctx = createInnerTRPCContext({ auth: mockAuth });\n    const caller = appRouter.createCaller(ctx);\n    const result = await caller.user.me();\n    expect(result).toHaveProperty('id');\n  });\n});\n```\n\nRun tests with:\n```bash\npnpm test        # Run all tests\npnpm test:watch  # Run tests in watch mode\npnpm test:ui     # Run tests with UI\npnpm test:coverage # Run tests with coverage report\n```\n\n## 📚 Learn More\n\n- [TanStack Router Documentation](https://tanstack.com/router/latest/docs/framework/react/overview)\n- [TanStack Query Documentation](https://tanstack.com/query/latest/docs/react/overview)\n- [tRPC Documentation](https://trpc.io/docs)\n- [Prisma Documentation](https://www.prisma.io/docs)\n- [Clerk Documentation](https://clerk.com/docs)\n- [Shadcn UI Documentation](https://ui.shadcn.com/docs)\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkryptobaseddev%2Ftanstack-forge-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkryptobaseddev%2Ftanstack-forge-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkryptobaseddev%2Ftanstack-forge-starter/lists"}