shadcn/ui — ไลบรารีที่ก็อปโค้ดมาไว้ในโปรเจกต์เรา

next                      16.3.5
react                     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() — ดูหัวข้อ 4
node                      v24.14.0
npm                       11.9.0

$ npm shadcn@latest add button
Unknown command: "shadcn@latest"

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

1 · shadcn ไม่ใช่ของที่ import — มันคือของที่ก็อป

ลองเทียบสองแบบนี้ดู

แบบ UI library ทั่วไป — คุณสั่ง npm install ชื่อไลบรารี โค้ดของปุ่มไปนอนอยู่ใน node_modules/ แล้วคุณเขียน import { Button } from "ชื่อไลบรารี"
อยากเปลี่ยนสีปุ่ม? ทำได้เท่าที่ไลบรารีเปิดช่องให้ · อยากแก้ข้างในจริง ๆ? ไม่ได้ เพราะมันไม่ใช่โค้ดของคุณ (แก้ใน node_modules/ ได้ แต่ติดตั้งใหม่ครั้งหน้าก็หาย)

แบบ shadcn — คุณสั่ง npx shadcn@latest add button แล้วมันเขียนไฟล์ components/ui/button.tsx ลงในโปรเจกต์ของคุณ เป็น source code ธรรมดา ๆ 57 บรรทัด อ่านได้ทุกบรรทัด
คุณ import มันจาก @/components/ui/button — จากโฟลเดอร์ของตัวเอง ไม่ใช่จาก package

// โปรเจกต์นี้มี "shadcn" อยู่ใน package.json จริง ๆ (init ใส่ให้)
// งั้นลอง import ปุ่มจากมันตรง ๆ
import { Button } from "shadcn";
export const X = Button;

probe-import.ts(1,10): error TS2305: Module '"shadcn"' has no exported member 'Button'.

2 · init — เตรียมสมุดก่อนก็อปสูตรแรก

สไลด์หน้า 11 ให้คำสั่งนี้ (ถูกต้อง รันได้):

$ npx shadcn@latest init -t next

ภาพ terminal ในสไลด์หน้า 11 โชว์ว่ามันถามสองคำถาม: Select a component library (ในภาพเลือก Base UI) แล้วตามด้วย Which preset would you like to use? (Nova · Vega · Maia · Lyra · Mira · Luma · Sera · Rhea · Custom) — preset คือชุดหน้าตาสำเร็จ ส่วนสไลด์หน้า 12 คือหน้า ui.shadcn.com/create ที่ให้ปรับ style / สี / ฟอนต์ / radius เองแล้วกด Get Code

init ไม่ได้ก็อป component ให้สักตัว — มันเตรียมโปรเจกต์ให้พร้อมรับ · นี่คือ git show --stat ของ commit ที่ผมรัน init + add สี่ตัวไว้ (ตัดบรรทัด lockfile ออก):

$ git show --stat HEAD
 app/globals.css            |  132 +-
 components.json            |   25 +
 components/ui/badge.tsx    |   51 +
 components/ui/button.tsx   |   57 +
 components/ui/card.tsx     |  102 ++
 components/ui/skeleton.tsx |   13 +
 lib/utils.ts               |    1 +
 package.json               |    8 +-

แยกให้ดูว่าแต่ละไฟล์มาทำอะไร:

components.json ของจริงในโปรเจกต์ (ตัด $schema บรรทัดแรก กับ menuColor · menuAccent · registries ท้ายไฟล์ออก):

{
  "style": "base-nova",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",                   // ว่าง = Tailwind v4 ไม่มี tailwind.config.js
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "iconLibrary": "lucide",
  "rtl": false,
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",        // ← add จะวางไฟล์ลงตรงนี้
    "lib": "@/lib",
    "hooks": "@/hooks"
  }
}

(ในรูปสไลด์หน้า 13 และ 15 จะเห็น components.json ติดตัว U สีเขียว — VS Code บอกว่าเป็นไฟล์ใหม่ที่ git ยังไม่เคยเห็น ตรงกับที่เราเจอ)

3 · add — พิสูจน์ว่ามันก็อปไฟล์จริง

