สร้างแอปแรกด้วย Next.js — โครงโฟลเดอร์ · shadcn · tokens · CVA · layout แผ่นเดียวจบ

next                      16.3.5    # Turbopack
react / react-dom         19.2.8
typescript                5.9.3
tailwindcss               4.3.3
shadcn                    4.21.0    # npx shadcn@latest --version
@base-ui/react            1.8.0
class-variance-authority  0.7.1
cn                        0.3.0     # ตัวที่ทำ cn() — ไม่ใช่ clsx + tailwind-merge แล้ว
eslint                    9.39.5
node                      v24.14.0
npm                       11.9.0

# โปรเจกต์ตั้งต้นของทุกบท:
create-next-app  →  npx shadcn init (preset base-nova)  →  npx shadcn add button card badge skeleton

สารบัญ

1. โครงโฟลเดอร์ — อะไรอยู่ไหน ทำไม
2. คำสั่ง shadcn ที่ใช้จริง
3. cn() — ตัวรวม class
4. design tokens สองชั้น
5. cva — variants ของปุ่ม
6. Layout · Container · Navbar
7. RecipeCard + 4 สถานะของหน้า
8. คำสั่งพิสูจน์ว่าทำงานจริง
9. ตารางแปล error ที่เจอจริง
10. ตารางกับดักรวมทั้งกลุ่ม
11. อ้างอิง

1 · โครงโฟลเดอร์ — อะไรอยู่ไหน ทำไม

.
├── app/
│   ├── layout.tsx            # กรอบที่ห่อทุกหน้า — วาง Navbar / Footer ที่นี่
│   ├── page.tsx              # หน้า /
│   ├── globals.css           # Tailwind + token ทั้งชุด (shadcn init เติมให้)
│   ├── _components/          # ของที่ใช้หน้าเดียว · ขีดล่าง = ไม่เป็น URL
│   ├── _containers/
│   └── recipes/page.tsx      # หน้า /recipes
├── components/
│   ├── RecipeCard/           # หนึ่งโฟลเดอร์ต่อหนึ่งตัว
│   │   ├── RecipeCard.tsx
│   │   └── index.ts          # barrel
│   └── ui/                   # ไฟล์ที่ shadcn add ก็อปมา — อย่าแก้ตรง ๆ
├── containers/
│   └── RecipeList/
│       ├── RecipeList.tsx
│       └── index.ts
├── lib/utils.ts              # export { cn } from "cn"  (บรรทัดเดียว)
└── components.json           # ตั้งค่าที่ shadcn CLI อ่านทุกครั้งที่ add

ตัดสินว่าโค้ดชิ้นนี้อยู่ไหน — ถามสองข้อตามลำดับ

2 · คำสั่ง shadcn ที่ใช้จริง

$ npm shadcn@latest add button        # ← ตามสไลด์ ใช้ไม่ได้
Unknown command: "shadcn@latest"

To see a list of supported npm commands, run:
  npm help

$ npx shadcn@latest add button        # ← ที่ถูก (เหมือน init ในหน้า 11)

สั่ง add ซ้ำกับไฟล์ที่มีอยู่แล้ว — ได้ข้อความไม่เหมือนกัน

“อย่าแก้ไฟล์ตรง ๆ ให้สร้างใหม่ตามแบบ shadcn” (สไลด์หน้า 16) — ห่อแทนแก้

// components/ActionButton/ActionButton.tsx
import type { ComponentProps } from "react";
import { Button } from "@/components/ui/button";
import { cn } from "@/lib/utils";

type ActionButtonProps = ComponentProps<typeof Button> & {   // รับทุก prop ที่ Button รับ + ของเรา
  loading?: boolean;
};

const ActionButton = ({ loading = false, disabled, className, children, ...restProps }: ActionButtonProps) => {
  return (
    <Button
      className={cn("bg-orange-500 text-white hover:bg-orange-600", className)}  // className คนเรียกไว้ท้าย → ทับได้
      disabled={disabled || loading}
      {...restProps}
    >
      {loading ? "กำลังบันทึก..." : children}
    </Button>
  );
};

