{"id":31581031,"url":"https://github.com/lucasps136/baseclaudereactwebtemplate","last_synced_at":"2025-10-05T21:52:21.186Z","repository":{"id":315108532,"uuid":"1058128732","full_name":"lucasps136/baseClaudeReactWebtemplate","owner":"lucasps136","description":"This project is a starter template for building modern web applications using React together with Claude Code. It provides a quick and clean setup, so you can focus on writing features instead of boilerplate configuration :)","archived":false,"fork":false,"pushed_at":"2025-09-30T23:24:53.000Z","size":212,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-01T01:14:42.882Z","etag":null,"topics":["ai-code-generation","ai-coding","boilerplate","claude","claude-code","llm","mcp","mcp-servers","nextjs","react","shadcn-ui","supabase","tailwindcss","typescript","vibecoded","vibekit","web-template"],"latest_commit_sha":null,"homepage":"","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/lucasps136.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-09-16T16:55:39.000Z","updated_at":"2025-09-30T23:24:57.000Z","dependencies_parsed_at":"2025-09-16T20:03:23.783Z","dependency_job_id":"aef8da33-4f5a-4bbf-99cb-1bb5eb75bb18","html_url":"https://github.com/lucasps136/baseClaudeReactWebtemplate","commit_stats":null,"previous_names":["lucasps136/baseclaudereactwebtemplate"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/lucasps136/baseClaudeReactWebtemplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasps136%2FbaseClaudeReactWebtemplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasps136%2FbaseClaudeReactWebtemplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasps136%2FbaseClaudeReactWebtemplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasps136%2FbaseClaudeReactWebtemplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lucasps136","download_url":"https://codeload.github.com/lucasps136/baseClaudeReactWebtemplate/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasps136%2FbaseClaudeReactWebtemplate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278526242,"owners_count":26001325,"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-05T02:00:06.059Z","response_time":54,"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":["ai-code-generation","ai-coding","boilerplate","claude","claude-code","llm","mcp","mcp-servers","nextjs","react","shadcn-ui","supabase","tailwindcss","typescript","vibecoded","vibekit","web-template"],"created_at":"2025-10-05T21:52:20.284Z","updated_at":"2025-10-05T21:52:21.178Z","avatar_url":"https://github.com/lucasps136.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"This project is a starter template for building modern web applications using React together with Claude Code.\nIt provides a quick and clean setup, so you can focus on writing features instead of boilerplate configuration.\n\nFeatures\n\n⚡ Quick start: minimal configuration to get your app running fast.\n\n🛠 Claude Code integration: ready-to-use setup for experimenting with Claude's coding capabilities.\n\n🎨 React best practices: structured project with reusable components and clear organization.\n\n🚀 Extensible: easily adaptable for small prototypes or larger projects.\n\nUse cases\n\nKickstarting new React projects without wasting time on setup.\n\nPrototyping apps that leverage Claude Code for AI-assisted development.\n\nLearning how to integrate Claude into a modern React environment.\n\n# 🚀 Next.js SOLID Boilerplate\n\nModern Next.js template with SOLID architecture, TypeScript, Tailwind CSS and Vertical Slice organization.\n\n🌐 **English** | [Português](./README.pt-BR.md)\n\n## ⚡ Quick Start\n\n### 🚀 Usando pnpm (Recomendado - Mais Seguro)\n\n```bash\n# Clone and setup\ngit clone \u003cthis-repo\u003e my-app\ncd my-app\n\n# Install pnpm globally (se não tiver)\nnpm install -g pnpm\n\n# Install dependencies and setup\npnpm install\npnpm setup:hooks\n\n# Start development\npnpm dev\n```\n\n### 🔄 Outras opções\n\n```bash\n# Yarn\nyarn install \u0026\u0026 yarn setup:hooks \u0026\u0026 yarn dev\n\n# npm (fallback)\nnpm install \u0026\u0026 npm run setup:hooks \u0026\u0026 npm run dev\n```\n\n\u003e 📖 **Gerenciadores suportados**: [pnpm](docs/package-managers.md) | yarn | npm\n\n## ✨ Features\n\n- **Next.js 14+** with App Router\n- **TypeScript** + **Tailwind CSS** + **shadcn/ui**\n- **SOLID Architecture** with Vertical Slice\n- **Supabase** for auth \u0026 database (local)\n- **RBAC System** with granular permissions\n- **Payment Integration** (Stripe, Paddle, LemonSqueezy)\n- **Git hooks** (Husky + lint-staged) for code quality\n\n### 🏗️ SOLID Principles\n\n- **S**ingle Responsibility - One class/function = one responsibility\n- **O**pen/Closed - Open for extension, closed for modification\n- **L**iskov Substitution - Subtypes must be substitutable\n- **I**nterface Segregation - Specific interfaces \u003e general interfaces\n- **D**ependency Inversion - Depend on abstractions, not concretes\n\n### 🔌 11 MCP Servers (Claude Code Integration)\n\n1. **shadcn/ui MCP** - Install/manage UI components\n2. **Playwright MCP** - Browser automation \u0026 testing\n3. **Figma MCP** - Design-to-code integration\n4. **Apify MCP** - Web scraping \u0026 data extraction\n5. **Browser Automation MCP** - Additional browser control\n6. **Gemini MCP** - Google AI model integration\n7. **Context7 MCP** - Real-time documentation search\n8. **Stripe MCP** - Payment processing integration\n9. **Supabase MCP** - Local Supabase database operations\n10. **Filesystem MCP** - File system operations\n11. **Serena MCP** - AI coding agent toolkit\n\n**Note**: Git/GitHub operations use standard **CLI tools** (GitHub CLI + Git) for better performance.\n\n### 🪝 Code Quality Hooks\n\nAutomatic code quality checks on Git operations:\n\n- **Pre-commit**: Auto-format, lint, and type-check before commits\n- **Pre-push**: Final validation before pushing to remote\n- **Commit-msg**: Validates commit message format (optional)\n\n### 🛡️ Security \u0026 Access Control\n\n- **RBAC System** - Role-based access control with Supabase RLS\n- **Multi-tenant** - Organization-based permissions\n- **JWT Claims** - Automatic role/permission injection\n- **VibeKit** - AI agent sandbox isolation\n\n### 💳 SaaS Features (Next.js SaaS Starter Integration)\n\n- **Payment Processing** - Stripe, Paddle, LemonSqueezy support\n- **Subscription Management** - Complete billing workflows\n- **Customer Portal** - Self-service billing management\n- **Webhook Handling** - Automated payment event processing\n\n### 📋 Spec-Driven Development\n\n- **GitHub Spec Kit** - Specification-first development methodology\n- **Structured AI interactions** with Claude Code\n- **Living documentation** that evolves with code\n\n## 📦 Scripts\n\n```bash\nnpm run setup              # Complete setup\nnpm run setup:spec-kit     # Setup Spec-Driven Development\nnpm run dev                # Development server\nnpm run build              # Production build\nnpm run lint:fix           # Fix linting issues\nnpm run format             # Format code\nnpm run generate:feature   # Generate new feature\n```\n\n## 📁 Project Structure\n\n```\nsrc/\n├── app/                # Next.js App Router\n├── components/         # Global components\n│   └── ui/            # shadcn/ui components\n├── features/          # Business domains (Vertical Slice)\n│   ├── [feature]/\n│   │   ├── components/  # Domain-specific UI\n│   │   ├── hooks/       # Domain hooks\n│   │   ├── services/    # Business logic\n│   │   ├── stores/      # Domain state\n│   │   └── types/       # Domain types\n├── shared/            # Cross-cutting concerns\n│   ├── components/    # Shared components\n│   ├── hooks/         # Global hooks\n│   ├── stores/        # Global state\n│   ├── services/      # Infrastructure services\n│   └── utils/         # Utilities\n├── config/            # Configuration\n├── tests/             # E2E tests\n└── middleware.ts      # Route middleware\n\nspecs/             # 📋 Spec-Driven Development\n├── requirements.md # Product specifications\n├── plan.md        # Technical implementation plan\n└── tasks/         # Actionable task breakdown\n\ndocs/             # 📚 Documentation\n├── MCP-SERVERS.md # MCP configuration guide\n├── SPEC-DRIVEN-DEVELOPMENT.md # Spec Kit usage\n├── RBAC.md       # Role-based access control guide\n└── HOOKS.md      # Git hooks documentation\n```\n\n### 🎯 Features vs Shared - When to use each?\n\n**Features/** - Domain-specific business code:\n\n- ✅ Components that only exist in one context (e.g., `UserProfileCard`)\n- ✅ Specific business logic (e.g., `calculateOrderTotal`)\n- ✅ Domain local state (e.g., `useProductFilters`)\n- ✅ Domain types (e.g., `interface Product`)\n\n**Shared/** - Reusable code across multiple domains:\n\n- ✅ Generic components (e.g., `Button`, `Modal`, `Toast`)\n- ✅ Utility hooks (e.g., `useDebounce`, `useLocalStorage`)\n- ✅ Global application state (e.g., `authStore`, `themeStore`)\n- ✅ Infrastructure services (e.g., `apiClient`, `logger`)\n- ✅ Pure utilities (e.g., `formatCurrency`, `validateEmail`)\n\n**Golden rule**: If used by 2+ features → `shared/`. If specific to one feature → `features/[name]/`\n\n## 📚 Architecture Guide: Types, Hooks, and Stores\n\n### 📝 **Types** - Data Structure Definitions\n\n**What they are:** TypeScript interfaces and types that define data structures.\n\n**When to use:**\n\n- Define API data formats\n- Create contracts between layers\n- Ensure type safety\n- Document data structures\n\n**Example:**\n\n```typescript\n// features/users/types/user.types.ts\nexport interface User {\n  id: string;\n  email: string;\n  name: string;\n}\n```\n\n**Where to place:**\n\n- `features/[domain]/types/` - Domain-specific types\n- `shared/types/` - Globally shared types\n\n### 🪝 **Hooks** - Reusable Logic\n\n**What they are:** Functions that encapsulate state logic and React side effects.\n\n**When to use:**\n\n- Share logic between components\n- Manage component local state\n- Execute side effects (API calls, subscriptions)\n- Abstract complex UI logic\n\n**Example:**\n\n```typescript\n// features/users/hooks/useUser.ts\nexport function useUser(userId: string) {\n  const [user, setUser] = useState\u003cUser\u003e();\n  const [loading, setLoading] = useState(true);\n\n  useEffect(() =\u003e {\n    userService\n      .getById(userId)\n      .then(setUser)\n      .finally(() =\u003e setLoading(false));\n  }, [userId]);\n\n  return { user, loading };\n}\n```\n\n**Where to place:**\n\n- `features/[domain]/hooks/` - Domain-specific hooks\n- `shared/hooks/` - Global utility hooks\n\n### 🗄️ **Stores** - Global State\n\n**What they are:** Shared state containers between components using Zustand.\n\n**When to use:**\n\n- State that needs to be accessed by multiple components\n- Data that persists between page navigations\n- User data cache\n- Application state (theme, language, authentication)\n\n**Example:**\n\n```typescript\n// shared/stores/auth.store.ts\nexport const useAuthStore = create((set) =\u003e ({\n  user: null,\n  isAuthenticated: false,\n\n  login: (user) =\u003e set({ user, isAuthenticated: true }),\n  logout: () =\u003e set({ user: null, isAuthenticated: false }),\n}));\n```\n\n**Where to place:**\n\n- `shared/stores/` - Global state (auth, theme, UI)\n- `features/[domain]/stores/` - Domain-specific state\n\n## 🎯 Quick Decision Guide\n\n| I need to...              | Use                      | Example                                          |\n| ------------------------- | ------------------------ | ------------------------------------------------ |\n| Define data format        | **Types**                | `interface Product { id: string; name: string }` |\n| Fetch data in a component | **Hook**                 | `useProduct(id)` returns product and loading     |\n| Share state between pages | **Store**                | Shopping cart, logged user                       |\n| Validate data structure   | **Types** + Zod          | Validation schema with types                     |\n| Temporary form state      | **Hook**                 | `useForm()` with react-hook-form                 |\n| API data cache            | **Store** or React Query | Already loaded products list                     |\n| Reusable UI logic         | **Hook**                 | `useModal()`, `useDebounce()`                    |\n| Global settings           | **Store**                | Theme, language, preferences                     |\n\n## 🛡️ Middleware\n\nThe `src/middleware.ts` file manages:\n\n- Route protection and authentication\n- Request/response modifications\n- Redirects and rewrites\n- Access control for protected routes\n\nLocation: `src/middleware.ts` (same level as `src/app/`)\n\n## 🗄️ Supabase Configuration\n\n**Local Supabase** is automatically installed and configured.\n\nTo change keys: edit `scripts/setup-all.js` lines 127-129.\n\n### Access Local Supabase\n\n- **Database**: http://127.0.0.1:54321\n- **Dashboard**: http://127.0.0.1:54323\n\n## 🧪 Testing\n\n### Unit Tests (Jest)\n\n```bash\nnpm run test           # Run tests\nnpm run test:watch     # Watch mode\nnpm run test:coverage  # Coverage report\n```\n\n### E2E Tests (Playwright)\n\n```bash\nnpm run test:e2e       # Run E2E tests\nnpm run test:e2e:ui    # Visual interface\n```\n\n## 🚀 Generating New Feature\n\n```bash\nnpm run generate:feature\n\n# Follow prompts:\n# - Feature name (e.g., products)\n# - Include store? (y/n)\n# - Include service? (y/n)\n```\n\nThis will create complete structure:\n\n```\nfeatures/products/\n├── components/\n├── hooks/\n├── services/\n├── stores/\n├── types/\n└── index.ts\n```\n\n## 🚀 **Spec-Driven Development Quick Start**\n\n```bash\n# 1. Setup Spec Kit\nnpm run setup:spec-kit\n\n# 2. Start specifying in Claude Code\n/specify Build a user dashboard with analytics and settings\n\n# 3. Plan implementation\n/plan Use our SOLID providers (Auth, Database, Theme) + shadcn/ui\n\n# 4. Break into tasks\n/tasks\n\n# 5. Implement\nimplement specs/plan.md\n```\n\n**Benefits:**\n\n- 📋 **Structured development** with clear specifications\n- 🤖 **Enhanced AI interactions** with consistent context\n- 📚 **Living documentation** that evolves with code\n- 🏗️ **SOLID integration** - specs leverage existing architecture\n\nSee [Spec-Driven Development Guide](docs/SPEC-DRIVEN-DEVELOPMENT.md) for detailed usage.\n\n## 🛡️ **RBAC Quick Start**\n\n```tsx\n// 1. Wrap your app with RBAC provider\n\u003cRBACProvider\u003e\n  \u003cApp /\u003e\n\u003c/RBACProvider\u003e\n\n// 2. Protect components with permissions\n\u003cRBACGuard permissions={['users.create']}\u003e\n  \u003cCreateUserButton /\u003e\n\u003c/RBACGuard\u003e\n\n// 3. Use hooks for conditional logic\nconst { hasPermission, hasRole } = useRBAC()\nif (hasPermission('billing.read')) {\n  // Show billing section\n}\n\n// 4. Admin-only components\n\u003cAdminGuard fallback={\u003cdiv\u003eAccess denied\u003c/div\u003e}\u003e\n  \u003cAdminPanel /\u003e\n\u003c/AdminGuard\u003e\n```\n\n**Features:**\n\n- 🎯 **Granular permissions** - Resource-based access control\n- 🏢 **Multi-tenant** - Organization-scoped permissions\n- ⚡ **JWT integration** - Permissions in token for performance\n- 🔒 **Supabase RLS** - Database-level security\n- 🎨 **React components** - Guards, hooks, and providers\n\nSee [RBAC Documentation](docs/RBAC.md) for complete guide.\n\n## 📋 Best Practices Checklist\n\n### Before Implementation\n\n- [ ] Check if similar code already exists\n- [ ] Confirm requirements with user\n- [ ] Plan following SOLID principles\n\n### During Implementation\n\n- [ ] One responsibility per class/function\n- [ ] Use appropriate TypeScript types\n- [ ] Reuse existing code\n- [ ] Follow project patterns\n\n### After Implementation\n\n- [ ] Run linter and type-check\n- [ ] Add/update tests\n- [ ] Request user approval\n\n## 📚 Docs\n\n- [MCP Servers](docs/MCP-SERVERS.md)\n- [Spec-Driven Development](docs/SPEC-DRIVEN-DEVELOPMENT.md)\n- [RBAC System](docs/RBAC.md)\n- [Git Hooks](docs/HOOKS.md)\n- [Middleware](docs/MIDDLEWARE.md)\n\n## 🙏 **Acknowledgments**\n\nThis template integrates and adapts code from the excellent **Next.js SaaS Starter** by Vercel:\n\n- **Repository**: [nextjs/saas-starter](https://github.com/nextjs/saas-starter)\n- **Features integrated**: Stripe payments, RBAC system, activity logging\n- **Adapted with**: SOLID architecture, MCP integration, Spec-Driven Development\n\n**Special thanks to the Vercel team** for creating such a solid foundation for SaaS applications! 🚀\n\nWe've enhanced their approach with:\n\n- ✅ **SOLID principles** implementation\n- ✅ **11+ MCP servers** for enhanced development\n- ✅ **Spec-Driven Development** methodology\n- ✅ **Provider abstractions** for extensibility\n\n## 📄 License\n\nMIT\n\n---\n\n**Built with SOLID principles and software engineering best practices.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucasps136%2Fbaseclaudereactwebtemplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flucasps136%2Fbaseclaudereactwebtemplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucasps136%2Fbaseclaudereactwebtemplate/lists"}