โปรเจกต์ตั้งต้นมี button · card · badge · skeleton แล้ว ผมเลือก input ซึ่งยังไม่มี · commit ทุกอย่างให้สะอาดก่อน แล้วสั่ง:

$ npx shadcn@latest add input
✔ Checking registry.
✔ Created 1 file:
  - components/ui/input.tsx

$ git status --short
?? components/ui/input.tsx

$ git diff --stat
(ว่าง — ไม่มีไฟล์เดิมไหนถูกแก้เลย)

อ่านผลสามบรรทัดนี้ให้ออก:

• ?? แปลว่าไฟล์ใหม่ที่ git ยังไม่รู้จัก — มีไฟล์เดียว
• package.json ไม่เปลี่ยน — ไม่มี package ชื่อ “input” ถูกติดตั้ง (input ใช้ @base-ui/react ซึ่ง init ติดตั้งไว้ให้แล้วตั้งแต่แรก)
• components.json ก็ไม่เปลี่ยน — shadcn ไม่ได้จดว่าเราติดตั้งอะไรไปบ้าง ไฟล์ที่อยู่ใน components/ui/ คือบันทึกเดียวที่มี

ไฟล์ที่ได้มาหน้าตาแบบนี้ (class ยาวมาก ผมตัดตรงกลางเป็น …):

// components/ui/input.tsx — 19 บรรทัด ก็อปมาจาก registry ของ shadcn
import * as React from "react"
import { Input as InputPrimitive } from "@base-ui/react/input"
import { cn } from "cn"

function Input({ className, type, ...props }: React.ComponentProps<"input">) {
  return (
    <InputPrimitive
      type={type}
      data-slot="input"
      className={cn(
        "h-8 w-full min-w-0 rounded-lg border border-input bg-transparent px-2.5 py-1 … dark:aria-invalid:ring-destructive/40",
        className
      )}
      {...props}
    />
  )
}

export { Input }

สังเกตว่ามันคือ component ธรรมดาแบบที่เราเขียนเป็นแล้วใน บท 71 — รับ className · กระจาย ...props ที่เหลือ · ครอบตัว InputPrimitive จาก Base UI (ตัวที่จัดการพฤติกรรมกับ accessibility) แล้วแปะ class ของ Tailwind ให้สวย
ไม่มีเวทมนตร์อะไรเลย · คุณเปิดอ่านได้ทุกบรรทัด เพราะมันอยู่ในโปรเจกต์คุณ

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

$ cat lib/utils.ts
export { cn } from "cn"

$ grep cn components/ui/button.tsx | head -1
import { cn } from "cn"

ปัญหาที่ cn() แก้คือแบบนี้: button.tsx มี class ของตัวเองอยู่แล้ว เช่น bg-primary · แล้วคุณส่ง className="bg-orange-500" เข้าไป
ถ้าเอาสองสตริงมาต่อกันเฉย ๆ จะได้ "bg-primary bg-orange-500" — มีพื้นหลังสองสีในแท็กเดียว
คุณคงคิดว่า “ตัวหลังชนะ” เหมือนเขียน prop ซ้ำ… ลองทายดู

// ต่อสตริงเอง ไม่ใช้ cn — ตั้งใจให้ px-2 (ตัวหลัง) ชนะ
<div className="px-4 px-2">ต่อสตริงเอง</div>

// px-2 = padding ซ้ายขวา 8px · px-4 = 16px

ต่อสตริงเอง => pad-left 16px

.px-2{padding-inline:calc(var(--spacing) * 2)}   ← เจอก่อนในไฟล์
.px-4{padding-inline:calc(var(--spacing) * 4)}   ← เจอทีหลัง (ห่างกัน 97 ตัวอักษร) จึงชนะ

ผลรันจริงของ cn() (node รันไฟล์ที่ import { cn } from "cn"):

$ node cn-probe.mjs
// cn("px-2", "px-4")
"px-4"
// cn("px-2 py-1", "p-4")        p-4 คุมทั้งสี่ด้าน จึงกลืน px/py ที่มาก่อน
"p-4"
// cn("p-4", "px-2")             px-2 มาทีหลัง ทับได้แค่ซ้ายขวา p-4 จึงยังอยู่
"p-4 px-2"
// cn("text-red-500", "text-lg") สีกับขนาด คนละเรื่อง ไม่ชนกัน เก็บทั้งคู่
"text-red-500 text-lg"
// cn("rounded-lg", isActive && "bg-blue-500", { "text-white": isActive, "border": true })  โดย isActive = false
"rounded-lg border"
// "px-2" + " " + "px-4"         ต่อสตริงเอง
"px-2 px-4"