export default ActionButton;

// components/ActionButton/index.ts
export { default } from "./ActionButton";

พิสูจน์แล้ว: สั่ง add button --overwrite หลังมี ActionButton → button.tsx กลับเป็นต้นฉบับ แต่ HTML ของ ActionButton ยังลงท้าย bg-orange-500 text-white hover:bg-orange-600 ครบ · อยากตัด children ออกจาก type ใช้ Omit<ComponentProps<typeof Badge>, "children"> (ภารกิจ DifficultyBadge บท 80)

3 · cn() — ตัวรวม class ที่รู้ว่า class ไหนชนกัน

ปัญหาที่มันแก้: ต่อสตริง "px-4 px-2" เองแล้วหวังว่าตัวหลังชนะ — วัดจริงได้ padding 16px (px-4 ชนะ) เพราะ CSS ตัดสินจากลำดับ rule ในไฟล์ CSS ที่ Tailwind เรียงเอง (.px-2 มาก่อน .px-4) ไม่ใช่ลำดับใน attribute class

กติกาที่ใช้ได้ทุก component ที่รับ className: cn(class ของเรา, className) — ใส่ของคนเรียกไว้ท้าย คนใช้จะทับได้ · ต่อสตริงเองหรือส่ง className ให้ cva ตรง ๆ โดยไม่ผ่าน cn → มีทั้ง h-8.5 และ h-12 อยู่ด้วยกัน ผลขึ้นกับลำดับไฟล์ CSS ทายจากโค้ดไม่ได้

4 · design tokens — ค่าจริงใน :root → ชื่อใน @theme inline → class

