From 7ee26ab699943fb0f67da3496d9eefdcba2b4eca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1rcio=20Barroso?= Date: Wed, 24 Sep 2025 13:07:55 -0300 Subject: [PATCH] fix: fixing agent issue --- .../bmad-nextjs-fullstack/README.md | 20 ++- .../agents/api-developer.yaml | 6 +- .../agents/base-controller-specialist.yaml | 6 +- .../agents/domain-architect.yaml | 6 +- .../agents/nextjs-architect.yaml | 6 +- .../agents/tailwind-designer.yaml | 6 +- .../agents/typescript-specialist.yaml | 6 +- .../checklists/base-controller-checklist.md | 22 ++- .../checklists/component-checklist.md | 12 +- .../feature-based-architecture-checklist.md | 20 ++- .../bmad-nextjs-fullstack/config.yaml | 2 +- .../tasks/create-api-endpoint.md | 86 ++++++------ .../tasks/setup-from-template.md | 125 +++++++++++------- .../tasks/setup-nextjs-project.md | 16 ++- .../templates/api-route-template.yaml | 2 +- .../templates/base-controller-template.yaml | 2 +- .../templates/component-template.yaml | 2 +- .../templates/feature-structure-template.yaml | 6 +- .../base-controller-implementation.yaml | 2 +- .../workflows/domain-feature-development.yaml | 10 +- .../feature-based-project-setup.yaml | 2 +- .../workflows/feature-development.yaml | 3 +- .../workflows/nextjs-project-setup.yaml | 2 +- 23 files changed, 245 insertions(+), 125 deletions(-) diff --git a/expansion-packs/bmad-nextjs-fullstack/README.md b/expansion-packs/bmad-nextjs-fullstack/README.md index 9ac8c661..ec0dd705 100644 --- a/expansion-packs/bmad-nextjs-fullstack/README.md +++ b/expansion-packs/bmad-nextjs-fullstack/README.md @@ -9,6 +9,7 @@ This extension pack provides everything needed to build enterprise-grade Next.js ## ✨ Features ### 🤖 Specialized AI Agents + - **Domain Architect** - Business domain modeling and bounded context definition - **Next.js Architect** - Feature-Based Architecture and App Router patterns - **BaseController Specialist** - Database-agnostic controller patterns and schema-first design @@ -23,6 +24,7 @@ This extension pack provides everything needed to build enterprise-grade Next.js - **Security Auditor** - Security best practices for modern web applications ### 🔄 Domain-Driven Workflows + - **Feature-Based Project Setup** - Initialize project from `nextjs-new-app` template - **Domain Feature Development** - Complete business domain implementation - **BaseController Implementation** - Database-agnostic controller setup @@ -32,6 +34,7 @@ This extension pack provides everything needed to build enterprise-grade Next.js - **Deployment Pipeline** - Production deployment with Feature-Based Architecture ### 📝 Architecture Templates + - Feature Structure Template (Complete feature organization) - BaseController Extension Template (Database-agnostic controller) - Schema-First Entity Template (Zod validation + TypeScript types) @@ -40,6 +43,7 @@ This extension pack provides everything needed to build enterprise-grade Next.js - Custom Hooks Template (Data fetching patterns) ### ✅ Architecture Checklists + - Feature-Based Architecture Development Checklist - BaseController Implementation Checklist - Domain-Driven Design Checklist @@ -49,7 +53,9 @@ This extension pack provides everything needed to build enterprise-grade Next.js ## 🚀 Quick Start ### Template Base + This extension pack is designed to work with the `nextjs-new-app` template: + ```bash # Clone the base template git clone https://github.com/marciobarroso/nextjs-new-app.git my-project @@ -60,6 +66,7 @@ pnpm install # or npm install ``` ### Extension Pack Usage + ```bash # Use BMAD Method with this extension pack bmad-fba create-feature "user-management" @@ -88,12 +95,14 @@ This extension pack implements Feature-Based Architecture with Domain-Driven Des ## 📚 Documentation ### Core Concepts + - [Project Structure](docs/project-structure.md) - [Component Patterns](docs/component-patterns.md) - [API Design](docs/api-design.md) - [State Management](docs/state-management.md) ### Guides + - [Getting Started](docs/getting-started.md) - [Development Workflow](docs/development-workflow.md) - [Testing Strategy](docs/testing-strategy.md) @@ -102,6 +111,7 @@ This extension pack implements Feature-Based Architecture with Domain-Driven Des ## 🛠️ Technology Stack ### Core Technologies (from nextjs-new-app template) + - **Next.js 15.5.3** - React framework with App Router - **React 19.1.0** - Latest React with modern features - **TypeScript 5** - Strict type safety @@ -110,12 +120,14 @@ This extension pack implements Feature-Based Architecture with Domain-Driven Des - **pnpm** - Efficient package management ### Development Tools (pre-configured) + - **ESLint 9** - Code linting with Next.js integration - **Prettier 3.6.2** - Code formatting with import sorting - **Husky 9.1.7** - Git hooks for code quality - **Jest** - Testing framework (configured, ready for implementation) ### Feature-Based Architecture Additions + - **Zod** - Schema validation and type generation - **BaseController Pattern** - Database-agnostic CRUD operations - **Domain-Driven Design** - Business domain organization @@ -124,6 +136,7 @@ This extension pack implements Feature-Based Architecture with Domain-Driven Des ## 🎯 Best Practices ### Code Quality + - Strict TypeScript configuration - Comprehensive ESLint rules - Automatic code formatting with Prettier @@ -131,6 +144,7 @@ This extension pack implements Feature-Based Architecture with Domain-Driven Des - API-first design approach ### Performance + - Server Components by default - Client Components only when needed - Image optimization with Next.js Image @@ -138,6 +152,7 @@ This extension pack implements Feature-Based Architecture with Domain-Driven Des - Core Web Vitals monitoring ### Security + - Input validation with Zod - CSRF protection - Secure headers middleware @@ -194,11 +209,12 @@ This extension pack is part of the BMAD Method project and follows the same MIT **Current Version:** 1.0.0 -**Compatibility:** +**Compatibility:** + - Next.js 14+ - Node.js 18+ - TypeScript 5+ --- -Built with ❤️ using the BMAD Method framework. \ No newline at end of file +Built with ❤️ using the BMAD Method framework. diff --git a/expansion-packs/bmad-nextjs-fullstack/agents/api-developer.yaml b/expansion-packs/bmad-nextjs-fullstack/agents/api-developer.yaml index 8b57e591..c7bf64df 100644 --- a/expansion-packs/bmad-nextjs-fullstack/agents/api-developer.yaml +++ b/expansion-packs/bmad-nextjs-fullstack/agents/api-developer.yaml @@ -11,7 +11,7 @@ background: >- directive: >- You are an API Development Specialist focused on creating robust, scalable, and secure backend services. Your expertise includes: - + - Next.js API Routes and Route Handlers - RESTful API design and best practices - GraphQL implementation and optimization @@ -21,7 +21,7 @@ directive: >- - Error handling and validation - Caching strategies and performance optimization - Security best practices and OWASP guidelines - + Always prioritize security, performance, and maintainability in API design. Follow REST principles and modern backend patterns. @@ -29,4 +29,4 @@ conversation_starters: - "Let's design the API structure for this feature" - "How should we handle authentication in this API?" - "Help me optimize this database query" - - "What's the best way to validate and handle this API request?" \ No newline at end of file + - "What's the best way to validate and handle this API request?" diff --git a/expansion-packs/bmad-nextjs-fullstack/agents/base-controller-specialist.yaml b/expansion-packs/bmad-nextjs-fullstack/agents/base-controller-specialist.yaml index 86e28453..ba96fa41 100644 --- a/expansion-packs/bmad-nextjs-fullstack/agents/base-controller-specialist.yaml +++ b/expansion-packs/bmad-nextjs-fullstack/agents/base-controller-specialist.yaml @@ -11,7 +11,7 @@ background: >- directive: >- You are a BaseController Pattern Specialist focused on creating consistent, database-agnostic API controllers. Your expertise includes: - + - BaseController abstract class implementation - Schema-first design with Zod validation - Database-agnostic patterns (Prisma, TypeORM, Mongoose, etc.) @@ -21,7 +21,7 @@ directive: >- - Type-safe database operations - API response standardization - Error handling and logging patterns - + Always prioritize database abstraction, schema validation, type safety, and consistent patterns across all feature controllers. Follow the established BaseController pattern from the project architecture. @@ -30,4 +30,4 @@ conversation_starters: - "Let's implement a BaseController for this entity" - "How should we structure the schema validation for this feature?" - "Help me create a database-agnostic controller pattern" - - "What's the best way to handle search filtering in BaseController?" \ No newline at end of file + - "What's the best way to handle search filtering in BaseController?" diff --git a/expansion-packs/bmad-nextjs-fullstack/agents/domain-architect.yaml b/expansion-packs/bmad-nextjs-fullstack/agents/domain-architect.yaml index dbabe51f..ab900806 100644 --- a/expansion-packs/bmad-nextjs-fullstack/agents/domain-architect.yaml +++ b/expansion-packs/bmad-nextjs-fullstack/agents/domain-architect.yaml @@ -11,7 +11,7 @@ background: >- directive: >- You are a Domain-Driven Design Specialist focused on Feature-Based Architecture organization and business domain modeling. Your expertise includes: - + - Business domain identification and modeling - Bounded context definition and boundaries - Feature-Based Architecture organization in (features)/ groups @@ -22,7 +22,7 @@ directive: >- - Domain service patterns - Event-driven architecture for domain events - Anti-corruption layers for external integrations - + Always prioritize business domain clarity, feature independence, and clean boundaries between different business contexts. Ensure each feature represents a cohesive business domain with minimal external dependencies. @@ -31,4 +31,4 @@ conversation_starters: - "Let's identify the business domains for this application" - "How should we define bounded contexts for these features?" - "Help me organize these business requirements into feature modules" - - "What's the best way to model this business entity and its relationships?" \ No newline at end of file + - "What's the best way to model this business entity and its relationships?" diff --git a/expansion-packs/bmad-nextjs-fullstack/agents/nextjs-architect.yaml b/expansion-packs/bmad-nextjs-fullstack/agents/nextjs-architect.yaml index a1bb6aec..30a180ae 100644 --- a/expansion-packs/bmad-nextjs-fullstack/agents/nextjs-architect.yaml +++ b/expansion-packs/bmad-nextjs-fullstack/agents/nextjs-architect.yaml @@ -11,7 +11,7 @@ background: >- directive: >- You are a Next.js Feature-Based Architecture Specialist focused on Domain-Driven Design and self-contained feature modules. Your expertise includes: - + - Feature-Based Architecture with (features)/ route groups - Domain-Driven Design principles and bounded contexts - Next.js 15+ App Router with Server/Client component patterns @@ -21,7 +21,7 @@ directive: >- - Shared infrastructure patterns in shared/ directory - Cross-feature integration and dependency management - TypeScript strict mode and type safety end-to-end - + Always recommend Feature-Based organization, minimize cross-feature dependencies, and ensure each feature represents a clear business domain with consistent patterns. @@ -29,4 +29,4 @@ conversation_starters: - "Let's design a Feature-Based Architecture for this business domain" - "How should we structure this feature following Domain-Driven Design?" - "What's the best way to organize this bounded context in (features)/" - - "Help me implement the BaseController pattern for this entity" \ No newline at end of file + - "Help me implement the BaseController pattern for this entity" diff --git a/expansion-packs/bmad-nextjs-fullstack/agents/tailwind-designer.yaml b/expansion-packs/bmad-nextjs-fullstack/agents/tailwind-designer.yaml index 2f19f993..9c8f3162 100644 --- a/expansion-packs/bmad-nextjs-fullstack/agents/tailwind-designer.yaml +++ b/expansion-packs/bmad-nextjs-fullstack/agents/tailwind-designer.yaml @@ -11,7 +11,7 @@ background: >- directive: >- You are a Tailwind CSS Design Specialist focused on creating beautiful, responsive, and accessible user interfaces. Your expertise includes: - + - Tailwind CSS configuration and customization - Utility-first CSS methodology and best practices - Responsive design patterns and breakpoints @@ -20,7 +20,7 @@ directive: >- - Accessibility and WCAG compliance - Performance optimization for CSS - Integration with Next.js and React components - + Always prioritize clean, maintainable CSS with excellent user experience, accessibility, and performance. Follow modern design principles and Tailwind best practices. @@ -29,4 +29,4 @@ conversation_starters: - "Let's design a responsive component with Tailwind CSS" - "How can we customize the Tailwind configuration for this project?" - "Help me create an accessible form design" - - "What's the best approach for this layout in Tailwind?" \ No newline at end of file + - "What's the best approach for this layout in Tailwind?" diff --git a/expansion-packs/bmad-nextjs-fullstack/agents/typescript-specialist.yaml b/expansion-packs/bmad-nextjs-fullstack/agents/typescript-specialist.yaml index d9877107..3b00e93a 100644 --- a/expansion-packs/bmad-nextjs-fullstack/agents/typescript-specialist.yaml +++ b/expansion-packs/bmad-nextjs-fullstack/agents/typescript-specialist.yaml @@ -11,7 +11,7 @@ background: >- directive: >- You are a TypeScript Specialist dedicated to creating type-safe, maintainable code. Your expertise includes: - + - Advanced TypeScript configuration and compiler options - Complex type definitions and interfaces - Generic types and utility types @@ -20,7 +20,7 @@ directive: >- - Error handling and type-safe API responses - Module declaration and ambient types - Performance optimization of TypeScript builds - + Always prioritize type safety while maintaining code readability and developer productivity. Recommend strict TypeScript configurations and modern typing patterns. @@ -29,4 +29,4 @@ conversation_starters: - "Help me set up TypeScript configuration for this Next.js project" - "How can we improve type safety in this component?" - "What's the best way to type this API response?" - - "Let's create type definitions for this data structure" \ No newline at end of file + - "Let's create type definitions for this data structure" diff --git a/expansion-packs/bmad-nextjs-fullstack/checklists/base-controller-checklist.md b/expansion-packs/bmad-nextjs-fullstack/checklists/base-controller-checklist.md index 053062f3..1ddb387e 100644 --- a/expansion-packs/bmad-nextjs-fullstack/checklists/base-controller-checklist.md +++ b/expansion-packs/bmad-nextjs-fullstack/checklists/base-controller-checklist.md @@ -1,6 +1,7 @@ # BaseController Implementation Checklist ## Abstract Class Setup + - [ ] BaseController abstract class created in `shared/core/` - [ ] Generic type parameter `` properly defined - [ ] Database client abstraction implemented @@ -8,6 +9,7 @@ - [ ] Constructor properly initializes dependencies ## CRUD Operations Implementation + - [ ] `getAll` method implemented with pagination - [ ] `getById` method implemented with proper error handling - [ ] `create` method implemented with validation @@ -16,6 +18,7 @@ - [ ] All methods return proper HTTP responses ## Search & Filtering + - [ ] Abstract `buildSearchFilter` method defined - [ ] Search parameter extraction implemented - [ ] Database-agnostic filter pattern established @@ -24,6 +27,7 @@ - [ ] Search performance considered ## Validation & Schema Integration + - [ ] Zod schema validation on all inputs - [ ] Create schema validation implemented - [ ] Update schema validation implemented @@ -32,6 +36,7 @@ - [ ] Validation error messages are user-friendly ## Error Handling + - [ ] Consistent error response format - [ ] HTTP status codes properly used - [ ] Validation errors properly formatted @@ -40,6 +45,7 @@ - [ ] Error messages don't expose sensitive data ## Database Abstraction + - [ ] Database client interface defined - [ ] Connection management abstracted - [ ] Database-specific operations isolated @@ -48,6 +54,7 @@ - [ ] Connection pooling handled ## Response Formatting + - [ ] Consistent API response structure - [ ] Success responses properly formatted - [ ] Error responses standardized @@ -56,6 +63,7 @@ - [ ] Content-Type headers set correctly ## Feature Controller Extension + - [ ] Feature controller extends BaseController - [ ] Entity-specific `buildSearchFilter` implemented - [ ] Custom business logic methods added @@ -64,6 +72,7 @@ - [ ] Controller singleton pattern implemented (if needed) ## Type Safety + - [ ] Generic types properly constrained - [ ] Entity model interfaces defined - [ ] API response types defined @@ -72,6 +81,7 @@ - [ ] Return types explicitly defined ## Performance Optimization + - [ ] Database queries optimized - [ ] Proper indexing strategy planned - [ ] Pagination limits enforced @@ -80,6 +90,7 @@ - [ ] Database connection reuse implemented ## Testing + - [ ] Unit tests for BaseController methods - [ ] Mock database client created - [ ] Test data fixtures defined @@ -88,6 +99,7 @@ - [ ] Performance tests implemented ## Documentation + - [ ] BaseController usage documented - [ ] Extension patterns documented - [ ] Database integration examples provided @@ -96,6 +108,7 @@ - [ ] Performance considerations documented ## Logging & Monitoring + - [ ] Request/response logging implemented - [ ] Error logging with stack traces - [ ] Performance metrics captured @@ -104,6 +117,7 @@ - [ ] Audit trail for data changes ## Security Considerations + - [ ] Input sanitization implemented - [ ] SQL injection prevention (for SQL databases) - [ ] NoSQL injection prevention (for NoSQL databases) @@ -112,7 +126,9 @@ - [ ] Sensitive data handling ## Database-Specific Implementations + ### For SQL Databases (Prisma/TypeORM) + - [ ] Proper WHERE clause generation - [ ] JOIN operations handled - [ ] Transaction support implemented @@ -120,6 +136,7 @@ - [ ] Relationship loading optimized ### For MongoDB (Mongoose) + - [ ] Query object generation - [ ] Aggregation pipeline support - [ ] Index utilization optimized @@ -127,6 +144,7 @@ - [ ] Connection string security ### For Serverless Databases + - [ ] Connection pooling optimized - [ ] Cold start mitigation - [ ] Query timeout handling @@ -134,6 +152,7 @@ - [ ] Cost optimization considered ## Integration Points + - [ ] Authentication middleware integration - [ ] Authorization checks implemented - [ ] Audit logging integrated @@ -142,9 +161,10 @@ - [ ] External API integration patterns ## Production Readiness + - [ ] Environment variable configuration - [ ] Production database connection - [ ] Error monitoring integration - [ ] Performance monitoring setup - [ ] Load testing completed -- [ ] Backup and recovery procedures \ No newline at end of file +- [ ] Backup and recovery procedures diff --git a/expansion-packs/bmad-nextjs-fullstack/checklists/component-checklist.md b/expansion-packs/bmad-nextjs-fullstack/checklists/component-checklist.md index 895b8483..3deb242b 100644 --- a/expansion-packs/bmad-nextjs-fullstack/checklists/component-checklist.md +++ b/expansion-packs/bmad-nextjs-fullstack/checklists/component-checklist.md @@ -1,12 +1,14 @@ # React Component Development Checklist ## Pre-Development + - [ ] Component purpose and requirements clearly defined - [ ] Component interface (props) designed - [ ] Accessibility requirements identified - [ ] Design mockup/wireframe available ## Development + - [ ] TypeScript interface defined for all props - [ ] Component follows naming conventions (PascalCase) - [ ] Proper file structure and organization @@ -14,6 +16,7 @@ - [ ] Error boundaries implemented for critical components ## Styling + - [ ] Tailwind CSS classes used consistently - [ ] Responsive design implemented - [ ] Dark mode support (if applicable) @@ -21,6 +24,7 @@ - [ ] CSS class conflicts avoided ## Accessibility (a11y) + - [ ] Semantic HTML elements used - [ ] ARIA labels added where needed - [ ] Keyboard navigation supported @@ -29,6 +33,7 @@ - [ ] Color contrast meets WCAG guidelines ## Performance + - [ ] Unnecessary re-renders avoided - [ ] React.memo used where appropriate - [ ] Heavy computations memoized with useMemo @@ -36,6 +41,7 @@ - [ ] Large lists virtualized (if applicable) ## Testing + - [ ] Unit tests written and passing - [ ] Component renders without crashing - [ ] Props validation tested @@ -44,6 +50,7 @@ - [ ] Accessibility testing performed ## Code Quality + - [ ] TypeScript types are strict and accurate - [ ] ESLint rules pass - [ ] Prettier formatting applied @@ -52,6 +59,7 @@ - [ ] Comments added for complex logic ## Integration + - [ ] Component integrates well with parent components - [ ] State management working correctly - [ ] API calls handled properly (if applicable) @@ -59,14 +67,16 @@ - [ ] Loading states implemented ## Documentation + - [ ] Component documented with JSDoc comments - [ ] Props interface documented - [ ] Usage examples provided - [ ] Storybook story created (if using Storybook) ## Review + - [ ] Code review completed - [ ] Design review completed - [ ] Performance review completed - [ ] Accessibility review completed -- [ ] Security review completed (if handling sensitive data) \ No newline at end of file +- [ ] Security review completed (if handling sensitive data) diff --git a/expansion-packs/bmad-nextjs-fullstack/checklists/feature-based-architecture-checklist.md b/expansion-packs/bmad-nextjs-fullstack/checklists/feature-based-architecture-checklist.md index 5071346a..9bcb474a 100644 --- a/expansion-packs/bmad-nextjs-fullstack/checklists/feature-based-architecture-checklist.md +++ b/expansion-packs/bmad-nextjs-fullstack/checklists/feature-based-architecture-checklist.md @@ -1,6 +1,7 @@ # Feature-Based Architecture Development Checklist ## Domain Analysis & Planning + - [ ] Business domain clearly identified and defined - [ ] Bounded context boundaries established - [ ] Domain entities and relationships mapped @@ -9,6 +10,7 @@ - [ ] Business requirements thoroughly documented ## Project Structure + - [ ] Feature organized in `(features)/({feature-name})/` route group - [ ] API layer structured in `api/{entity-name}/` directory - [ ] Components organized in `components/` directory within feature @@ -17,6 +19,7 @@ - [ ] Feature pages organized in appropriate subdirectories ## Schema-First Development + - [ ] Zod schema defined for entity validation - [ ] TypeScript interfaces derived from Zod schemas - [ ] Create, Update, and Search schemas properly defined @@ -25,6 +28,7 @@ - [ ] Schema validation covers all business rules ## BaseController Implementation + - [ ] Entity controller extends BaseController abstract class - [ ] Database-agnostic design maintained - [ ] `buildSearchFilter` method implemented for entity-specific search @@ -33,6 +37,7 @@ - [ ] Controller uses Zod schema for validation ## API Routes Development + - [ ] Collection routes (`/api/{entity}`) implemented - [ ] Individual entity routes (`/api/{entity}/[id]`) implemented - [ ] HTTP methods properly implemented (GET, POST, PUT, DELETE) @@ -41,6 +46,7 @@ - [ ] Database connection properly managed ## Custom Hooks Implementation + - [ ] Data fetching hooks follow naming convention (`use{Entities}`) - [ ] Mutation hooks follow naming convention (`use{Entity}Mutations`) - [ ] Single entity hooks follow naming convention (`use{Entity}`) @@ -50,6 +56,7 @@ - [ ] Search functionality integrated ## React Components + - [ ] Components follow PascalCase naming convention - [ ] Form components implemented (`{Entity}Form`) - [ ] List components implemented (`{Entity}List`) @@ -60,6 +67,7 @@ - [ ] Components follow accessibility guidelines ## Next.js Pages + - [ ] Feature index page implemented (`page.tsx`) - [ ] Entity detail pages implemented (`[id]/page.tsx`) - [ ] Create new entity page implemented (`new/page.tsx`) @@ -69,6 +77,7 @@ - [ ] Proper layouts and navigation implemented ## Type Safety + - [ ] Strict TypeScript configuration enforced - [ ] No `any` types used - [ ] End-to-end type safety from database to UI @@ -77,6 +86,7 @@ - [ ] Generic types used appropriately ## Code Quality + - [ ] ESLint rules passing without warnings - [ ] Prettier formatting applied consistently - [ ] No console statements in production code @@ -85,6 +95,7 @@ - [ ] Code follows established conventions ## Testing + - [ ] Unit tests for controller logic - [ ] API route integration tests - [ ] React component tests @@ -93,6 +104,7 @@ - [ ] Test data and mocks properly implemented ## Database Integration + - [ ] Database connection abstracted properly - [ ] ORM/ODM integration follows patterns - [ ] Migration strategy considered @@ -101,6 +113,7 @@ - [ ] Data relationships properly modeled ## Performance Considerations + - [ ] Server Components used for data fetching - [ ] Client Components minimized - [ ] Database queries optimized @@ -109,6 +122,7 @@ - [ ] Bundle size impact assessed ## Security + - [ ] Input validation on all API endpoints - [ ] Authentication/authorization considered - [ ] SQL injection prevention (if using SQL database) @@ -117,6 +131,7 @@ - [ ] Error messages don't leak sensitive information ## Documentation + - [ ] Feature purpose and scope documented - [ ] API endpoints documented - [ ] Component usage examples provided @@ -125,6 +140,7 @@ - [ ] Database schema documented ## Integration & Dependencies + - [ ] Shared infrastructure properly utilized - [ ] Cross-feature dependencies minimized - [ ] Integration points well-defined @@ -133,6 +149,7 @@ - [ ] Feature can be tested in isolation ## Deployment Readiness + - [ ] Environment variables properly configured - [ ] Production build successful - [ ] Database migrations ready (if needed) @@ -141,9 +158,10 @@ - [ ] Health checks implemented ## Review & Quality Assurance + - [ ] Code review completed - [ ] Architecture review completed - [ ] Business logic verified - [ ] User experience tested - [ ] Accessibility tested -- [ ] Cross-browser compatibility verified \ No newline at end of file +- [ ] Cross-browser compatibility verified diff --git a/expansion-packs/bmad-nextjs-fullstack/config.yaml b/expansion-packs/bmad-nextjs-fullstack/config.yaml index ddaf6ea9..6240f67a 100644 --- a/expansion-packs/bmad-nextjs-fullstack/config.yaml +++ b/expansion-packs/bmad-nextjs-fullstack/config.yaml @@ -9,4 +9,4 @@ description: >- database-agnostic design, and enterprise-grade development workflows following modern Next.js App Router conventions with Server/Client component patterns. author: marciobarroso -slashPrefix: bmad-fba \ No newline at end of file +slashPrefix: bmad-fba diff --git a/expansion-packs/bmad-nextjs-fullstack/tasks/create-api-endpoint.md b/expansion-packs/bmad-nextjs-fullstack/tasks/create-api-endpoint.md index 1d42e70f..7f3f7c1f 100644 --- a/expansion-packs/bmad-nextjs-fullstack/tasks/create-api-endpoint.md +++ b/expansion-packs/bmad-nextjs-fullstack/tasks/create-api-endpoint.md @@ -1,9 +1,11 @@ # Create API Endpoint ## Task Overview + Create a new API endpoint in Next.js with proper TypeScript typing, validation, and error handling. ## Prerequisites + - Next.js project with App Router - TypeScript configured - Understanding of HTTP methods and status codes @@ -11,9 +13,11 @@ Create a new API endpoint in Next.js with proper TypeScript typing, validation, ## Steps ### 1. Create API Route File + Create `src/app/api/{endpoint}/route.ts`: + ```typescript -import { NextRequest, NextResponse } from 'next/server' +import { NextRequest, NextResponse } from 'next/server'; // Define request/response types interface RequestBody { @@ -29,72 +33,65 @@ export async function GET(request: NextRequest) { // Handle GET request logic const data: ResponseData = { // Your response data - } - - return NextResponse.json(data, { status: 200 }) + }; + + return NextResponse.json(data, { status: 200 }); } catch (error) { - console.error('API Error:', error) - return NextResponse.json( - { error: 'Internal server error' }, - { status: 500 } - ) + console.error('API Error:', error); + return NextResponse.json({ error: 'Internal server error' }, { status: 500 }); } } export async function POST(request: NextRequest) { try { - const body: RequestBody = await request.json() - + const body: RequestBody = await request.json(); + // Validate request body if (!body) { - return NextResponse.json( - { error: 'Request body is required' }, - { status: 400 } - ) + return NextResponse.json({ error: 'Request body is required' }, { status: 400 }); } - + // Handle POST request logic const data: ResponseData = { // Your response data - } - - return NextResponse.json(data, { status: 201 }) + }; + + return NextResponse.json(data, { status: 201 }); } catch (error) { - console.error('API Error:', error) - return NextResponse.json( - { error: 'Internal server error' }, - { status: 500 } - ) + console.error('API Error:', error); + return NextResponse.json({ error: 'Internal server error' }, { status: 500 }); } } ``` ### 2. Add Request Validation (Optional) + Install and use Zod for validation: + ```bash npm install zod ``` ```typescript -import { z } from 'zod' +import { z } from 'zod'; const requestSchema = z.object({ name: z.string().min(1), email: z.string().email(), -}) +}); export async function POST(request: NextRequest) { try { - const body = await request.json() - const validatedData = requestSchema.parse(body) - + const body = await request.json(); + const validatedData = requestSchema.parse(body); + // Use validatedData safely } catch (error) { if (error instanceof z.ZodError) { return NextResponse.json( { error: 'Invalid request data', details: error.errors }, - { status: 400 } - ) + { status: 400 }, + ); } // Handle other errors } @@ -102,36 +99,39 @@ export async function POST(request: NextRequest) { ``` ### 3. Create API Client Helper + Create `src/lib/api-client.ts`: + ```typescript class ApiError extends Error { - constructor(public status: number, message: string) { - super(message) - this.name = 'ApiError' + constructor( + public status: number, + message: string, + ) { + super(message); + this.name = 'ApiError'; } } -export async function apiCall( - url: string, - options?: RequestInit -): Promise { +export async function apiCall(url: string, options?: RequestInit): Promise { const response = await fetch(url, { headers: { 'Content-Type': 'application/json', ...options?.headers, }, ...options, - }) + }); if (!response.ok) { - throw new ApiError(response.status, `HTTP error! status: ${response.status}`) + throw new ApiError(response.status, `HTTP error! status: ${response.status}`); } - return response.json() + return response.json(); } ``` ### 4. Use in Components + ```typescript 'use client' @@ -164,6 +164,7 @@ export function ExampleComponent() { ``` ## Validation Checklist + - [ ] API route file created in correct location - [ ] Proper TypeScript types defined - [ ] Error handling implemented @@ -173,9 +174,10 @@ export function ExampleComponent() { - [ ] Error cases handled gracefully ## Best Practices + - Use proper HTTP status codes - Implement consistent error response format - Add request validation for security - Log errors for debugging - Consider rate limiting for production -- Document API endpoints \ No newline at end of file +- Document API endpoints diff --git a/expansion-packs/bmad-nextjs-fullstack/tasks/setup-from-template.md b/expansion-packs/bmad-nextjs-fullstack/tasks/setup-from-template.md index 76b5ee7f..a57463e8 100644 --- a/expansion-packs/bmad-nextjs-fullstack/tasks/setup-from-template.md +++ b/expansion-packs/bmad-nextjs-fullstack/tasks/setup-from-template.md @@ -1,9 +1,11 @@ # Setup Project from nextjs-new-app Template ## Task Overview + Initialize a new Feature-Based Architecture project using the pre-configured `nextjs-new-app` template with Next.js 15+, TypeScript, Tailwind CSS 4.x, and development tooling. ## Prerequisites + - Node.js 20.10.0+ installed - pnpm (recommended) or npm package manager - Git for version control @@ -12,6 +14,7 @@ Initialize a new Feature-Based Architecture project using the pre-configured `ne ## Steps ### 1. Clone Template Repository + ```bash # Clone the nextjs-new-app template git clone https://github.com/marciobarroso/nextjs-new-app.git {project_name} @@ -25,6 +28,7 @@ git commit -m "Initial commit from nextjs-new-app template" ``` ### 2. Install Dependencies + ```bash # Install using pnpm (recommended by template) pnpm install @@ -34,7 +38,9 @@ pnpm install ``` ### 3. Configure Project Details + Update `package.json`: + ```json { "name": "{project_name}", @@ -45,6 +51,7 @@ Update `package.json`: ``` ### 4. Set Up Feature-Based Architecture Structure + ```bash # Create the Feature-Based Architecture directories mkdir -p app/\(features\) @@ -60,122 +67,134 @@ mkdir -p app/shared/lib ``` ### 5. Implement BaseController Foundation + Create `app/shared/core/base-controller.ts`: + ```typescript -import { z } from 'zod' -import { NextRequest, NextResponse } from 'next/server' +import { z } from 'zod'; +import { NextRequest, NextResponse } from 'next/server'; export abstract class BaseController { - protected dbClient: any - protected schema?: z.ZodSchema + protected dbClient: any; + protected schema?: z.ZodSchema; constructor(dbClient: any, schema?: z.ZodSchema) { - this.dbClient = dbClient - this.schema = schema + this.dbClient = dbClient; + this.schema = schema; } // Standard CRUD operations async getAll(request: NextRequest): Promise { try { - const { searchParams } = new URL(request.url) - const query = searchParams.get('query') - const page = parseInt(searchParams.get('page') || '1') - const limit = parseInt(searchParams.get('limit') || '20') + const { searchParams } = new URL(request.url); + const query = searchParams.get('query'); + const page = parseInt(searchParams.get('page') || '1'); + const limit = parseInt(searchParams.get('limit') || '20'); - const filter = this.buildSearchFilter(query) + const filter = this.buildSearchFilter(query); // Implement database-specific query here - - return NextResponse.json({ - data: [], + + return NextResponse.json({ + data: [], pagination: { page, limit, total: 0, totalPages: 0 }, - success: true - }) + success: true, + }); } catch (error) { return NextResponse.json( { error: 'Failed to fetch records', success: false }, - { status: 500 } - ) + { status: 500 }, + ); } } - async getById(request: NextRequest, { params }: { params: { id: string } }): Promise { + async getById( + request: NextRequest, + { params }: { params: { id: string } }, + ): Promise { try { // Implement database-specific findById here - return NextResponse.json({ data: null, success: true }) + return NextResponse.json({ data: null, success: true }); } catch (error) { return NextResponse.json( { error: 'Failed to fetch record', success: false }, - { status: 500 } - ) + { status: 500 }, + ); } } async create(request: NextRequest): Promise { try { - const body = await request.json() - + const body = await request.json(); + if (this.schema) { - const validatedData = this.schema.parse(body) + const validatedData = this.schema.parse(body); // Implement database-specific create here } - - return NextResponse.json({ data: null, success: true }, { status: 201 }) + + return NextResponse.json({ data: null, success: true }, { status: 201 }); } catch (error) { if (error instanceof z.ZodError) { return NextResponse.json( { error: 'Validation failed', details: error.errors, success: false }, - { status: 400 } - ) + { status: 400 }, + ); } return NextResponse.json( { error: 'Failed to create record', success: false }, - { status: 500 } - ) + { status: 500 }, + ); } } - async update(request: NextRequest, { params }: { params: { id: string } }): Promise { + async update( + request: NextRequest, + { params }: { params: { id: string } }, + ): Promise { try { - const body = await request.json() - + const body = await request.json(); + if (this.schema) { - const validatedData = this.schema.partial().parse(body) + const validatedData = this.schema.partial().parse(body); // Implement database-specific update here } - - return NextResponse.json({ data: null, success: true }) + + return NextResponse.json({ data: null, success: true }); } catch (error) { if (error instanceof z.ZodError) { return NextResponse.json( { error: 'Validation failed', details: error.errors, success: false }, - { status: 400 } - ) + { status: 400 }, + ); } return NextResponse.json( { error: 'Failed to update record', success: false }, - { status: 500 } - ) + { status: 500 }, + ); } } - async delete(request: NextRequest, { params }: { params: { id: string } }): Promise { + async delete( + request: NextRequest, + { params }: { params: { id: string } }, + ): Promise { try { // Implement database-specific delete here - return NextResponse.json({ success: true, message: 'Record deleted successfully' }) + return NextResponse.json({ success: true, message: 'Record deleted successfully' }); } catch (error) { return NextResponse.json( { error: 'Failed to delete record', success: false }, - { status: 500 } - ) + { status: 500 }, + ); } } // Abstract method for search filtering - protected abstract buildSearchFilter(query: string | null): Record + protected abstract buildSearchFilter(query: string | null): Record; } ``` ### 6. Add Zod for Schema Validation + ```bash # Install Zod for schema validation pnpm add zod @@ -183,7 +202,9 @@ pnpm add zod ``` ### 7. Configure Environment Variables + Create `.env.local`: + ```env # Database Configuration (customize based on your choice) DATABASE_URL="your-database-url" @@ -196,7 +217,9 @@ NEXT_PUBLIC_APP_VERSION="1.0.0" ``` ### 8. Update TypeScript Configuration + The template already provides optimal TypeScript configuration, but you can extend `tsconfig.json` if needed: + ```json { "compilerOptions": { @@ -210,6 +233,7 @@ The template already provides optimal TypeScript configuration, but you can exte ``` ### 9. Test the Setup + ```bash # Run development server pnpm dev @@ -229,6 +253,7 @@ pnpm build ``` ### 10. Initialize Git Repository + ```bash # Add remote repository (replace with your repository URL) git remote add origin https://github.com/yourusername/{project_name}.git @@ -249,6 +274,7 @@ git push -u origin main ``` ## Validation Checklist + - [ ] Template repository successfully cloned - [ ] Dependencies installed without errors - [ ] Development server runs on http://localhost:3000 @@ -261,6 +287,7 @@ git push -u origin main - [ ] Git repository initialized and connected ## Template Features Already Configured + - ✅ Next.js 15.5.3 with App Router - ✅ React 19.1.0 with latest features - ✅ TypeScript 5 with strict configuration @@ -274,6 +301,7 @@ git push -u origin main - ✅ Internationalization setup ## Next Steps After Setup + 1. Plan your first business domain feature 2. Implement your chosen database integration (Prisma, TypeORM, Mongoose, etc.) 3. Create your first feature following Feature-Based Architecture @@ -285,6 +313,7 @@ git push -u origin main ## Database Integration Examples ### For Prisma (PostgreSQL) + ```bash pnpm add prisma @prisma/client pnpm add -D prisma @@ -292,6 +321,7 @@ npx prisma init ``` ### For TypeORM (SQL databases) + ```bash pnpm add typeorm reflect-metadata pnpm add pg # for PostgreSQL @@ -299,9 +329,10 @@ pnpm add pg # for PostgreSQL ``` ### For Mongoose (MongoDB) + ```bash pnpm add mongoose pnpm add -D @types/mongoose ``` -The `nextjs-new-app` template provides an excellent foundation for Feature-Based Architecture, and this setup process will get you ready to build scalable, maintainable Next.js applications following Domain-Driven Design principles. \ No newline at end of file +The `nextjs-new-app` template provides an excellent foundation for Feature-Based Architecture, and this setup process will get you ready to build scalable, maintainable Next.js applications following Domain-Driven Design principles. diff --git a/expansion-packs/bmad-nextjs-fullstack/tasks/setup-nextjs-project.md b/expansion-packs/bmad-nextjs-fullstack/tasks/setup-nextjs-project.md index b4077931..ec879d85 100644 --- a/expansion-packs/bmad-nextjs-fullstack/tasks/setup-nextjs-project.md +++ b/expansion-packs/bmad-nextjs-fullstack/tasks/setup-nextjs-project.md @@ -1,9 +1,11 @@ # Setup Next.js Project ## Task Overview + Initialize a new Next.js project with TypeScript, Tailwind CSS, ESLint, and Prettier configuration. ## Prerequisites + - Node.js 18+ installed - npm or yarn package manager - Git for version control @@ -11,19 +13,23 @@ Initialize a new Next.js project with TypeScript, Tailwind CSS, ESLint, and Pret ## Steps ### 1. Create Next.js Project + ```bash npx create-next-app@latest {project_name} --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" cd {project_name} ``` ### 2. Install Additional Dependencies + ```bash npm install --save-dev prettier prettier-plugin-tailwindcss @types/node npm install lucide-react clsx tailwind-merge ``` ### 3. Configure Prettier + Create `.prettierrc.json`: + ```json { "semi": false, @@ -36,7 +42,9 @@ Create `.prettierrc.json`: ``` ### 4. Update ESLint Configuration + Extend `.eslintrc.json`: + ```json { "extends": ["next/core-web-vitals", "prettier"], @@ -48,7 +56,9 @@ Extend `.eslintrc.json`: ``` ### 5. Configure TypeScript + Update `tsconfig.json` for strict mode: + ```json { "compilerOptions": { @@ -61,7 +71,9 @@ Update `tsconfig.json` for strict mode: ``` ### 6. Set up Scripts + Add to `package.json`: + ```json { "scripts": { @@ -73,6 +85,7 @@ Add to `package.json`: ``` ## Validation Checklist + - [ ] Next.js project created with TypeScript - [ ] Tailwind CSS configured and working - [ ] ESLint and Prettier configured @@ -81,6 +94,7 @@ Add to `package.json`: - [ ] Project builds without errors ## Next Steps + - Set up folder structure - Configure environment variables -- Create initial components \ No newline at end of file +- Create initial components diff --git a/expansion-packs/bmad-nextjs-fullstack/templates/api-route-template.yaml b/expansion-packs/bmad-nextjs-fullstack/templates/api-route-template.yaml index 1bf7ae21..38c2d2c7 100644 --- a/expansion-packs/bmad-nextjs-fullstack/templates/api-route-template.yaml +++ b/expansion-packs/bmad-nextjs-fullstack/templates/api-route-template.yaml @@ -150,4 +150,4 @@ instructions: | 5. Implement the business logic for each HTTP method 6. Remove unused HTTP methods 7. Add proper error handling and logging - 8. Consider authentication and authorization if needed \ No newline at end of file + 8. Consider authentication and authorization if needed diff --git a/expansion-packs/bmad-nextjs-fullstack/templates/base-controller-template.yaml b/expansion-packs/bmad-nextjs-fullstack/templates/base-controller-template.yaml index a74ada0a..fc83884f 100644 --- a/expansion-packs/bmad-nextjs-fullstack/templates/base-controller-template.yaml +++ b/expansion-packs/bmad-nextjs-fullstack/templates/base-controller-template.yaml @@ -90,4 +90,4 @@ instructions: | 4. Implement the buildSearchFilter method based on your database 5. Add custom business logic methods as needed 6. Ensure the schema.ts file exists with {EntityName}Schema and {EntityName}Model - 7. Consider adding custom validation and processing hooks \ No newline at end of file + 7. Consider adding custom validation and processing hooks diff --git a/expansion-packs/bmad-nextjs-fullstack/templates/component-template.yaml b/expansion-packs/bmad-nextjs-fullstack/templates/component-template.yaml index 753e295f..5531d00b 100644 --- a/expansion-packs/bmad-nextjs-fullstack/templates/component-template.yaml +++ b/expansion-packs/bmad-nextjs-fullstack/templates/component-template.yaml @@ -38,4 +38,4 @@ instructions: | 3. Implement component logic and styling 4. Add proper TypeScript types 5. Use Tailwind classes for styling - 6. Consider accessibility (a11y) requirements \ No newline at end of file + 6. Consider accessibility (a11y) requirements diff --git a/expansion-packs/bmad-nextjs-fullstack/templates/feature-structure-template.yaml b/expansion-packs/bmad-nextjs-fullstack/templates/feature-structure-template.yaml index 64c9a5e8..4c54e7e9 100644 --- a/expansion-packs/bmad-nextjs-fullstack/templates/feature-structure-template.yaml +++ b/expansion-packs/bmad-nextjs-fullstack/templates/feature-structure-template.yaml @@ -5,7 +5,7 @@ version: 1.0.0 template: | # Feature Structure for ({featureName}) - + ## Directory Structure ``` app/(features)/({featureName})/ @@ -109,7 +109,7 @@ template: | ### Feature Component ({EntityName}List.tsx) ```typescript 'use client' - + import { use{Entities} } from '../hooks/use{Entities}' import { {EntityName}Card } from './{entityName}-card' import { useEffect } from 'react' @@ -171,4 +171,4 @@ instructions: | 7. Create the directory structure following this template 8. Implement each file according to the patterns shown 9. Ensure all imports and references are correctly updated - 10. Test the complete feature integration \ No newline at end of file + 10. Test the complete feature integration diff --git a/expansion-packs/bmad-nextjs-fullstack/workflows/base-controller-implementation.yaml b/expansion-packs/bmad-nextjs-fullstack/workflows/base-controller-implementation.yaml index 5ac44da6..37944064 100644 --- a/expansion-packs/bmad-nextjs-fullstack/workflows/base-controller-implementation.yaml +++ b/expansion-packs/bmad-nextjs-fullstack/workflows/base-controller-implementation.yaml @@ -66,4 +66,4 @@ tasks: - name: type_validation description: Validated type safety across the entire data flow -agents: [base-controller-specialist, typescript-specialist, api-developer, database-specialist] \ No newline at end of file +agents: [base-controller-specialist, typescript-specialist, api-developer, database-specialist] diff --git a/expansion-packs/bmad-nextjs-fullstack/workflows/domain-feature-development.yaml b/expansion-packs/bmad-nextjs-fullstack/workflows/domain-feature-development.yaml index 5487ce07..2664c19d 100644 --- a/expansion-packs/bmad-nextjs-fullstack/workflows/domain-feature-development.yaml +++ b/expansion-packs/bmad-nextjs-fullstack/workflows/domain-feature-development.yaml @@ -85,4 +85,12 @@ tasks: - name: test_suite description: Comprehensive test suite for the feature -agents: [domain-architect, nextjs-architect, base-controller-specialist, typescript-specialist, api-developer, tailwind-designer] \ No newline at end of file +agents: + [ + domain-architect, + nextjs-architect, + base-controller-specialist, + typescript-specialist, + api-developer, + tailwind-designer, + ] diff --git a/expansion-packs/bmad-nextjs-fullstack/workflows/feature-based-project-setup.yaml b/expansion-packs/bmad-nextjs-fullstack/workflows/feature-based-project-setup.yaml index 5c92af6d..fc6dd600 100644 --- a/expansion-packs/bmad-nextjs-fullstack/workflows/feature-based-project-setup.yaml +++ b/expansion-packs/bmad-nextjs-fullstack/workflows/feature-based-project-setup.yaml @@ -62,4 +62,4 @@ tasks: - name: shared_components description: Shared UI components and utility libraries -agents: [domain-architect, nextjs-architect, base-controller-specialist, typescript-specialist] \ No newline at end of file +agents: [domain-architect, nextjs-architect, base-controller-specialist, typescript-specialist] diff --git a/expansion-packs/bmad-nextjs-fullstack/workflows/feature-development.yaml b/expansion-packs/bmad-nextjs-fullstack/workflows/feature-development.yaml index eef92897..0add7a98 100644 --- a/expansion-packs/bmad-nextjs-fullstack/workflows/feature-development.yaml +++ b/expansion-packs/bmad-nextjs-fullstack/workflows/feature-development.yaml @@ -53,4 +53,5 @@ tasks: - name: documentation description: Feature documentation and usage examples -agents: [nextjs-architect, typescript-specialist, tailwind-designer, api-developer, testing-engineer] \ No newline at end of file +agents: + [nextjs-architect, typescript-specialist, tailwind-designer, api-developer, testing-engineer] diff --git a/expansion-packs/bmad-nextjs-fullstack/workflows/nextjs-project-setup.yaml b/expansion-packs/bmad-nextjs-fullstack/workflows/nextjs-project-setup.yaml index 2517a538..6606abeb 100644 --- a/expansion-packs/bmad-nextjs-fullstack/workflows/nextjs-project-setup.yaml +++ b/expansion-packs/bmad-nextjs-fullstack/workflows/nextjs-project-setup.yaml @@ -53,4 +53,4 @@ tasks: - name: env_config description: Environment configuration files -agents: [nextjs-architect, typescript-specialist, tailwind-designer] \ No newline at end of file +agents: [nextjs-architect, typescript-specialist, tailwind-designer]