cn() ทำสองงานในตัวเดียว: (1) รวม — รับได้ทั้งสตริง, false (ทิ้งให้), และ object แบบ { "class": เงื่อนไข } · (2) ตัดสินการชน — รู้ว่า text-red-500 กับ text-lg ขึ้นต้นเหมือนกันแต่คนละเรื่อง ส่วน px-2 กับ px-4 คือเรื่องเดียวกัน

5 · ทำไมสไลด์หน้า 16 บอกว่า “อย่าแก้ไฟล์ตรง ๆ”

ถึงตรงนี้คุณอาจคิดว่า “ไฟล์เป็นของเราแล้ว งั้นอยากได้ปุ่มสีส้มก็เปิด button.tsx แก้เลยสิ”
ได้จริง — แต่ลองดูว่าเกิดอะไรขึ้นถ้าวันหนึ่งมีคน (หรือ AI) สั่ง add button ซ้ำ
ผมแก้ variant default ของปุ่มให้เป็นสีส้ม:

$ git diff
--- a/components/ui/button.tsx
+++ b/components/ui/button.tsx
@@ -7,7 +7,7 @@ const buttonVariants = cva(
   {
     variants: {
       variant: {
-        default: "bg-primary text-primary-foreground hover:bg-primary/80",
+        default: "bg-orange-500 text-white hover:bg-orange-600",

# แก้ button.tsx ไว้แล้ว (ยังไม่ commit) แล้วสั่งซ้ำ
$ npx shadcn@latest add button

✔ Checking registry.
? The file button.tsx already exists. Would you like to overwrite? › (y/N)

ℹ Skipped 1 file: (files might be identical, use --overwrite to overwrite)
  - components/ui/input.tsx

คำถามนั้นถามแค่ครั้งเดียว · คนที่ไม่ได้อ่าน หรือสคริปต์/AI ที่ใส่ --overwrite มาให้ จะเจอแบบนี้:

$ npx shadcn@latest add button --overwrite
✔ Checking registry.
ℹ Updated 1 file:
  - components/ui/button.tsx

$ git status --short
(ว่าง)

$ grep -n 'default: "bg-' components/ui/button.tsx
10:        default: "bg-primary text-primary-foreground hover:bg-primary/80",

ปุ่มสีส้มหายเกลี้ยง ไม่มีคำเตือน · git status ว่างเพราะไฟล์กลับไปเหมือน commit เดิมทุกตัวอักษร
ในโปรเจกต์นี้โชคดีที่งานยังไม่ได้ commit เลยเสียแค่หนึ่งบรรทัด · ในโปรเจกต์จริงที่แก้ button.tsx ไว้ 20 จุดตลอดครึ่งปี แล้วมีคนสั่ง add button --overwrite เพื่อ “อัปเดตให้เป็นรุ่นล่าสุด” — คุณจะต้องไล่หาใน git history ว่าเคยแก้อะไรไว้บ้าง

$ npx shadcn@latest add button --diff components/ui/button.tsx
┌ shadcn add button (dry run)
├ components/ui/button.tsx (overwrite)
│ -        default: "bg-orange-500 text-white hover:bg-orange-600",
│ +        default: "bg-primary text-primary-foreground hover:bg-primary/80",
└ Run without --dry-run to apply.

6 · สร้างใหม่ตามแบบ shadcn — ห่อ Button แทนการแก้

“create a new by following Shadcn” ในสไลด์หน้า 16 แปลเป็นโค้ดได้แบบนี้ · วางตามโครง components/ComponentA/ComponentA.tsx + index.ts ที่สไลด์หน้า 8 ให้ไว้ (บท 79)
(ในภาพสไลด์หน้า 15 ก็เห็นโฟลเดอร์ components/Bases วางคู่กับ components/ui — ภาพไม่ได้กางให้เห็นว่าข้างในมีอะไร แต่ตำแหน่งตรงกับแนวคิดนี้)

// 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> & {
  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)}
      disabled={disabled || loading}
      {...restProps}
    >
      {loading ? "กำลังบันทึก..." : children}
    </Button>
  );
};

