/solid-nextjs

name: solid-nextjs
description: Use when applying SOLID principles to Next.js architecture — modular structure, file size limits, interface separation, JSDoc.
version: 1.0.0
user-invocable: true
references: references/solid-principles.md, references/single-responsibility.md, references/open-closed.md, references/liskov-substitution.md, references/interface-segregation.md, references/dependency-inversion.md, references/architecture-patterns.md, references/templates/server-component.md, references/templates/client-component.md, references/templates/service.md, references/templates/hook.md, references/templates/interface.md, references/templates/store.md, references/templates/action.md, references/templates/api-route.md, references/templates/validator.md, references/templates/factory.md, references/templates/adapter.md, references/templates/error.md, references/templates/test.md, references/templates/middleware.md, references/templates/prisma.md, references/templates/i18n.md, references/templates/query.md

<objective> 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. </objective>

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. **`ref