new-feature-nextjs

new-feature-nextjs

Do not open any file for editing until all 6 steps are completed.

---

Step 1 — Define the feature surface

Write the surface in plain text before any code:

Feature name: users
Routes: /users (list), /users/[id] (detail)
Mutations: createUser, updateUser, deleteUser
Reads: getUser(id), listUsers()
Cache tags: user(id), userList(), userOrders(userId)

If you can't fill all 5 lines in 2 sentences each, the scope is unclear — clarify with the user first.

---

Step 2 — Pick the folder location (Principle C1)

Scope	Location
Reusable everywhere (Button, Input)	src/components/ui/
Belongs to one business domain	src/features/<domain>/
Pure helper used in 2+ features	src/lib/<area>/
Used in exactly one place	colocate next to that place (Principle C6)

For a new feature, default to src/features/<domain>/ with this structure:

src/features/<domain>/
├── components/         # JSX (server + client)
├── actions.ts          # Server Actions
├── repository.ts       # Drizzle adapter (only file importing drizzle-orm)
├── protocols.ts        # Repository protocol/interface
├── schema.ts           # Zod schemas
└── store.ts            # Zustand (only if genuinely needed)

---

Step 3 — Add cache tags FIRST (Principle D1)

Before writing any Server Action, add the tags to src/lib/cache/tags.ts:

// src/lib/cache/tags.ts
export const tags = {
  // ... existing tags
  user: (id: string) => `user:${id}` as const,
  userList: () => 'user:list' as const,
} as const;

Rule: zero revalidateTag('magic-string') in the new feature. Every invalidation goes through the typed DSL. Typos must be compile errors.

---

Step 4 — Build bottom-up (parallel to FastAPI new-feature skill)

1. Schema (Zod)         → src/features/<domain>/schema.ts
2. Repository protocol  → src/features/<domain>/protocols.ts
3. Repository impl      → src/features/<domain>/repository.ts (Drizzle)
4. Server Actions       → src/features/<domain>/actions.ts (uses tags + repo via Protocol)
5. Components (server)  → src/features/<domain>/components/<Feature>Page.tsx
6. Components (client)  → src/features/<domain>/components/<Leaf>.tsx ('use client')
7. Route               → src/app/<route>/page.tsx (thin, < 20 lines)