playbooks

home / skills / ahmed6ww / ax-agents / nextjs-code-structure

nextjs-code-structure skill

/nextjs-code-structure

This skill guides structuring Next.js apps using Feature-Sliced Design and Server Components to improve scalability and maintainability.

npx playbooks add skill ahmed6ww/ax-agents --skill nextjs-code-structure

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.0 KB
---
name: nextjs-structure
description: Architect scalable Next.js applications using Feature-Sliced Design and Server Component patterns.
version: 1.0.0
---

# Next.js Enterprise Standards

## 1. Feature-Sliced Directory Structure
Avoid a monolithic `components/` folder. Structure the frontend to mirror the backend domain boundaries.
**Adopt Structure by Feature [26]:**

```text
src/
  features/
    auth/
      components/    # UI specifically for Auth
      hooks/         # Auth logic
      actions.ts     # Server Actions for Auth
    billing/
      components/
      types/
  ui/                # Shared, domain-agnostic UI (Buttons, Inputs)
  app/               # Only for Routing and Layouts (Thin layer) 
Why: Code refactoring becomes easier because feature-specific logic is colocated. You can delete the features/billing folder and know you removed 100% of the billing code.
2. Server vs. Client Component Boundaries
• Default to Server: All components are Server Components by default. They can access the DB directly (acting as the Presentation Layer).
• Client Boundaries: Push use client as far down the tree as possible (leaves).
• Data Fetching: Do NOT fetch data in useEffect (client). Fetch data in Server Components and pass it down as props. This acts as the "Controller" in MVC terms, preparing data for the View.
3. The Anti-Corruption Layer (API Integration)
Do not call fetch('/api/users') directly inside UI components.
• Pattern: Use a Gateway/Service Layer on the frontend.
• Implementation: Create a typed SDK or generic HTTP wrapper (e.g., api.users.get()).
• Why: This acts as a "Gateway" to external resources. If the backend API schema changes, you update the Gateway, not 500 UI components.
4. State Management
• URL as State: For 100M+ users, rely on URL parameters for filter/sort state (Client Session State). This allows shareable links and reduces complex Redux/Context overhead.
• Server State: Use React Query or SWR for caching server data on the client. Treat it as a sync mechanism, not local state management.

Overview

This skill teaches how to architect scalable Next.js applications using Feature-Sliced Design and Server Component patterns. It focuses on folder organization by domain, clear server/client boundaries, a frontend gateway for APIs, and pragmatic state strategies for large-scale apps. The outcome is maintainable, easy-to-refactor codebases that scale with team size and traffic.

How this skill works

The skill inspects and prescribes a feature-based src/ layout where domain features own their components, hooks, and server actions, while ui/ holds shared, domain-agnostic primitives. It enforces Server Components by default, pushing client components to the leaf nodes, and recommends fetching data on the server and passing props down. It also establishes an anti-corruption gateway layer for API calls and practical rules for using URL, React Query, or SWR for state.

When to use it

  • Building large Next.js apps with multiple domains or teams
  • When you need predictable boundaries for safe refactors and feature removal
  • If you want to favor Server Components for performance and security
  • When API schemas change frequently and you need a single update surface
  • For apps expecting very high traffic or tens of millions of users

Best practices

  • Organize code by feature: src/features/<domain>/ with components, hooks, and actions colocated
  • Keep app/ minimal: only routing and high-level layouts, no business logic
  • Default to Server Components; add 'use client' only on leaf UI where interactivity is required
  • Fetch data on the server and pass as props; avoid useEffect-driven data loads for primary data
  • Create a typed gateway/service layer (api.users.get()) instead of direct fetch calls in UI
  • Use URL parameters for shareable filter/sort state and React Query/SWR for server caching

Example use cases

  • An enterprise billing app where the billing feature folder contains all related UI, hooks, and server actions
  • A marketplace where server-rendered product pages fetch data on the server and client components handle small interactive widgets
  • A multi-team platform that uses a typed frontend SDK to shield UI from backend API changes
  • A high-traffic analytics dashboard relying on URL-driven filters and React Query for caching

FAQ

Why default to Server Components?

Server Components reduce client bundle size, allow secure server-side data access, and centralize data fetching for consistent rendering.

How do I handle UI that needs client-side interactivity?

Push 'use client' components to the leaves. Keep the interactive component small and receive server-prepared props to minimize client work.