{"id":34946451,"url":"https://github.com/dwarvesf/mvp-template","last_synced_at":"2026-05-19T21:34:36.652Z","repository":{"id":312016939,"uuid":"1045343693","full_name":"dwarvesf/mvp-template","owner":"dwarvesf","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-29T16:25:51.000Z","size":993,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-28T07:49:05.345Z","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/dwarvesf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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}},"created_at":"2025-08-27T02:45:16.000Z","updated_at":"2025-08-29T16:25:54.000Z","dependencies_parsed_at":"2025-08-28T09:38:49.378Z","dependency_job_id":"7ffacd2e-811a-46f0-a6a6-65f9b96bebf7","html_url":"https://github.com/dwarvesf/mvp-template","commit_stats":null,"previous_names":["dwarvesf/mvp-template"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/dwarvesf/mvp-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwarvesf%2Fmvp-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwarvesf%2Fmvp-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwarvesf%2Fmvp-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwarvesf%2Fmvp-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dwarvesf","download_url":"https://codeload.github.com/dwarvesf/mvp-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwarvesf%2Fmvp-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33233740,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-19T15:49:41.270Z","status":"ssl_error","status_checked_at":"2026-05-19T15:49:22.917Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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":[],"created_at":"2025-12-26T20:15:34.023Z","updated_at":"2026-05-19T21:34:36.646Z","avatar_url":"https://github.com/dwarvesf.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MVP Template\n\nA modern, full-stack application template built with Next.js, NestJS, and TypeScript. Perfect for rapidly building MVPs and production-ready applications with enterprise-grade authentication and type-safe APIs.\n\n## 🚀 Features\n\n- **Frontend**: Next.js 14 with App Router, Tailwind CSS, React Query\n- **Backend**: NestJS with Swagger/OpenAPI documentation\n- **Database**: PostgreSQL with Prisma ORM\n- **Authentication**: NextAuth with GitHub OAuth, email/password, and password recovery\n- **Type Safety**: Auto-generated TypeScript client from OpenAPI specs\n- **Email**: Resend integration with React Email templates\n- **Testing**: Vitest (frontend) + Jest (backend)\n- **Code Quality**: ESLint, Prettier, Husky, Commitlint\n- **Development**: Hot reload, Docker Compose, pnpm workspaces\n\n## 📋 Prerequisites\n\n- Node.js 18+\n- pnpm 8+\n- Docker \u0026 Docker Compose\n\n## 🛠️ Quick Start\n\n### Option 1: One-Command Setup (Recommended)\n\n```bash\ngit clone \u003cyour-repo-url\u003e\ncd mvp-template\nmake setup\nmake dev  # Start development servers\n```\n\nThe `make setup` command will:\n\n- ✅ Install all dependencies\n- ✅ Copy environment files with working defaults\n- ✅ Start PostgreSQL database in Docker\n- ✅ Run database migrations\n- ✅ Seed with default user\n- ✅ Ready to develop immediately!\n\n### Option 2: Manual Setup\n\n#### 1. Clone and Install\n\n```bash\ngit clone \u003cyour-repo-url\u003e\ncd mvp-template\npnpm install\n```\n\n#### 2. Environment Setup\n\nCopy environment files and configure:\n\n```bash\n# API environment\ncp apps/api/.env.example apps/api/.env\n# Web environment\ncp apps/web/.env.example apps/web/.env.local\n```\n\n**Environment variables (with working defaults):**\n\n#### API (.env)\n\n```env\nDATABASE_URL=postgresql://postgres:postgres@localhost:35434/mvp_template\nJWT_SECRET=mvp-template-dev-secret-key-change-in-production  # ✅ Default provided\nPORT=4000\nRESEND_API_KEY=  # Optional - for email functionality\nEMAIL_FROM=noreply@mvp-template.local  # ✅ Default provided\n```\n\n#### Web (.env.local)\n\n```env\nNEXT_PUBLIC_API_URL=http://localhost:4000  # ✅ Default provided\nNEXTAUTH_SECRET=mvp-template-nextauth-dev-secret-change-in-production  # ✅ Default provided\nNEXTAUTH_URL=http://localhost:3000  # ✅ Default provided\nGITHUB_ID=  # Optional - for GitHub OAuth\nGITHUB_SECRET=  # Optional - for GitHub OAuth\nRESEND_API_KEY=  # Optional - for email functionality\nEMAIL_FROM=noreply@mvp-template.local  # ✅ Default provided\n```\n\n\u003e 💡 **Ready to code!** All required values have defaults. Optional secrets can be added later.\n\n#### 3. Database Setup\n\n```bash\n# Start PostgreSQL\nmake db-up\n\n# Run migrations\nmake db-migrate\n\n# Seed with default user\nmake db-seed\n```\n\n#### 4. Start Development\n\n```bash\n# Start both frontend and backend\nmake dev\n```\n\n\u003e 💡 **Tip**: Use `make setup` instead of steps 1-4 for automatic setup!\n\nYour applications will be available at:\n\n- **Frontend**: http://localhost:3000\n- **Backend API**: http://localhost:4000\n- **API Documentation**: http://localhost:4000/docs\n\n### 5. Default Login\n\nUse the pre-seeded user to test authentication:\n\n- **Email**: mvp@example.com\n- **Password**: Pwd123!\n\n## ⚙️ Optional Configuration\n\nThe template works out-of-the-box, but you can enhance it by adding these optional services:\n\n### GitHub OAuth (Optional)\n\n1. Create GitHub OAuth App at https://github.com/settings/applications/new\n2. Set callback URL: `http://localhost:3000/api/auth/callback/github`\n3. Add to `apps/web/.env.local`:\n   ```env\n   GITHUB_ID=your_github_client_id\n   GITHUB_SECRET=your_github_client_secret\n   ```\n\n### Email Service (Optional)\n\n1. Sign up at https://resend.com\n2. Get your API key\n3. Add to both `.env` files:\n   ```env\n   RESEND_API_KEY=your_resend_api_key\n   EMAIL_FROM=your-verified@domain.com\n   ```\n\n### Production Secrets\n\nBefore deploying to production, update these in your `.env` files:\n\n```env\n# API\nJWT_SECRET=your-secure-jwt-secret-here\n\n# Web\nNEXTAUTH_SECRET=your-secure-nextauth-secret-here\n```\n\n## 📁 Project Structure\n\n```\nmvp-template/\n├── apps/\n│   ├── api/              # NestJS backend\n│   │   ├── src/\n│   │   ├── prisma/\n│   │   └── docker-compose.yml\n│   └── web/              # Next.js frontend\n│       ├── src/\n│       └── public/\n├── packages/\n│   ├── api-client/       # Generated API client\n│   ├── shared/           # Shared types, constants, utilities\n│   └── config/           # Shared configurations\n├── tools/\n│   └── codegen/          # Code generation configs\n├── Makefile              # Development commands\n└── pnpm-workspace.yaml   # Workspace configuration\n```\n\n## 🛠️ Available Commands\n\n```bash\n# Setup\nmake setup          # Complete initial setup (recommended for new projects)\n\n# Development\nmake dev            # Run both apps in parallel\n\n# Building\nmake build          # Build all apps for production\npnpm --filter api build     # Build API only\npnpm --filter web build     # Build web app only\n\n# Testing \u0026 Quality\nmake test           # Run all tests\nmake lint           # Run ESLint\nmake format         # Format code with Prettier\npnpm typecheck      # TypeScript type checking\n\n# Database\nmake db-up          # Start PostgreSQL container\nmake db-migrate     # Run Prisma migrations\nmake db-seed        # Seed with default data\n\n# Code Generation\nmake codegen        # Generate API client from OpenAPI\n\n# Individual Development\npnpm --filter api dev       # Run API only\npnpm --filter web dev       # Run web only\npnpm --filter api prisma:migrate  # Run migrations\n```\n\n## 🔧 GitHub OAuth Setup\n\n1. Create GitHub OAuth App at https://github.com/settings/applications/new\n2. Set callback URL: `http://localhost:3000/api/auth/callback/github`\n3. Add `GITHUB_ID` and `GITHUB_SECRET` to your `.env.local`\n\n## 📧 Email Setup (Optional)\n\n1. Sign up at https://resend.com\n2. Get your API key\n3. Add `RESEND_API_KEY` to both `.env` files\n4. Configure `EMAIL_FROM` with your verified domain\n\n## 🏗️ Architecture\n\n### Shared Package System\n\nThe `@mvp-template/shared` package provides common utilities, types, and constants shared between frontend and backend:\n\n```typescript\n// Types and validation schemas\nimport { User, LoginRequest, CreateUserSchema } from '@mvp-template/shared';\n\n// Constants (API endpoints, validation rules, error messages)\nimport { API_ENDPOINTS, VALIDATION_RULES, ERROR_MESSAGES } from '@mvp-template/shared';\n\n// Utilities (validation, formatting, common helpers)\nimport { isValidEmail, formatDate, debounce } from '@mvp-template/shared';\n```\n\n**Benefits:**\n\n- **Type Safety**: API and frontend stay in sync automatically\n- **DRY Code**: Shared validation logic, constants, and utilities\n- **Consistency**: Same error messages and formats across the stack\n- **Developer Experience**: IntelliSense works across all packages\n\n### API Client Generation\n\nThe project uses [Orval](https://orval.dev/) to generate type-safe React Query hooks from the NestJS OpenAPI specification:\n\n1. Start the API server\n2. Run `make codegen`\n3. Import generated hooks: `import { useAuthMe } from '@mvp-template/api-client'`\n\n### Authentication Flow\n\nThe template provides a complete authentication system with multiple flows:\n\n#### Available Authentication Methods\n\n- **GitHub OAuth**: One-click social login via NextAuth\n- **Email/Password**: Traditional credentials with registration and login\n- **Password Recovery**: Complete forgot/reset password flow\n\n#### Authentication Pages\n\n- `/auth/signin` - Login with GitHub OAuth or email/password\n- `/auth/signup` - User registration with email verification\n- `/auth/forgot-password` - Request password reset\n- `/auth/reset-password` - Set new password with token\n- `/dashboard` - Protected dashboard page\n\n#### Password Reset Flow\n\n1. User enters email on forgot password page\n2. Backend generates secure reset token (1 hour expiry)\n3. Reset link logged to console (dev mode) or sent via email (production)\n4. User clicks reset link to set new password\n5. Token validated and password updated securely\n\n#### Technical Implementation\n\n- **JWT Tokens**: Stored in NextAuth session, automatically added to API requests\n- **Password Hashing**: bcrypt with salt rounds for secure storage\n- **Token Security**: Cryptographically secure random tokens for password reset\n- **Session Management**: NextAuth handles session persistence and refresh\n\n### Database\n\n- **ORM**: Prisma with PostgreSQL\n- **Migrations**: Version controlled with Prisma Migrate\n- **Seeding**: Default user and sample data\n\n## 🧪 Testing\n\n```bash\n# Run all tests\nmake test\n\n# Run specific test suites\npnpm --filter web test     # Frontend tests (Vitest)\npnpm --filter api test     # Backend tests (Jest)\n```\n\n## 🔨 Building for Production\n\n### Build All Applications\n\n```bash\n# Build everything (API + Web)\nmake build\n\n# Or use pnpm directly\npnpm build\n```\n\n### Build Individual Applications\n\n```bash\n# Build API only\npnpm --filter api build\n\n# Build web app only\npnpm --filter web build\n\n# Build shared package\npnpm --filter @mvp-template/shared build\n```\n\n### Build Output\n\n- **API**: Compiled JavaScript in `apps/api/dist/`\n- **Web**: Static files and server bundle in `apps/web/.next/`\n- **Shared**: Compiled types and declarations in `packages/shared/dist/`\n\n### Production Environment Setup\n\n1. **Environment Variables**: Update `.env` files with production values\n2. **Database**: Run migrations on production database\n3. **Build**: Run `make build` to compile all applications\n4. **Deploy**: Upload build artifacts to your hosting platform\n\n## 📝 Code Generation Workflow\n\n1. Make changes to NestJS controllers/DTOs\n2. Ensure API is running (`pnpm --filter api dev`)\n3. Generate client: `make codegen`\n4. Use new hooks in frontend components\n\n## 🔄 Working with Shared Code\n\n### Adding New Shared Types\n\n1. **Define types**: Add to `packages/shared/src/types/`\n2. **Add constants**: Update `packages/shared/src/constants/`\n3. **Create utilities**: Add to `packages/shared/src/utils/`\n4. **Export**: Update index files to make them available\n5. **Use**: Import in both web and API apps\n\n### Example: Adding a Post Feature\n\n```typescript\n// 1. Add types (packages/shared/src/types/post.ts)\nexport interface Post {\n  id: string;\n  title: string;\n  content: string;\n  authorId: string;\n  createdAt: Date;\n}\n\nexport const CreatePostSchema = z.object({\n  title: z.string().min(1).max(100),\n  content: z.string().min(10),\n});\n\n// 2. Add API endpoints (packages/shared/src/constants/index.ts)\nexport const API_ENDPOINTS = {\n  // ... existing endpoints\n  POSTS: {\n    BASE: '/posts',\n    CREATE: '/posts',\n    BY_ID: '/posts/:id',\n  },\n} as const;\n\n// 3. Use in API (apps/api/src/posts/posts.dto.ts)\nimport { CreatePostSchema } from '@mvp-template/shared';\n\nexport class CreatePostDto implements z.infer\u003ctypeof CreatePostSchema\u003e {\n  @IsString()\n  @Length(1, 100)\n  title: string;\n\n  @IsString()\n  @MinLength(10)\n  content: string;\n}\n\n// 4. Use in web (apps/web/src/lib/api/posts.ts)\nimport { CreatePostSchema, API_ENDPOINTS } from '@mvp-template/shared';\n\nexport const validatePost = (data: unknown) =\u003e {\n  return CreatePostSchema.safeParse(data);\n};\n```\n\n### Benefits of This Approach\n\n- **Refactoring Safety**: Change a type once, get compile errors everywhere it's used\n- **Team Productivity**: New developers learn patterns once\n- **API Consistency**: Frontend and backend can't drift apart\n- **Testing**: Shared validation logic can be tested once\n\n## 🚀 Deployment\n\nThe template is ready for deployment on platforms like:\n\n- **Frontend**: Vercel, Netlify\n- **Backend**: Railway, Render, AWS\n- **Database**: Supabase, PlanetScale, AWS RDS\n\nUpdate environment variables for production and modify OAuth callback URLs accordingly.\n\n## 🤝 Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for development guidelines.\n\n## 📄 License\n\nMIT License - see [LICENSE](./LICENSE) file for details.\n\n## 💡 Built With\n\n- [Next.js](https://nextjs.org/) - React framework\n- [NestJS](https://nestjs.com/) - Node.js framework\n- [Prisma](https://prisma.io/) - Database ORM\n- [NextAuth](https://next-auth.js.org/) - Authentication\n- [React Query](https://tanstack.com/query) - Server state management\n- [Tailwind CSS](https://tailwindcss.com/) - Styling\n- [Orval](https://orval.dev/) - API client generation\n- [Resend](https://resend.com/) - Email delivery\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdwarvesf%2Fmvp-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdwarvesf%2Fmvp-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdwarvesf%2Fmvp-template/lists"}