export default ActionButton;

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

// app/t80/page.tsx
import ActionButton from "@/components/ActionButton";
import { Button } from "@/components/ui/button";

export default function Page() {
  return (
    <main className="flex gap-2 p-8">
      <Button>ปุ่มเดิมของ shadcn</Button>
      <ActionButton>บันทึกสูตร</ActionButton>
      <ActionButton loading>บันทึกสูตร</ActionButton>
      <ActionButton variant="outline" className="bg-white text-orange-600">ยกเลิก</ActionButton>
    </main>
  );
}

สามอย่างที่ทำให้ตัวห่อนี้ “ตามแบบ shadcn”:

• ComponentProps<typeof Button> — รับ prop ทุกตัวที่ Button รับ (variant · size · onClick …) โดยไม่ต้องพิมพ์ type เอง แล้วต่อ loading ที่เป็นของเราเพิ่ม
• ...restProps ส่งต่อทุกอย่างที่เหลือ — ท่าเดียวกับ {...restProps} ใน บท 71
• cn(ของเรา, className) — ใส่ className ของคนเรียกไว้ทีหลัง คนที่ใช้ ActionButton จึงยังทับสีได้ถ้าจำเป็น

ผลตรวจจริง:

$ npx next build
▲ Next.js 16.3.5 (Turbopack)
✓ Compiled successfully in 3.1s
  Running TypeScript ...
  Finished TypeScript in 1028ms ...
✓ Generating static pages using 6 workers (5/5) in 240ms

Route (app)
┌ ○ /
├ ○ /_not-found
└ ○ /t80

$ npx tsc --noEmit; echo "tsc rc=$?"
tsc rc=0

$ npx eslint . ; echo "eslint rc=$?"
eslint rc=0

และนี่คือ class ที่ออกมาใน HTML จริง (ไฟล์ .next/server/app/t80.html) · ผมตัด class ส่วนหัวที่เหมือนกันทุกปุ่มออกเป็น … เหลือแต่ท่อนท้ายที่ต่างกัน:

<!-- Button เดิม -->
class="… bg-primary text-primary-foreground hover:bg-primary/80 h-8 gap-1.5 px-2.5 …"

<!-- ActionButton -->
class="… h-8 gap-1.5 px-2.5 … bg-orange-500 text-white hover:bg-orange-600"

<!-- ActionButton loading — ได้ disabled="" มาด้วย และข้อความเปลี่ยน -->
<button type="button" data-disabled="" tabindex="0" disabled="" data-slot="button" class="… bg-orange-500 text-white hover:bg-orange-600">กำลังบันทึก...</button>

<!-- ActionButton variant="outline" className="bg-white text-orange-600" -->
class="… border-border hover:text-foreground aria-expanded:bg-muted … hover:bg-orange-600 bg-white text-orange-600"

ดูปุ่มที่สอง: bg-primary text-primary-foreground hover:bg-primary/80 หายไปทั้งสามตัว — cn() ข้างใน button.tsx ตัดทิ้งเพราะชนกับของเรา
ปุ่มสุดท้ายยิ่งชัด: variant outline มี bg-background hover:bg-muted — โดน bg-white กับ hover:bg-orange-600 ทับหาย · text-white ของเราก็โดน text-orange-600 ของคนเรียกทับอีกชั้น
วัดใน browser จริง: ปุ่ม “บันทึกสูตร” ได้พื้นหลัง lab(64.272 57.1788 90.3583) (สีส้ม) · ปุ่ม “ยกเลิก” ได้ rgb(255, 255, 255)

ภารกิจ — ป้ายระดับความยากของสูตรอาหาร

// components/DifficultyBadge/DifficultyBadge.tsx
import type { ComponentProps } from "react";
import { Badge } from "@/components/ui/badge";
import { cn } from "@/lib/utils";

type Difficulty = "easy" | "medium" | "hard";

const LABEL: Record<Difficulty, string> = {
  easy: "ง่าย",
  medium: "ปานกลาง",
  hard: "ยาก",
};

