React 19 + Next.js 16 + Ant Design — Clean Architecture
Skill for creating and maintaining React 19 + Next.js 16 frontends with feature architecture, Ant Design, and REST integration (.NET or similar).
When to use
- Create or extend Next.js frontend (admin, SaaS, backoffice)
- CRUD, forms, authenticated layout
- Integrate with REST API
- Refactor React components to vertical slice
- Define service, hook, schema, and route patterns
When not to use
- React projects without Next.js.
- Codebases on the Pages Router instead of App Router.
- Projects where Tailwind or Shadcn is the primary design system.
- Applications that use GraphQL instead of REST for data fetching.
Expected structure
src/app/ → routes, layouts, loading, error, not-found (NO business logic)
src/features/ → domains (auth, products, …)
src/shared/ → components, providers, lib (api, auth, env), theme/
UI URLs vs API
| Layer |
Convention |
Example |
| UI routes |
English |
/products, /products/new, /products/:id/edit |
| REST API |
English |
/api/products |
Architecture rules
src/app — Next.js only (thin routes importing pages from features/)src/features/{domain}/ — types, schemas, services, hooks, components, {domain}.page.tsxsrc/shared/ — reusable, no domain logic- HTTP centralized in
shared/lib/api/api-client.ts
process.env only in shared/lib/env/env.ts- Forms: React Hook Form + Zod
- Remote state: TanStack Query
- UI: Ant Design (no Tailwind in MVP)
- Design system in
shared/theme/ — palette, CSS tokens, overrides in theme/styles/antd/
- Drawer/menu:
rootClassName="app-drawer" + CSS .app-drawer .drawer-menu (portaled to body)
- SEO:
shared/lib/seo/metadata.ts + metadata per route; noindex in admin app
- Forbidden:
any, Axios directly in visual components; legacy redirects without need
This skill uses Ant Design as the default design system, matching CleanStack. Do not force Ant Design on projects that already use another design system — adapt the feature structure and patterns instead.
Ant Design + App Router
// src/app/layout.tsx
import { AntdRegistry } from '@ant-design/nextjs-registry';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en-US">
<body>
<AntdRegistry>{children}</AntdRegistry>
</body>
</html>
);
}
Separate provider with ConfigProvider, en_US locale, centralized theme.
Server vs Client Components
'use client' |
Server Component |
| Interactive Ant Design |
Route that only re-exports feature page |
| useRouter, useState, useEffect |
redirect(), metadata |
| TanStack Query, React Hook Form |
Layout without interactivity |
| localStorage, events |
— |
Service pattern
import { apiClient } from '@/shared/lib/api/api-client';
export async function listProducts(): Promise<Product[]> {
return apiClient.get<Product[]>('/api/products');
}
- Services are pure async functions
- Must not use hooks or JSX
Hook pattern
'use client';
import { useQuery } from '@tanstack/react-query';
export function useProducts() {
return useQuery({ queryKey: ['products'], queryFn: listProducts });
}
- Hooks must not return JSX
- Mutations invalidate related query keys
Form pattern
export const productSchema = z.object({
name: z.string().min(1, 'Name is required.'),
price: z.number().positive('Price must be greater than zero.'),
});
Component: useForm + zodResolver + Controller + Ant Design Form.Item.
Test conventions
- Test Zod schemas with
safeParse (Vitest)
- File:
{feature}.schema.test.ts next to the schema
- Do not test Ant Design internal implementation
- Prefer contract tests (schema, mocked service) over UI snapshots
New feature — checklist
- types → 2. schema (+ test) → 3. service → 4. hooks → 5. components → 6. page → 7. route in app/
Anti-patterns
- Business logic in
src/app/page.tsx instead of feature pages.
- Axios calls directly in visual components.
- Scattered
process.env access outside shared/lib/env.
- Mixing Tailwind/Shadcn with Ant Design as co-primary design systems.
- Hooks that return JSX instead of data and handlers.
Reference
Detailed examples in reference.md.
1---2name: react-nextjs-antd-clean-architecture3description: React 19 + Next.js 16 App Router, TypeScript, Ant Design, TanStack Query, Axios, React Hook Form, Zod — Clean Architecture frontend with vertical slice by feature. Use when creating or refactoring Next.js apps, admin panels, SaaS frontends, CRUDs, forms, layouts and frontend architecture.4---56# React 19 + Next.js 16 + Ant Design — Clean Architecture78Skill for creating and maintaining React 19 + Next.js 16 frontends with feature architecture, Ant Design, and REST integration (.NET or similar).910## When to use1112- Create or extend Next.js frontend (admin, SaaS, backoffice)13- CRUD, forms, authenticated layout14- Integrate with REST API15- Refactor React components to vertical slice16- Define service, hook, schema, and route patterns1718## When not to use1920- React projects without Next.js.21- Codebases on the Pages Router instead of App Router.22- Projects where Tailwind or Shadcn is the primary design system.23- Applications that use GraphQL instead of REST for data fetching.2425## Expected structure2627```txt28src/app/ → routes, layouts, loading, error, not-found (NO business logic)29src/features/ → domains (auth, products, …)30src/shared/ → components, providers, lib (api, auth, env), theme/31```3233## UI URLs vs API3435| Layer | Convention | Example |36|---|---|---|37| UI routes | English | `/products`, `/products/new`, `/products/:id/edit` |38| REST API | English | `/api/products` |3940## Architecture rules41421. `src/app` — Next.js only (thin routes importing pages from `features/`)432. `src/features/{domain}/` — types, schemas, services, hooks, components, `{domain}.page.tsx`443. `src/shared/` — reusable, **no** domain logic454. HTTP centralized in `shared/lib/api/api-client.ts`465. `process.env` only in `shared/lib/env/env.ts`476. Forms: **React Hook Form + Zod**487. Remote state: **TanStack Query**498. UI: **Ant Design** (no Tailwind in MVP)509. Design system in `shared/theme/` — palette, CSS tokens, overrides in `theme/styles/antd/`5110. Drawer/menu: `rootClassName="app-drawer"` + CSS `.app-drawer .drawer-menu` (portaled to body)5211. SEO: `shared/lib/seo/metadata.ts` + metadata per route; `noindex` in admin app5312. Forbidden: `any`, Axios directly in visual components; legacy redirects without need5455This skill uses **Ant Design** as the default design system, matching [CleanStack](https://github.com/luismpenholato/clean-stack). Do not force Ant Design on projects that already use another design system — adapt the feature structure and patterns instead.5657## Ant Design + App Router5859```tsx60// src/app/layout.tsx61import { AntdRegistry } from '@ant-design/nextjs-registry';6263export default function RootLayout({ children }: { children: React.ReactNode }) {64 return (65 <html lang="en-US">66 <body>67 <AntdRegistry>{children}</AntdRegistry>68 </body>69 </html>70 );71}72```7374Separate provider with `ConfigProvider`, `en_US` locale, centralized theme.7576## Server vs Client Components7778| `'use client'` | Server Component |79|---|---|80| Interactive Ant Design | Route that only re-exports feature page |81| useRouter, useState, useEffect | redirect(), metadata |82| TanStack Query, React Hook Form | Layout without interactivity |83| localStorage, events | — |8485## Service pattern8687```ts88import { apiClient } from '@/shared/lib/api/api-client';8990export async function listProducts(): Promise<Product[]> {91 return apiClient.get<Product[]>('/api/products');92}93```9495- Services are pure async functions96- **Must not** use hooks or JSX9798## Hook pattern99100```ts101'use client';102103import { useQuery } from '@tanstack/react-query';104105export function useProducts() {106 return useQuery({ queryKey: ['products'], queryFn: listProducts });107}108```109110- Hooks **must not** return JSX111- Mutations invalidate related query keys112113## Form pattern114115```ts116export const productSchema = z.object({117 name: z.string().min(1, 'Name is required.'),118 price: z.number().positive('Price must be greater than zero.'),119});120```121122Component: `useForm` + `zodResolver` + `Controller` + Ant Design `Form.Item`.123124## Test conventions125126- Test Zod schemas with `safeParse` (Vitest)127- File: `{feature}.schema.test.ts` next to the schema128- Do not test Ant Design internal implementation129- Prefer contract tests (schema, mocked service) over UI snapshots130131## New feature — checklist1321331. types → 2. schema (+ test) → 3. service → 4. hooks → 5. components → 6. page → 7. route in app/134135## Anti-patterns136137- Business logic in `src/app/page.tsx` instead of feature pages.138- Axios calls directly in visual components.139- Scattered `process.env` access outside `shared/lib/env`.140- Mixing Tailwind/Shadcn with Ant Design as co-primary design systems.141- Hooks that return JSX instead of data and handlers.142143## Reference144145Detailed examples in [`reference.md`](reference.md).
luismpenholato