Build scalable Next.js apps with a folder structure that stays clean.
A practical App Router architecture using route groups, feature modules, server actions, shared UI, entities, and infrastructure boundaries.
src/
app/
(marketing)/pricing/page.tsx
(auth)/login/page.tsx
(dashboard)/dashboard/page.tsx
api/billing/route.ts
features/
auth/actions/login.ts
billing/queries/getBillingPlans.ts
dashboard/components/DashboardChart.client.tsx
entities/
user/user.permissions.ts
subscription/subscription.utils.ts
shared/ui/Button/Button.tsx
lib/payments/stripe.ts
config/routes.tsWhy this structure works
Every folder has a job, and every import has a direction.
app/
App Router boundaries
Routing, layouts, loading states, error boundaries, and route composition.
features/
Feature-based modules
Product logic grouped by capability: auth, billing, dashboard, and more.
entities/
Entities and domain logic
Shared business models, schemas, permissions, and domain utilities.
shared/
Shared UI layer
Product-neutral components, hooks, utilities, and common API types.
lib/
Infrastructure with lib
Low-level database, auth, payments, email, storage, and HTTP wrappers.
config/
Typed configuration
Routes, constants, environment helpers, and app-level settings.
Server vs client components
Server components fetch data through feature queries. Interactive pieces use the `.client.tsx` suffix, keeping client boundaries visible in code review.
DashboardStats.tsx
DashboardChart.client.tsx
Architecture rules
- app composes routes but does not own product logic
- features own server actions, queries, services, and local components
- entities model reusable domain concepts
- shared stays product-neutral
- lib wraps infrastructure and third-party services
- imports flow inward from routes to features to entities/shared/lib
Full folder tree, working pages, real examples.
Explore auth forms, billing plans, dashboard data, server actions, API routes, domain permissions, and mock infrastructure without connecting real services.