Next Starter

App Router-based Next.js 16 starter kit with DDD architecture, TanStack Query, atomic component structure, Storybook 10, Tailwind CSS 4, and lint automation already wired in.

Features

• Next.js 16 with TypeScript, React 19, server components, and server actions.
• DDD/Clean Architecture: Domain-driven design with Domain, Application, and Infrastructure layers.
• TanStack Query v5: Modern data synchronization with mutations for server actions.
• Digital Agency Design System: Government-standard accessible UI components.
• Storybook 10: Component workbench for atoms, organisms, and pages.
• Tailwind CSS 4: Utility-first styling with SCSS modules support.
• State & Data: Recoil state management, SWR data fetching, TanStack Query mutations.
• Tooling: ESLint 9, Stylelint, Prettier, and Husky + lint-staged pre-commit hooks.

Requirements

• Node.js 24.11.0 (see .node-version; use nvm, fnm, etc. to align locally).
• pnpm 10+ (package manager).
• Install dependencies with pnpm install.

Develop

1. Run npm run dev to start the Next.js dev server at http://localhost:3000.
2. Edit routes in src/app/… or components in src/components/…; hot reload is enabled by default.

Scripts

• npm run dev – Next.js development server with hot refresh.
• npm run build – Production bundle (uses the Webpack-based builder configured for Next 16).
• npm run start – Serve the latest production build locally.
• npm run lint – ESLint across the project with --max-warnings=0.
• npm run storybook – Launch Storybook at http://localhost:6006.
• npm run build-storybook – Generate the static Storybook build into storybook-static/.

Project Layout

src/
├── app/                           # Next.js App Router (Presentation)
│   ├── layout.tsx                 # Root layout
│   ├── providers.tsx              # QueryClient, HeroUI providers
│   ├── inquiry/                   # Inquiry pages
│   └── photo-content/             # PhotoContent pages
│
├── features/                      # Feature modules (Presentation)
│   ├── inquiry/
│   │   ├── actions.ts             # Server Actions
│   │   └── components/            # Feature-specific UI
│   ├── photo-content/
│   │   └── actions.ts
│   ├── dashboard/
│   └── common/
│       └── notifications/         # Toast notifications
│
├── hooks/                         # Custom React hooks (Presentation)
│   ├── mutations/                 # TanStack Query mutations
│   └── queries/                   # TanStack Query queries
│
├── components/                    # Shared UI components
│   ├── ui/                        # Digital Agency Design System
│   └── layout/                    # Layout components
│
└── server/                        # Backend layers (DDD)
    ├── domain/                    # Domain Layer
    │   ├── models/                # Entities (Inquiry, PhotoContent)
    │   ├── value-objects/         # Value Objects (Email, Status)
    │   ├── repositories/          # Repository interfaces
    │   └── services/              # Domain services
    │
    ├── application/               # Application Layer
    │   ├── use-cases/             # Business logic orchestration
    │   └── dtos/                  # Data Transfer Objects
    │
    └── infrastructure/            # Infrastructure Layer
        ├── repositories/          # Repository implementations
        ├── mappers/               # Domain ↔ DTO mappers
        ├── di/                    # Dependency injection
        └── cache/                 # TanStack Query cache keys

public/                            # Static assets
.storybook/                        # Storybook configuration

Styling & UI System

• Tailwind CSS 4 powers utility classes; extend design tokens in tailwind.config.ts.
• Component styles stay next to their implementation (Component.tsx, Component.scss, Component.stories.ts).
• src/app/providers.tsx wraps the tree with NextUIProvider so HeroUI/NextUI components share theme state.
• The Twemoji atom serves emoji as SVGs via CDN, and Font Awesome is ready for icon usage in pages.
• Uses Digital Agency Design System for accessible and government-standard UI components.
• Icons and illustrations are provided by the Digital Agency Design System.

Storybook & Demo Content

• Stories follow the Component.stories.ts naming convention inside each component folder.
• Run npm run storybook for the component workbench; it mirrors the page at src/app/story/page.tsx for quick smoke tests.
• Use Storybook controls and links addons to explore different states before wiring live data.

Linting & Formatting

• Husky’s pre-commit hook executes lint-staged: ESLint for TS/JS, Stylelint for SCSS, and Prettier formatting.
• Run npm run lint before pushing to catch import order and TypeScript issues early.
• For manual formatting, run npx prettier --write and npx stylelint src/**/*.{css,scss,sass} as needed.

Deployment

• Build with npm run build, then verify locally via npm run start.
• Target Node 24.11.0 in CI/CD; keeping local versions aligned avoids build drift.
• Deploy to Vercel or any Node host that supports Next.js 16.