solid-nextjs

Enforces SOLID and DRY architecture on Next.js 16 projects: source files within `FUSE_SOLID_MAX_LINES` and split by responsibility when cohesion drops, types isolated in `interfaces/` directories (never in components/pages), mandatory JSDoc on exports, and the module/`modules/cores/` directory structure. Requires researching current Next.js/React/Prisma docs (via Context7/Exa with the current year) before writing any code, and grepping for existing utilities before creating new ones.

Provides a dedicated reference guide per SOLID letter (SRP file-splitting, OCP composition/plugin patterns, LSP contract compliance, ISP role-based interfaces, DIP constructor injection/factories) plus 23 ready-to-copy templates covering components, hooks, services, stores, Server Actions, API routes, validators, Prisma singletons, i18n, and queries. This is a cross-cutting code-quality skill, not a feature skill — for the framework APIs themselves see nextjs-16 and its sibling skills.

SOLID Next.js - Modular Architecture

Current Date (CRITICAL)

Today: January 2026 - ALWAYS use the current year for your searches. Search with "2025" or "2026", NEVER with past years.

MANDATORY: Research Before Coding

CRITICAL: Check today's date first, then search documentation and web BEFORE writing any code.

1. Use Context7 to query Next.js/React official documentation
2. Use Exa web search with current year for latest trends
3. Check Vercel Blog of current year for new features
4. Verify package versions for Next.js 16 compatibility

Search queries (replace YYYY with current year):

• Next.js [feature] YYYY best practices
• React 19 [component] YYYY
• TypeScript [pattern] YYYY
• Prisma 7 [feature] YYYY

---

Codebase Analysis (MANDATORY)

Before ANY implementation:

1. Explore project structure to understand architecture
2. Read existing related files to follow established patterns
3. Identify naming conventions, coding style, and patterns used
4. Understand data flow and dependencies

DRY - Reuse or Create Shared (MANDATORY)

Before writing ANY new code:

1. Grep the codebase for similar function names, patterns, or logic
2. Check shared locations: modules/cores/lib/, modules/cores/components/, modules/cores/hooks/
3. If similar code exists → extend/reuse instead of duplicate
4. If code will be used by 2+ features → create it in modules/cores/ directly
5. Extract repeated logic (3+ occurrences) into shared helpers
6. Run npx jscpd ./src --threshold 3 after creating new files

---

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:

1. fuse-ai-pilot:explore-codebase - Analyze project structure and existing patterns
2. fuse-ai-pilot:research-expert - Verify latest docs for all stack technologies
3. mcp__context7__query-docs - Check integration compatibility

After implementation, run fuse-ai-pilot:sniper for validation.

---

Absolute Rules (MANDATORY)

1. Source-file size ceiling

• Source files must not exceed FUSE_SOLID_MAX_LINES - the hook's ceiling is the only authority
• Split by responsibility when cohesion drops (pages delegate to modules, components via composition, one Server Action per concern)

2. Modular Architecture

See references/architecture-patterns.md for complete structure with feature modules and cores directory.

3. JSDoc Mandatory

/**
 * Fetch user by ID from database.
 *
 * @param id - User unique identifier
 * @returns User object or null if not found
 * @throws DatabaseError on connection failure
 */
export async function getUserById(id: string): Promise<User | null>

4. Interfaces Separated

modules/auth/src/
├── interfaces/          # Types ONLY
│   ├── user.interface.ts
│   └── session.interface.ts
├── services/            # NO types here
└── components/          # NO types here

---

SOLID Principles (Detailed Guides)

Each SOLID principle has a dedicated reference guide:

1. references/single-responsibility.md - One class/function = one reason to change

   • Responsibility-based splitting within FUSE_SOLID_MAX_LINES
   • Component composition patterns
   • Next.js page & server action examples

2. references/open-closed.md - Extend via composition, not modification

   • Plugin architecture patterns
   • Provider patterns for multiple implementations
   • Adapter and strategy patterns
   • Adding features without changing existing code

3. references/liskov-substitution.md - Contract compliance & behavioral subtyping

   • Subtypes must be substitutable for base types
   • Exception and return type contracts
   • Testing LSP compliance

4. references/interface-segregation.md - Many focused interfaces beat one fat interface

   • Role-based interfaces
   • Avoiding bloated contracts
   • Client-specific interfaces

5. references/dependency-inversion.md - Depend on abstractions, not implementations

   • Constructor injection patterns
   • Factory patterns for creation
   • IoC containers
   • Easy mocking for tests

See references/solid-principles.md for overview and quick reference.

---

Code Templates

Ready-to-copy code in references/templates/:

Template	Usage
server-component.md	Server Component with data fetching
client-component.md	Client Component with hooks
service.md	Service with dependency injection
hook.md	React hook with state
interface.md	TypeScript interfaces
store.md	Zustand store with persistence
action.md	Server Action with validation
api-route.md	API Route Handler
validator.md	Zod validation schemas
factory.md	Factory pattern
adapter.md	Adapter pattern
error.md	Custom error classes
test.md	Test templates
middleware.md	Auth middleware
prisma.md	Prisma singleton
i18n.md	Feature/global translations
query.md	Database queries (Prisma 7)

---

Response Guidelines

1. Research first - MANDATORY: Search Context7 + Exa before ANY code
2. Show complete code - Working examples, not snippets
3. Explain decisions - Why this pattern over alternatives
4. Include tests - Always suggest test cases
5. Handle errors - Never ignore, use error boundaries
6. Type everything - Full TypeScript, no any
7. Document code - JSDoc for complex functions

---

Forbidden

• ❌ Coding without researching docs first (ALWAYS research)
• ❌ Using outdated APIs without checking current year docs
• ❌ Source files exceeding FUSE_SOLID_MAX_LINES
• ❌ Interfaces in component files
• ❌ Business logic in app/ pages
• ❌ Direct DB calls in components
• ❌ Module importing another module (except cores)
• ❌ 'use client' by default
• ❌ useEffect for data fetching
• ❌ Missing JSDoc on exports
• ❌ any type
• ❌ Barrel exports
• ❌ Duplicating existing utility/helper without Grep search first
• ❌ Copy-pasting logic blocks instead of extracting shared function