nextjs-code-structure_skill

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