:root          { --primary: #a80689 }                  ← ชั้น 1: ค่าจริง (browser อ่าน)
      │
      ▼
@theme inline  { --color-primary: var(--primary) }     ← ชั้น 2: ตั้งชื่อให้ Tailwind
      │                 └──┬──┘
      │         "--color-" + "primary"
      ▼
class ที่ใช้ได้:  bg-primary · text-primary · border-primary · ring-primary · hover:bg-primary …
      │
      ▼  (npx next build)
CSS จริงที่ได้:  .bg-primary{background-color:var(--primary)}

ขั้นตอนเพิ่ม token ใหม่ (ทำครบทุกข้อ)

1. ใส่ค่าจริงใน :root — และใน .dark ถ้ามีธีมมืด
2. ลงทะเบียน --color-ชื่อ: var(--ชื่อ); ในบล็อก @theme inline เดิม ของ shadcn — อย่าเปิดบล็อก @theme ใหม่
3. ใช้ใน JSX เช่น bg-accent-subtle · text-accent-strong
4. npx next build แล้ว grep CSS ที่ build ออกมา ให้เจอทั้ง rule และค่า (หัวข้อ 8) — “เปิดหน้าแล้วสวย” ไม่นับว่าพิสูจน์

/* app/globals.css — ผลจาก git diff จริงของภารกิจบท 81 (ตัดบริบทออก) */
@theme inline {
  --color-accent-subtle: var(--accent-subtle);
  --color-accent-strong: var(--accent-strong);
}
:root {
  --accent-subtle: #fff1dc;
  --accent-strong: #b36a00;
}
@utility wongnok-text-h1 {
  font-size: 2.25rem;
  line-height: 2.5rem;
  font-weight: 700;
}

แบบไม่ inline จะ “ดูเหมือนใช้ได้” ตอนใส่ dark ที่ <html> (ได้ rgb(232, 121, 201) ทั้งสองแบบ) แล้วค่อยพังตอนมีคนทำกล่องธีมมืดเฉพาะส่วน · dark: ในโปรเจกต์นี้ผูกกับ class ด้วย @custom-variant dark (&:is(.dark *));

class ของเราเอง (เช่น wongnok-text-h2) — ใช้ @utility

5 · cva — ปุ่มหลายหน้าตาในที่เดียว

แพ็กเกจชื่อ class-variance-authority (หัวสไลด์หน้า 31 สะกด “Variant” — ตอนค้นเอกสาร/พิมพ์ import ใช้ variance) · shadcn init ติดตั้งให้แล้ว · cva ไม่สร้าง CSS มันแค่ประกอบ string class — Tailwind ยังเป็นคนสร้าง CSS

// components/Bases/button-variants.ts (ย่อ — ไฟล์เต็มอยู่บท 82 หัวข้อ 3)
import { cva, type VariantProps } from "class-variance-authority";

export const buttonVariants = cva(
  "inline-flex items-center justify-center gap-2 rounded-md font-medium transition-colors disabled:pointer-events-none disabled:opacity-50",  // ① class ฐาน
  {
    variants: {                                         // ② เมนูแต่ละแกน
      variant: { contained: "", outlined: "border-2 bg-transparent" },
      color:   { primary: "", accent: "", error: "", gray: "" },   // ว่าง: สีขึ้นกับ variant ด้วย
      size:    { sm: "h-8.5 px-3 text-sm", md: "h-10 px-4 text-sm", lg: "h-12 px-6 text-base" },
    },
    compoundVariants: [                                 // ③ ต่อท้ายเมื่อทุกเงื่อนไขตรง
      { variant: "contained", color: "primary", className: "bg-primary text-primary-foreground hover:bg-primary/90" },
      { variant: "outlined",  color: "primary", className: "border-primary text-primary hover:bg-primary/10" },
      // … ครบ 8 คู่ (2 variant × 4 color)
    ],
    defaultVariants: { variant: "contained", color: "primary", size: "md" },   // ④ ใช้เมื่อเป็น undefined
  },
);

export type ButtonVariantProps = VariantProps<typeof buttonVariants>;   // ⑤ type มาจากเมนูเอง

compound ต่อท้ายเมื่อไหร่ — cva ย่อ ("btn" + สองกฎของสไลด์หน้า 32 ที่ต้องการ contained)

ห่อเป็น Button ที่มี loading

// components/Bases/Button.tsx
import { Loader2Icon } from "lucide-react";
import { cn } from "@/lib/utils";
import { buttonVariants, type ButtonVariantProps } from "./button-variants";

export type ButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> &
  ButtonVariantProps & {
    loading?: boolean;
  };

const Button = (props: ButtonProps) => {
  const { variant, color, size, loading = false, disabled, className, children, ...restProps } = props;
  // ↑ ดึงของตัวเองออกให้ครบก่อน ...restProps ไม่งั้นไหลไปเป็น attribute บน <button>

  return (
    <button
      className={cn(buttonVariants({ variant, color, size }), className)}
      disabled={disabled || loading}                  // กันกดซ้ำ + จางให้ฟรี
      aria-busy={loading || undefined}                // ปุ่มปกติจะไม่มี attribute นี้เลย
      {...restProps}
    >
      {loading && <Loader2Icon className="size-4 animate-spin" aria-hidden="true" />}
      {children}
    </button>
  );
};

export default Button;

ขนาดตามป้าย 34 / 40 / 48px ในสไลด์หน้า 30 ใช้ h-8.5 / h-10 / h-12 ได้เลย ไม่ต้อง h-[34px] — CSS จริงคือ .h-8\.5{height:calc(var(--spacing) * 8.5)} กับ --spacing:.25rem → 2.125rem = 34px · ชื่อในสไลด์ไม่ตรงกันเอง: หน้า 29 ซ้ายเขียน outlined ขวาเขียน variant="outline" · ชุดหน้า 28–29 เป็นสไตล์ shadcn ส่วนหน้า 30–32 เป็นชุด craft — อย่าก็อปปนกัน

6 · Layout · Container · Navbar

Container — สไลด์หน้า 39 เรียกใช้ แต่ไม่มีหน้าไหนนิยามให้

// components/layout/Container.tsx (บท 83 เขียนเอง — สไลด์ไม่ได้ให้มา · shadcn ก็ไม่มี)
import { cn } from "@/lib/utils";

export function Container({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      className={cn("mx-auto w-full max-w-7xl px-4 sm:px-6 lg:px-8", className)}
      {...props}
    />
  );
}

พื้นหลังเต็มจอต้องใส่ที่กล่องแม่ชั้นนอก (<header> · <footer>) ไม่ใช่ที่ Container

Navbar กับ active link ที่ถูกต้อง

// components/layout/Navbar.tsx (ตัดส่วนโลโก้ออก)
"use client";                                   // ← บรรทัดแรกสุด เพราะใช้ usePathname

import Link from "next/link";
import { usePathname } from "next/navigation";
import { Container } from "@/components/layout/Container";
import { cn } from "@/lib/utils";

const NAV_LINKS = [
  { href: "/", label: "Home" },                  // ไม่มี active: true ตายตัว
  { href: "/recipes", label: "Recipes" },
];

function Navbar() {
  const pathname = usePathname();
  return (
    <header className="fixed inset-x-0 top-0 z-50 border-b bg-card">
      <Container className="flex h-16 items-center justify-between gap-6">
        <nav aria-label="Main" className="hidden items-center gap-1 lg:flex">
          {NAV_LINKS.map((link) => {
            const active = pathname === link.href;
            return (
              <Link
                key={link.href}
                href={link.href}
                aria-current={active ? "page" : undefined}
                className={cn("rounded-md px-3.5 py-2 font-medium", active ? "text-primary" : "hover:bg-muted")}
              >
                {link.label}
              </Link>
            );
          })}
        </nav>
      </Container>
    </header>
  );
}

export default Navbar;

// app/layout.tsx — ใน <body className="min-h-full flex flex-col"> ที่ create-next-app สร้างให้
<Navbar />
<main className="pt-16">{children}</main>     // เว้นที่ให้ Navbar แบบ fixed
<Footer />                                   // Footer ใช้ className="mt-auto" → ดันลงล่างสุดของจอ

7 · RecipeCard + 4 สถานะของหน้า

props type — อ่านจาก design properties (สไลด์หน้า 45–46)

// components/RecipeCard/RecipeCard.tsx (ส่วน type · บท 84)
export type RecipeLevel = "EASY" | "MEDIUM" | "HARD";   // union ไม่ใช่ string

export type RecipeSummary = {
  id: number;
  name: string;
  imageUrl?: string;           // ยังไม่มีรูปจริง → วาด placeholder
  level: RecipeLevel;
  ownerName: string;
  ownerImageUrl?: string;      // เพิ่มในภารกิจท้ายบท · ไม่มีรูป → วงกลมตัวย่อชื่อ
  rating: number;
  ratingCount: number;
};

export type RecipeCardProps = {
  recipe: RecipeSummary;       // ส่งสูตรทั้งก้อน ตามโค้ดสไลด์หน้า 45
  onClick?: (id: number) => void;
};

const levelLabel: Record<RecipeLevel, string> = { EASY: "Easy", MEDIUM: "Medium", HARD: "Hard" };
// ค่าที่เก็บ (EASY) แยกจากข้อความที่โชว์ (Easy)

4 สถานะ — เก็บเป็น discriminated union บน status

// components/RecipeList/RecipeList.tsx (โครง)
export type RecipeListState =
  | { status: "loading" }
  | { status: "error"; message: string }
  | { status: "success"; recipes: RecipeSummary[] };   // ไม่มี "empty" — ว่าง = success ที่ยาว 0

const RecipeList = ({ state }: { state: RecipeListState }) => {
  if (state.status === "loading") return /* Skeleton 4 กล่อง · aria-busy="true" */;
  if (state.status === "error")   return /* role="alert" · state.message · Try again */;
  if (state.recipes.length === 0) return /* No recipes match your search · Clear filters */;
  return /* state.recipes.map((recipe) => <RecipeCard key={recipe.id} recipe={recipe} />) */;
};

หน้า All Recipes (บท 85) — responsive + ข้อความหัวจาก state

// app/recipes/page.tsx (เฉลยภารกิจบท 85 · ส่วนสำคัญ)
const subtitle = (state: RecipeListState) => {
  if (state.status === "loading") return "Loading recipes…";
  if (state.status === "error") return "Could not load recipes";
  return `${state.recipes.length} recipes found`;         // แทน "8 recipes · page 1 of 7" ที่ hardcode จาก mock
};

<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4 mt-7">   // มือถือ 1 · แท็บเล็ต 2 · จอใหญ่ 4
  <RecipeList state={state} />
</div>

// ใน RecipeList: กล่อง empty / error ใส่ className="col-span-full …" ไม่งั้นอัดอยู่ช่องแรก
// (RecipeList คืน Fragment <> — grid อยู่ที่ page.tsx ตามสไลด์หน้า 49)

sm: = @media (min-width:40rem) = 640px · lg: = @media (min-width:64rem) = 1024px · จอ 375px ได้ 1 คอลัมน์ · 700px ได้ 2 · 1280px ได้ 4 · prefix แปลว่า “ตั้งแต่ขนาดนี้ขึ้นไป” ลำดับใน className ไม่มีผล · ผล curl ของเฉลย: /recipes การ์ด 8 · /recipes-empty การ์ด 0 skeleton 0 + 0 recipes found · /recipes-loading skeleton 8

8 · คำสั่งพิสูจน์ว่าทำงานจริง

9 · ตารางแปล error ที่เจอจริงในบท 79–85

Next.js / Turbopack — ตอน next build หรือเปิดหน้า

npm / shadcn

TypeScript — จาก npx tsc --noEmit

ESLint — npx eslint .

10 · ตารางกับดักรวมทั้งกลุ่ม

11 · อ้างอิง

• Next.js — Project Structure — หัวข้อ Private folders (กฎขีดล่าง) และ Colocation · คู่กับ Dynamic Route Segments ที่อธิบายว่าทำไม [another-routes] รับทุก URL
• shadcn/ui — CLI — หัวข้อ add ดู flag --overwrite · --diff · --dry-run · และ components.json หัวข้อ aliases
• shadcn-ui/cn บน GitHub — README ช่วงต้น: cn เป็นตัวแทน clsx + tailwind-merge · อธิบายว่าทำไม lib/utils.ts ไม่เหมือนสไลด์
• Tailwind CSS — Theme variables — ตาราง Theme variable namespaces และหัวข้อ Referencing other variables (เหตุผลของ inline) · คู่กับ Adding custom styles หัวข้อ Adding custom utilities (@utility)
• shadcn/ui — Theming — หัวข้อ Adding New Tokens เพิ่ม token ด้วยขั้นตอนเดียวกับหัวข้อ 4
• cva — Variants · cva — TypeScript — Compound Variants · Default Variants · VariantProps
• Next.js — Link Component — หัวข้อ Checking active links (usePathname แบบหัวข้อ 6) · คู่กับ usePathname
• Next.js — Server and Client Components — ส่วนที่บอกว่า props ข้ามฝั่งต้อง serializable (ต้นเหตุของ 500) และ Reducing JS bundle size
• TypeScript Handbook — Discriminated unions — หลักเดียวกับ RecipeListState
• React — Rendering Lists — Why does React need keys? และกล่อง Pitfall เรื่อง index เป็น key
• Tailwind CSS — Responsive design — Working mobile-first และตาราง breakpoint (sm = 40rem · lg = 64rem)
• Cheat sheet — Next.js (บท 69–78) — App Router · Server vs Client Component · hooks · เปิดคู่กับหน้านี้เวลาเจอ error ที่ไม่อยู่ในหัวข้อ 9