nextjs-architecture
Structure Next.js projects with Feature-Sliced Design layers, domain-grouped slices, and strict import hierarchy. Use when organizing features into FSD layers, enforcing slice boundaries, or keeping page.tsx thin. (triggers: src/features/**, src/entities/**, src/widgets/**, FSD, Feature Sliced Design, slices, segments)
Best use case
nextjs-architecture is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Structure Next.js projects with Feature-Sliced Design layers, domain-grouped slices, and strict import hierarchy. Use when organizing features into FSD layers, enforcing slice boundaries, or keeping page.tsx thin. (triggers: src/features/**, src/entities/**, src/widgets/**, FSD, Feature Sliced Design, slices, segments)
Teams using nextjs-architecture should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/nextjs-architecture/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How nextjs-architecture Compares
| Feature / Agent | nextjs-architecture | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Structure Next.js projects with Feature-Sliced Design layers, domain-grouped slices, and strict import hierarchy. Use when organizing features into FSD layers, enforcing slice boundaries, or keeping page.tsx thin. (triggers: src/features/**, src/entities/**, src/widgets/**, FSD, Feature Sliced Design, slices, segments)
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Architecture (Feature-Sliced Design) ## **Priority: P2 (MEDIUM)** Adopt **Feature-Sliced Design (FSD)** for scalable applications. **Warning**: FSD introduces boilerplate. Use it only if the project is expected to grow significantly (e.g., 20+ features). For smaller projects, a simple module-based structure is preferred. ## Workflow: Create a New Feature Slice 1. **Create feature folder** — `src/features/auth/login/` with `ui/`, `model/`, `api/` segments. 2. **Add public API** — Export via `src/features/auth/login/index.ts`. 3. **Wire into page** — Import the feature widget in `app/login/page.tsx` (thin page). 4. **Verify imports** — Ensure no upward or cross-slice imports violate the layer hierarchy. ## Layer Hierarchy `App (app/) -> Widgets -> Features -> Entities -> Shared` See [implementation examples](references/implementation.md) for a thin page example. ## Strategy 1. **RSC Boundaries**: Enforce strict serialization rules for props passed from Server to Client. See [RSC Boundaries & Serialization](references/RSC_BOUNDARIES.md). 2. **App Layer is Thin**: The `app/` directory (App Router) is **only** for Routing. - _Rule_: `page.tsx` should only import Widgets/Features. No business logic (`useEffect`, `fetch`) directly in pages. 3. **Slices over Types**: Group code by **Business Domain** (User, Product, Cart), not by File Type (Components, Hooks, Utils). - _Bad_: `src/components/LoginForm.tsx`, `src/hooks/useLogin.ts` - _Good_: `src/features/auth/login/` containing both. 4. **Layer Hierarchy**: Code can only import from _layers below it_. - `App` -> `Widgets` -> `Features` -> `Entities` -> `Shared`. 5. **Avoid Excessive Entities**: Do not preemptively create Entities. - _Rule_: Start logic in `Features` or `Pages`. Move to `Entities` **only** when data/logic is strictly reused across multiple differing features. - _Rule_: Simple CRUD belongs in `shared/api`, not `entities`. 6. **Standard Segments**: Use standard segment names within slices. - `ui` (Components), `model` (State/actions), `api` (Data fetching), `lib` (Helpers), `config` (Constants). - _Avoid_: `components`, `hooks`, `services` as segment names. ## Structure Reference For the specific directory layout and layer definitions, see the reference documentation. - [**FSD Folder Structure**](references/fsd-structure.md) - [**Bundling & Compatibility**](references/BUNDLING.md) - [**Runtime Selection (Edge/Node)**](references/RUNTIME_SELECTION.md) - [**Debug Tricks & MCP**](references/DEBUG_TRICKS.md) ## Architecture Checklist (Mandatory) - [ ] **Layer Imports**: Does any layer import from a layer ABOVE it? (App > Widgets > Features > Entities > Shared) - [ ] **Page Logic**: Is `page.tsx` thin, containing only Widgets/Features and zero `useEffect`/`fetch`? - [ ] **RSC Boundaries**: Are Server Components isolated from Client Components with proper 'use client' boundaries? - [ ] **Public API**: Is all access to a slice performed via the top-level `index.ts` (public API)? - [ ] **Cross-Slice**: Do slices within the same layer (e.g., two features) import from each other directly? (Prohibited) - **Server Actions**: Place them in the `model/` folder of a Feature (e.g., `features/auth/model/actions.ts`). - **Data Access (DAL)**: Place logic in the `model/` folder of an Entity (e.g., `entities/user/model/dal.ts`). - **UI Components**: Base UI (shadcn) belongs in `shared/ui`. Feature-specific UI belongs in `features/*/ui`. ## Anti-Patterns - **No cross-slice imports**: Slices in the same layer must not import from each other directly. - **No business logic in `page.tsx`**: Pages import Widgets/Features only; zero `useEffect`/`fetch`. - **No file-type folders**: Group by domain (`features/auth/`), not type (`components/`, `hooks/`). - **No premature Entity creation**: Start in Features; move to Entities only on strict reuse.
Related Skills
spring-boot-architecture
Structure Spring Boot 3+ projects with feature packaging and clean layering. Use when structuring Spring Boot 3 projects, defining layers, or applying architecture patterns. (triggers: pom.xml, build.gradle, structure, layering, dto, controller, @RestController, @Service, @Repository, @Entity, @Bean, @Configuration)
react-native-architecture
Structure React Native projects with feature-first organization and separation of concerns. Use when structuring a React Native project or applying clean architecture patterns. (triggers: src/**/*.tsx, src/**/*.ts, app.json, feature, module, directory structure, separation of concerns, Expo, React Navigation, StyleSheet.create, react-native, mobile architecture)
nextjs-upgrade
Next.js version migrations using official guides and codemods. Use when migrating a Next.js project to a new major version using codemods. (triggers: package.json, next upgrade, migration guide, codemod)
nextjs-tooling
Configure Next.js build tooling, deployment, and developer workflow. Use when setting up Turbopack, standalone Docker output, bundle analysis, CI caching, environment variable validation, or ESLint integration for Next.js projects. (triggers: next.config.js, package.json, Dockerfile, turbopack, output, standalone, lint, telemetry)
nextjs-testing
Write Jest or Vitest unit tests with React Testing Library and Playwright E2E tests for Next.js projects. Use when testing components with RTL, mocking APIs with MSW, or creating Playwright user flow tests. (triggers: **/*.test.{ts,tsx}, cypress/**, tests/**, jest.config.*, vitest, playwright, msw, testing-library)
nextjs-styling
Implement zero-runtime CSS with Tailwind, CSS Modules, and the cn() utility for RSC-compatible styling in Next.js. Use when choosing a styling library, creating dynamic class utilities, or optimizing fonts with next/font. (triggers: **/*.css, tailwind.config.ts, **/components/ui/*.tsx, tailwind, css modules, styled-components, clsx, cn)
nextjs-state-management
Apply best practices for managing URL, server, and client state in Next.js applications. Use when choosing between URL params, SWR/TanStack Query, Zustand, or Context for state, or when fixing hydration mismatches from localStorage. (triggers: **/hooks/*.ts, **/store.ts, **/components/*.tsx, useState, useContext, zustand, redux)
nextjs-server-components
Build async React Server Components and place 'use client' boundaries at leaf nodes for interactivity in Next.js App Router. Use when deciding RSC vs Client Component, composing server data into client wrappers, or fixing hydration errors. (triggers: app/**/*.tsx, src/app/**/*.tsx, app/**/*.jsx, src/app/**/*.jsx, use client, Server Component, Client Component, hydration)
nextjs-server-actions
Implement mutations, forms, and RPC-style calls with Next.js Server Actions. Use when implementing Server Actions, form mutations, or RPC-style data mutations in Next.js. (triggers: app/**/actions.ts, src/app/**/actions.ts, app/**/*.tsx, src/app/**/*.tsx, use server, Server Action, revalidatePath, useFormStatus)
nextjs-security
Secure Next.js App Router with middleware auth, Server Action validation, CSP headers, and taint APIs. Use when adding authentication middleware, validating Server Action inputs with Zod, or preventing secret leakage to client bundles. (triggers: app/**/actions.ts, middleware.ts, action, boundary, sanitize, auth, jose)
nextjs-rendering
Select and implement SSG, SSR, ISR, Streaming, or Partial Prerendering strategies in Next.js App Router. Use when choosing a rendering mode for a page, configuring generateStaticParams, or enabling PPR. (triggers: **/page.tsx, **/layout.tsx, generateStaticParams, dynamic, dynamicParams, PPR, streaming)
nextjs-pages-router
Implement Pages Router data fetching with getServerSideProps, getStaticProps, and API routes in Next.js legacy projects. Use when working in a pages/ directory project, adding SSR/SSG data fetching, or creating API routes. (triggers: pages/**/*.tsx, pages/**/*.ts, Pages Router, getServerSideProps, getStaticProps, _app, useRouter)