const COLOR: Record<Difficulty, string> = {
  easy: "bg-green-100 text-green-800",
  medium: "bg-yellow-100 text-yellow-800",
  hard: "bg-red-100 text-red-800",
};

type DifficultyBadgeProps = Omit<ComponentProps<typeof Badge>, "children"> & {
  level: Difficulty;
};

const DifficultyBadge = ({ level, className, ...restProps }: DifficultyBadgeProps) => {
  return (
    <Badge className={cn(COLOR[level], className)} {...restProps}>
      {LABEL[level]}
    </Badge>
  );
};

export default DifficultyBadge;

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

// app/t80/badge/page.tsx
import DifficultyBadge from "@/components/DifficultyBadge";

export default function Page() {
  return (
    <main className="flex gap-2 p-8">
      <DifficultyBadge level="easy" />
      <DifficultyBadge level="hard" className="text-base" />
    </main>
  );
}

$ npx next build
Route (app)
┌ ○ /
├ ○ /_not-found
├ ○ /t80
└ ○ /t80/badge

$ npx tsc --noEmit; echo "tsc rc=$?"
tsc rc=0

$ npx eslint . ; echo "eslint rc=$?"
eslint rc=0

$ npx shadcn@latest add badge
✔ Checking registry.
ℹ Skipped 1 file: (files might be identical, use --overwrite to overwrite)
  - components/ui/badge.tsx

$ git status --short
?? app/t80/
?? components/ActionButton/
?? components/DifficultyBadge/

# ไฟล์ทดสอบ components/DifficultyBadge/bad.tsx (ลบทิ้งหลังลอง):
#   import DifficultyBadge from "./DifficultyBadge";
#   export const Bad = () => <DifficultyBadge level="spicy" />;
$ npx tsc --noEmit
components/DifficultyBadge/bad.tsx(2,43): error TS2322: Type '"spicy"' is not assignable to type 'Difficulty'.

<span data-slot="badge" data-variant="default" class="… px-2 py-0.5 text-xs font-medium … [a]:hover:bg-primary/80 bg-green-100 text-green-800">ง่าย</span>

<span data-slot="badge" data-variant="default" class="… px-2 py-0.5 font-medium … [a]:hover:bg-primary/80 bg-red-100 text-red-800 text-base">ยาก</span>

ลองตอบดู

ถามกลับได้เลย

ถ้าโปรเจกต์ของคุณ lib/utils.ts หน้าตาไม่เหมือนในบทนี้ · หรือ add แล้วได้ข้อความไม่ตรง — เอาผล npx shadcn@latest --version กับ git status --short มาคุยได้เลย ส่วนใหญ่เป็นเรื่องรุ่นของ shadcn
ถ้าไม่แน่ใจว่าอยากได้ของใหม่ควร “เพิ่ม variant ใน button.tsx” หรือ “ห่อ component ใหม่” ก็เอาโจทย์มาถาม — คำถามนี้ไม่มีคำตอบเดียว แต่มีเหตุผลที่ต้องพูดให้ได้

อ้างอิง

• shadcn/ui — Introduction — อ่านหัวข้อ Open Code กับ Composition ซึ่งอธิบายตรง ๆ ว่าทำไมมันส่งโค้ดให้แทนการส่ง package — คือแกนของหัวข้อ 1 และ 6 ในบทนี้
• shadcn/ui — CLI — อ่านหัวข้อ add ดู flag --overwrite · --diff · --dry-run และหัวข้อ migrate cn ถ้าเจอโปรเจกต์ที่ยังใช้ clsx + tailwind-merge
• shadcn/ui — components.json — อ่านหัวข้อ aliases (โดยเฉพาะ aliases.ui กับ aliases.utils) เพื่อรู้ว่า CLI ตัดสินใจวางไฟล์ที่ไหน · ข้าม registries ไปก่อนได้
• shadcn-ui/cn บน GitHub — อ่าน README ช่วงต้นจนถึงหัวข้อ Can I use this today? จะเห็นว่า cn เป็นตัวแทน clsx + tailwind-merge และมีคำสั่ง migrate ให้ — อธิบายว่าทำไม lib/utils.ts ในโปรเจกต์ใหม่ไม่เหมือนสไลด์หน้า 15