architect-nextjs
Next.js architecture with Scope Rule and Screaming Architecture patterns. Trigger: When setting up new Next.js projects, deciding component placement, or implementing Server Actions and route groups.
- License 许可
- Apache-2.0
- 最近更新
- 2026-08-26
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- architect-nextjs
- license
- Apache-2.0
- metadata
- { "author": "gentleman-programming", "version": "1.0" }
- description
- Next.js architecture with Scope Rule and Screaming Architecture patterns. Trigger: When setting up new Next.js projects, deciding component placement, or implementing Server Actions and route groups.
02 资源文件 6
- 参考文档.skill-meta.json515 B
- 资产文件assets/01-app-structure.txt592 B
- 参考文档README.md431 B
- 参考文档references/01-app-router.md77 B
- 参考文档references/02-server-components.md70 B
- 参考文档references/03-project-structure.md73 B
03 SKILL.md 正文
When to Use
- Setting up new Next.js 16+ project structure
- Deciding component placement (local vs shared)
- Refactoring codebases toward scalable architecture
- Implementing Server Actions, layouts, and route groups
- Applying the Scope Rule consistently
Core Principles
1. The Scope Rule (Absolute Law)
"Scope determines structure."
| Usage | Location |
|---|---|
| Used by 1 feature | app/(feature)/_components/ |
| Used by 2+ features | src/shared/ |
No Exceptions: Do NOT pollute shared/ with single-use components.
2. Screaming Architecture
Directory structures MUST immediately declare what the application does.
app/
├── (auth)/ # 👀 Authentication feature
│ ├── login/
│ │ └── _components/
│ ├── register/
│ │ └── _components/
│ └── _components/ # Shared auth components
├── (shop)/ # 👀 E-commerce feature
│ ├── products/
│ │ └── _components/
│ └── cart/
│ └── _components/
└── (blog)/ # 👀 Blog feature
├── posts/
└── categories/
shared/ # ⚠️ ONLY for 2+ features
└── components/ # Global components
3. Next.js 16 Standards
- App Router Only: No
pages/directory - Server-First: Components are Server Components by default
- Data Access: Fetch directly in Server Components or via Server Actions
Directory Structure
Route Groups
Use (feature) syntax for top-level modules:
app/
├── (auth)/ # No URL impact
│ ├── login/page.tsx # /login
│ └── register/page.tsx # /register
├── (dashboard)/ # /dashboard/*
│ ├── layout.tsx
│ ├── page.tsx
│ └── settings/
└── (public)/ # Public pages
├── about/page.tsx
└── contact/page.tsx
Private Folders
Use _ prefix for folders that should NOT create routes:
app/
├── (feature)/
│ ├── page.tsx
│ ├── _components/ # NOT routed
│ ├── _actions/ # Server Actions (NOT routed)
│ └── _types/ # TypeScript types
Decision Framework
Step 1: Count Usage
Is the code used by:
├── 1 feature → app/(feature)/_components/
└── 2+ features → src/shared/
Step 2: Determine Component Type
| Type | When to Use | Directive |
|---|---|---|
| Server Component | Static content, data fetching | Default (none) |
| Client Component | useState, useEffect, event handlers | "use client" |
| Server Action | Mutations, form handling | "use server" |
Step 3: Push "use client" Down
❌ BAD: Entire page as client
app/(feature)/page.tsx (with "use client")
✅ GOOD: Only interactive leaf as client
app/(feature)/
├── page.tsx # Server - fetches data
└── _components/
└── Button.tsx # Client - "use client" here
Component Templates
Server Component
import { Suspense } from "react";
import { getData } from "@/shared/lib/api";
export default async function FeaturePage() {
const data = await getData();
return (
<main>
<Suspense fallback={<Skeleton />}>
<Content data={data} />
</Suspense>
</main>
);
}
Client Component
"use client";
import { useState } from "react";
interface Props {
initialValue?: string;
}
export function InteractiveComponent({ initialValue = "" }: Props) {
const [value, setValue] = useState(initialValue);
return (
<input
value={value}
onChange={(e) => setValue(e.target.value)}
/>
);
}
Server Action
"use server";
import { revalidatePath } from "next/cache";
import { redirect } from "next/navigation";
export async function submitForm(prevState: FormState, formData: FormData) {
const validated = validateForm(formData);
if (!validated.success) {
return { errors: validated.errors };
}
await db.items.create({ data: validated.data });
revalidatePath("/items");
redirect("/items");
}
File Naming Conventions
| Type | Convention | Example |
|---|---|---|
| Page | page.tsx |
app/(shop)/products/page.tsx |
| Layout | layout.tsx |
app/(shop)/layout.tsx |
| Component | CamelCase.tsx |
ProductCard.tsx |
| Server Action | kebab-case.ts |
create-product.ts |
| Hook | useCamelCase.ts |
useCart.ts |
| Type | kebab-case.ts |
product-types.ts |
| Utils | kebab-case.ts |
format-date.ts |
Quality Checklist
Before finalizing any structure:
- [ ] Scope: Is this used in >1 feature? If no →
_components/ - [ ] Server: Is "use client" necessary? Can it be pushed down the tree?
- [ ] Screaming: Does folder name describe what it does?
- [ ] Colocation: Are hooks/types/styles next to component?
Server Actions Placement
app/
└── (feature)/
├── _actions/ # Feature-specific actions
│ ├── create-item.ts
│ └── delete-item.ts
└── page.tsx
// app/(feature)/_actions/create-item.ts
"use server";
export async function createItem(formData: FormData) {
"use server";
// Implementation
}
// Usage in component
import { createItem } from "../_actions/create-item";
Shared vs Local Decision
src/
├── shared/
│ └── components/ # Used by 2+ features
│ ├── Button.tsx
│ ├── Modal.tsx
│ └── Input.tsx
└── app/
└── (feature)/
└── _components/ # Used only by this feature
├── FeatureCard.tsx
└── FeatureList.tsx
Commands
# Create new feature route group
mkdir -p app/\(new-feature\)/page.tsx
# Create private components folder
mkdir -p app/\(feature\)/_components
# Create server actions
mkdir -p app/\(feature\)/_actions
Resources
See references/ for detailed guides and code examples in assets/.
External Resources
- [Official Documentation]
04 同仓库更多 Skills
zustand-5
Zustand 5 state management patterns. Trigger: When managing React state with Zustand.
zod-4
Zod 4 schema validation patterns. Trigger: When using Zod for validation - breaking changes from v3.
x-bookmark-quote-posts
Workflow para revisar bookmarks de X/Twitter y convertirlos en drafts de quote posts. Accede a la sección de bookmarks vía browser headless, extrae posts recientes, y genera drafts con voz personal del usuario. No publica ni muta X — solo genera contenido para revisión. Trigger: X bookmarks, Twitter bookmarks, quote posts, bookmark automation, crear quote posts, revisar bookmarks, growth content X.
writing-skills
Use when creating new skills, editing existing skills, or verifying skills work before deployment
writing-plans
Use when you have a spec or requirements for a multi-step task, before touching code
work-unit-commits
Plan commits as reviewable work units. Trigger: implementation, commit splitting, chained PRs, or keeping tests and docs with code.