{"id":29610878,"url":"https://github.com/theboeffect/nextjs-cursor-boilerplate","last_synced_at":"2025-07-20T20:08:38.483Z","repository":{"id":295523290,"uuid":"990316326","full_name":"theBoEffect/nextjs-cursor-boilerplate","owner":"theBoEffect","description":"A Next.js boilerplate optimized for Cursor AI development with comprehensive rules and best practices.","archived":false,"fork":false,"pushed_at":"2025-07-06T16:08:57.000Z","size":278,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-06T17:27:16.304Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/theBoEffect.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}},"created_at":"2025-05-25T23:40:29.000Z","updated_at":"2025-07-06T16:09:00.000Z","dependencies_parsed_at":"2025-05-26T01:42:24.472Z","dependency_job_id":"763cdb17-2a03-4766-ba3a-9cc651ae94ea","html_url":"https://github.com/theBoEffect/nextjs-cursor-boilerplate","commit_stats":null,"previous_names":["unitedeffects/nextjs-cursor-boilerplate","theboeffect/nextjs-cursor-boilerplate"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/theBoEffect/nextjs-cursor-boilerplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theBoEffect%2Fnextjs-cursor-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theBoEffect%2Fnextjs-cursor-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theBoEffect%2Fnextjs-cursor-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theBoEffect%2Fnextjs-cursor-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theBoEffect","download_url":"https://codeload.github.com/theBoEffect/nextjs-cursor-boilerplate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theBoEffect%2Fnextjs-cursor-boilerplate/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266189677,"owners_count":23890065,"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","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-07-20T20:08:38.341Z","updated_at":"2025-07-20T20:08:38.476Z","avatar_url":"https://github.com/theBoEffect.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Next.js Cursor AI Boilerplate\n\nA production-ready Next.js boilerplate specifically optimized for development with Cursor AI. This template includes comprehensive rules, best practices, and patterns that maximize AI-assisted development effectiveness.\n\n## ✨ Features\n\n- **🤖 Cursor AI Optimized**: Comprehensive rules and patterns for effective AI-assisted development\n- **⚡ Next.js 15**: Latest Next.js with App Router and Server Components\n- **🔷 TypeScript**: Full type safety with strict TypeScript configuration\n- **🎨 Tailwind CSS**: Modern styling with Tailwind CSS v4 and clsx utilities\n- **🧩 shadcn/ui**: Beautiful, accessible UI components built on Radix UI\n- **🧪 Testing Ready**: Vitest + Testing Library setup with TDD rules\n- **🔒 Security First**: Environment variable management and security best practices\n- **📦 Package Management**: Yarn with proper dependency management\n- **🏗️ Feature-Based Architecture**: Organized by domain/feature for scalability\n- **🔄 OpenAI Integration**: Built-in patterns for concurrent AI API calls\n- **📋 Comprehensive Rules**: 10+ Cursor rules for consistent development\n\n## 🚀 Quick Start\n\n1. **Use this template**:\n   ```bash\n   # Clone or use as template\n   git clone https://github.com/your-username/nextjs-cursor-boilerplate.git my-project\n   cd my-project\n   ```\n\n2. **Install dependencies**:\n   ```bash\n   yarn install\n   ```\n\n3. **Set up environment variables**:\n   ```bash\n   cp .env.example .env.local\n   # Edit .env.local with your actual API keys and configuration\n   ```\n\n4. **Start development**:\n   ```bash\n   yarn dev\n   ```\n\n5. **Run tests**:\n   ```bash\n   yarn test\n   ```\n\n## 📁 Project Structure\n\n```\nsrc/\n├── app/                    # Next.js app router\n│   ├── api/               # API routes\n│   │   └── feature-example/   # Feature example api\n│   └── page-example/             # Page example api\n├── features/              # Feature-specific code (organized by domain)\n│   ├── home/              # Landing page feature\n│   │   ├── components/    # Home-specific components\n│   │   ├── hooks/         # Home-specific hooks\n│   │   ├── utils/         # Home-specific utilities\n│   │   ├── types/         # Home-specific types\n│   │   └── __tests__/     # Home feature tests\n│   │       ├── components/    # Component tests\n│   │       ├── hooks/         # Hook tests\n│   │       └── utils/         # Utility tests\n│   ├── page-example/             # page-example feature (future)\n│   └── shared/            # Global features spanning multiple pages\n│       └── __tests__/     # Shared feature tests\n├── components/            # Global reusable UI components\n│   └── ui/               # shadcn/ui components\n├── lib/                  # Global utility functions and clients\n│   ├── clients/          # API clients (OpenAI, HubSpot)\n│   └── utils/            # Helper functions\n├── types/                # Global TypeScript type definitions\n├── hooks/                # Global React hooks\n└── __tests__/            # Global test setup and integration tests\n```\n\n## 🤖 Cursor AI Integration\n\nThis boilerplate is specifically designed to work seamlessly with Cursor AI:\n\n### Built-in Rules\n- **Test-Driven Development**: Enforces writing tests before implementation\n- **OpenAI Concurrency**: Patterns for efficient AI API calls\n- **Environment Management**: Secure handling of API keys and secrets\n- **File Movement**: Proper file operations preserving history\n- **Multi-file Changes**: Structured approach to complex modifications\n- **Minimal Code Changes**: Avoiding unnecessary refactoring\n- **Package Management**: Consistent use of Yarn\n- **Directory Documentation**: Auto-prompting for new directory documentation\n\n### AI-Optimized Patterns\n- Clear, descriptive naming conventions\n- Explicit type definitions\n- Well-documented interfaces\n- Feature-based organization\n- Separation of concerns\n- Comprehensive error handling\n\n## 🛠️ Development Guidelines\n\n### Working with Cursor AI\n1. **Be Specific**: Provide clear, detailed prompts with context\n2. **Include File Paths**: Reference exact locations when discussing code\n3. **Break Down Tasks**: Split complex requests into smaller, focused tasks\n4. **Test First**: Always write tests before implementation (enforced by rules)\n5. **Use Existing Patterns**: Reference similar implementations in the codebase\n\n### Code Organization\n- **Feature-First**: Organize by business domain, not technical layer\n- **Co-location**: Keep related files (components, tests, types) together\n- **Clear Boundaries**: Separate client and server code appropriately\n- **Type Safety**: Use TypeScript for all code with strict configuration\n\n### Testing Strategy\n- **TDD Enforced**: Rules prevent implementation without tests\n- **Feature Tests**: Tests co-located with feature code\n- **Integration Tests**: Global tests for cross-feature functionality\n- **Component Tests**: UI component behavior and interactions\n\n## 📦 Scripts\n\n- `yarn dev` - Start development server\n- `yarn build` - Build for production\n- `yarn start` - Start production server\n- `yarn test` - Run tests\n- `yarn test:watch` - Run tests in watch mode\n- `yarn test:ui` - Run tests with UI\n- `yarn type-check` - Run TypeScript type checking\n- `yarn lint` - Run ESLint\n\n## 🔧 Configuration\n\n### Environment Variables\nCopy `.env.example` to `.env.local` and configure:\n\n```bash\n# Required for AI features\nOPENAI_API_KEY=your_openai_api_key_here\n\n# Required for authentication (if using NextAuth.js)\nNEXTAUTH_SECRET=your_nextauth_secret_here\nNEXTAUTH_URL=http://localhost:3000\n\n# Optional: Database\nDATABASE_URL=your_database_url_here\n\n# Optional: External APIs\nSTRIPE_SECRET_KEY=your_stripe_secret_key_here\nRESEND_API_KEY=your_resend_api_key_here\n```\n\n### TypeScript\nStrict TypeScript configuration with:\n- Strict mode enabled\n- Path mapping configured (`@/` for `src/`)\n- Type checking for build process\n\n### Tailwind CSS\n- Tailwind CSS v4 with modern configuration\n- Custom design system ready\n- clsx for conditional styling\n- shadcn/ui integration\n\n## 🚀 Deployment\n\nThis boilerplate is optimized for deployment on:\n- **Vercel** (recommended for Next.js)\n- **Netlify**\n- **Railway**\n- **Any Node.js hosting platform**\n\n### Deployment Checklist\n1. Set environment variables in your hosting platform\n2. Ensure all required API keys are configured\n3. Run `yarn build` to verify production build\n4. Configure domain and SSL if needed\n\n## 🤝 Contributing\n\n1. Follow the established patterns and rules\n2. Write tests before implementation (enforced by Cursor rules)\n3. Use descriptive commit messages\n4. Update documentation for new features\n5. Ensure all tests pass before submitting\n\n## 📄 License\n\nMIT License - feel free to use this boilerplate for any project.\n\n## 🆘 Getting Help\n\n- Check the `.cursor/rules/` directory for comprehensive development guidelines\n- Use specific, detailed prompts when working with Cursor AI\n- Reference existing patterns in the codebase\n- Follow the test-driven development approach enforced by the rules\n\n---\n\n**Happy coding with Cursor AI! 🚀**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheboeffect%2Fnextjs-cursor-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheboeffect%2Fnextjs-cursor-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheboeffect%2Fnextjs-cursor-boilerplate/lists"}