Tailwind, Radix & shadcn/ui · Part 9 — shadcn/ui: Philosophy & Setup

Mọi thứ tới giờ đều dẫn tới đây. Bạn biết Tailwind (style), biết Radix (hành vi headless dễ tiếp cận — Phần 7 & 8), biết cva + cn (variant + merge class — Phần 5). shadcn/ui là kết quả khi ai đó ráp ba thứ đó lại, có gu, cho ~50 component phổ biến — rồi đưa bạn mã nguồn thay vì một package.

Khác biệt lớn nhất so với mọi thư viện UI bạn từng dùng: không có gì để “cài và import”. shadcn là một CLI chép code vào repo của bạn. Sau đó bạn không còn là “người dùng thư viện” nữa — bạn là chủ sở hữu mã nguồn. Phần này mổ xẻ tận gốc triết lý đó, từng dòng output của CLI, từng field của components.json, và khép lại bằng một recipe init-tới-chạy hoàn chỉnh. Đọc xong, bạn không cần mở ui.shadcn.com nữa.

Ownership workflow

Vì shadcn copy code vào repo, quy trình làm việc cũng khác thư viện npm:

Đừng xem folder components/ui như vendor code cấm đụng. Nó là một phần design system của bạn. Nhưng cũng đừng sửa tùy hứng mỗi màn một kiểu; mỗi thay đổi nên hướng tới một API tốt hơn cho toàn app.

1. “Open code” — triết lý cốt lõi, không phải thư viện component

Thư viện UI truyền thống (MUI, Ant Design, Chakra) là package npm. Vòng đời của nó như sau:

  npm install @mui/material
        ↓
  import { Button } from '@mui/material'
        ↓
  <Button> sống trong node_modules/  ← bạn KHÔNG sửa được
        ↓
  Muốn đổi style? → override từ ngoài (theme API, sx, !important, styled())
        ↓
  Nâng cấp? → npm update → có thể vỡ giao diện, kẹt version

Component là hộp đen (black box): bạn cấu hình từ bên ngoài và vật lộn khi cần đổi một chi tiết mà API không cho phép. Đây là mô hình “closed code”.

shadcn/ui đảo ngược hoàn toàn — gọi là “open code”:

Bạn không cài component — bạn copy mã nguồn của chúng vào project của bạn.

Một CLI thả file .tsx thật vào src/components/ui/. Kể từ giây đó, nó là file của bạn: sửa markup, xóa một variant không xài, thêm prop, đổi class Tailwind, refactor đặt tên — không override, không !important, không kẹt version. Component không nằm trong node_modules mà nằm thẳng trong source bạn commit lên Git.

Bốn trụ cột của triết lý open code

Đánh đổi — nói thật cả hai mặt

Chốt triết lý: thư viện truyền thống tối ưu cho “ít code trong repo, cập nhật dễ”. shadcn tối ưu cho “toàn quyền kiểm soát, không hộp đen”. Với team đã sống trong Tailwind, vế thứ hai gần như luôn thắng — vì bạn restyle bằng đúng công cụ đang dùng hằng ngày, không học thêm gì.

Xem ngay bộ component bạn sẽ có:

2. Bốn mảnh ghép — shadcn = Radix + Tailwind + cva + cn

shadcn không phát minh ra gì mới. Nó là cách ráp bốn thứ bạn đã học thành một workflow. Đây là sơ đồ giải phẫu của bất kỳ component shadcn nào:

   ┌─────────────────────────────────────────────────────────┐
   │                  Một component shadcn                     │
   │                                                          │
   │   Radix primitive   →  hành vi + a11y    (Phần 7 & 8)    │
   │   Tailwind utility  →  vẻ ngoài          (Phần 2 & 4)    │
   │   cva()             →  bảng variant       (Phần 5)       │
   │   cn()              →  trộn class an toàn  (Phần 5)       │
   │   token ngữ nghĩa   →  bg-primary, …      (Phần 3)       │
   └─────────────────────────────────────────────────────────┘

Nói cách khác: Radix lo “nó hoạt động đúng & dễ tiếp cận”, Tailwind lo “nó trông thế nào”, cva lo “có mấy biến thể”, cn lo “trộn lại không cãi nhau”. shadcn là người biên đạo ghép bốn vũ công này. Khi bạn mở một file shadcn (mục 8), bạn sẽ thấy chính xác bốn mảnh này, không hơn.

3. Điều kiện cần — stack giả định

shadcn giả định đúng stack ta đã dựng xuyên series. Trước khi init, hãy chắc bốn thứ:

Path alias bắt buộc phải đúng, vì mọi file shadcn import lẫn nhau bằng nó:

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@/*": ["./src/*"] }
  }
}

Với Vite, alias trong tsconfig.json thôi chưa đủ — bundler cũng cần biết. Thêm vào vite.config.ts:

// vite.config.ts
import path from 'node:path';
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: { '@': path.resolve(__dirname, './src') },
  },
});

Bẫy #1, gặp nhiều nhất: quên đăng ký alias ở vite.config.ts. TypeScript không báo lỗi (vì tsconfig đã có paths), nhưng lúc chạy Vite ném Failed to resolve import "@/lib/utils". Alias phải khai báo ở cả hai nơi.

4. init — chạy một lần, đi qua từng câu hỏi

npx shadcn@latest init

Lưu ý package name: dùng shadcn (không phải shadcn-ui — package cũ đã ngừng). Luôn @latest để lấy CLI mới nhất.

CLI sẽ hỏi vài câu. Đây là từng prompt và ý nghĩa, để bạn không bấm bừa Enter:

Sau khi trả lời, init làm ba việc cụ thể:

  npx shadcn@latest init
        │
        ├─► ghi  components.json        (manifest — mục 5)
        │
        ├─► sửa  src/index.css          (thêm token CSS theme: --primary, --border…  — Phần 3)
        │
        └─► tạo  src/lib/utils.ts       (helper cn()  — Phần 5)

File lib/utils.ts sinh ra chính xác là cái bạn viết tay ở Phần 5:

// src/lib/utils.ts
import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

Và stylesheet được chèn khối token ngữ nghĩa (rút gọn — Phần 3 & 10 đào sâu):

/* src/index.css — init chèn thêm khối này */
@import "tailwindcss";

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --border: oklch(0.922 0 0);
  /* …và nhiều token khác */
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  /* …bản dark của từng token */
}

Tailwind v4 note: ở v4, init dùng @theme inline để ánh xạ các biến --primary này thành utility bg-primary, và màu mặc định là OKLCH thay vì HSL (như v3). Nếu bạn thấy oklch(...) thay vì hsl(...), đó là dấu hiệu bạn đang ở luồng v4 — đúng và mong muốn.

5. components.json — giải thích từng field

Đây là manifest của project: mọi lệnh add sau đọc nó để biết đặt file ở đâu, theo quy ước nào. Hiểu file này là hiểu cách CLI “nghĩ”.

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "src/index.css",
    "baseColor": "zinc",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "ui": "@/components/ui",
    "utils": "@/lib/utils",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide"
}

aliases.utils là field hay gây lỗi nhất. Nếu bạn để cn() ở src/utils/cn.ts nhưng components.json trỏ @/lib/utils, thì mọi component add về sẽ import { cn } from '@/lib/utils' — và vỡ. Giữ vị trí file utils khớp đúng với alias này (mục Gotchas).

6. Bố cục file sinh ra

Sau init rồi add vài component, cây thư mục trông như sau:

src/
├── index.css                 # @import "tailwindcss" + token theme (init chèn)
├── lib/
│   └── utils.ts              # cn()  ← init tạo
└── components/
    └── ui/                   # mọi component shadcn nằm ĐÂY (aliases.ui)
        ├── button.tsx        # add button
        ├── card.tsx          # add card
        ├── dialog.tsx        # add dialog
        ├── input.tsx
        ├── label.tsx
        └── form.tsx

Quy luật chỗ-nào-cái-gì:

Điểm mấu chốt: không có thư mục node_modules/@shadcn/.... Toàn bộ “thư viện” của bạn là các file .tsx lộ thiên, commit vào Git, review trong PR như mọi code khác.

7. add — kéo component vào (và registry là gì)

npx shadcn@latest add button card input badge avatar alert dialog

Lệnh add làm bốn việc:

  npx shadcn@latest add dialog
        │
        ├─► fetch định nghĩa "dialog" từ REGISTRY (mặc định: ui.shadcn.com)
        ├─► copy mã nguồn vào  components/ui/dialog.tsx
        ├─► tự cài dep Radix cần:  npm i @radix-ui/react-dialog
        └─► thêm cva / clsx / tailwind-merge nếu project chưa có

Chạy add không kèm tên sẽ hiện danh sách chọn tương tác:

npx shadcn@latest add        # hiện menu chọn nhiều component

Registry là gì

Registry là một “nguồn” cung cấp định nghĩa component dưới dạng JSON theo schema chuẩn. Mặc định CLI trỏ tới registry chính thức của shadcn. Nhưng add cũng nhận URL trỏ tới bất kỳ registry tương thích nào:

# Thêm từ một registry/URL bên thứ ba (phải đúng schema shadcn)
npx shadcn@latest add https://example.com/r/fancy-button.json

# Thêm nhiều component từ registry chính thức
npx shadcn@latest add button dialog form

   Registry (JSON theo schema)
        │  { name, files[], dependencies[], registryDependencies[] }
        ▼
   npx shadcn add <name | URL>
        │
        ▼
   Resolve → tải file + dep → ghi vào components/ui/

Cơ chế registry này chính là “Distribution” ở mục 1: nó cho phép bạn (và cộng đồng) tự phát hành component và cài bằng cùng một CLI — ta dựng registry riêng ở Phần 10.

Cập nhật & diff component

Vì component giờ là code của bạn, shadcn không tự npm update chúng. Bạn cập nhật có chủ đích:

# Xem khác biệt giữa bản local và bản mới nhất trên registry
npx shadcn@latest diff button

# Lấy lại bản mới nhất (sẽ GHI ĐÈ file hiện tại)
npx shadcn@latest add button --overwrite

Vì bạn sở hữu code, cập nhật là một thao tác merge, không phải npm update. Nếu bạn đã sửa button.tsx, đừng --overwrite mù — chạy diff trước, rồi áp tay thay đổi upstream để không mất tùy biến.

8. Đọc button.tsx sinh ra — bạn nhận ra từng dòng

Đây là phần thưởng của cả series. Mở file CLI vừa tạo, và bạn thấy đúng bốn mảnh ở mục 2:

import * as React from 'react';
import { Slot } from '@radix-ui/react-slot';                    // Phần 8 — asChild
import { cva, type VariantProps } from 'class-variance-authority'; // Phần 5 — variants
import { cn } from '@/lib/utils';                                // Phần 5 — merge class

const buttonVariants = cva(
  // base: luôn áp — layout, typography, transition, state focus/disabled (Phần 2 & 4)
  'inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium ' +
  'transition-colors focus-visible:outline-none focus-visible:ring-2 ' +
  'disabled:pointer-events-none disabled:opacity-50',
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground hover:bg-primary/90', // Phần 3 — token ngữ nghĩa
        destructive: 'bg-destructive text-white hover:bg-destructive/90',
        outline: 'border border-input bg-background hover:bg-accent',
        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
        ghost: 'hover:bg-accent hover:text-accent-foreground',
        link: 'text-primary underline-offset-4 hover:underline',
      },
      size: { default: 'h-9 px-4 py-2', sm: 'h-8 px-3', lg: 'h-10 px-6', icon: 'size-9' },
    },
    defaultVariants: { variant: 'default', size: 'default' },
  }
);

interface ButtonProps
  extends React.ComponentProps<'button'>,
    VariantProps<typeof buttonVariants> {
  asChild?: boolean;
}

function Button({ className, variant, size, asChild = false, ...props }: ButtonProps) {
  const Comp = asChild ? Slot : 'button';                         // Phần 8 — đổi thẻ render
  return (
    <Comp
      className={cn(buttonVariants({ variant, size }), className)} // Phần 5 — base+variant rồi merge override
      {...props}
    />
  );
}

export { Button, buttonVariants };

Bóc từng dòng về phần đã dạy:

Không có phép màu nào. shadcn chỉ là người ráp bốn mảnh bạn đã thành thạo — nên khi cần sửa, bạn sửa được, vì đây là code bạn đọc hiểu trọn vẹn.

9. Recipe thực tế — init một project rồi dựng form trong dialog

Mục tiêu: từ project Vite + React + Tailwind v4 trống, dựng nút “New project” mở Dialog chứa một Form có Input validate. Đi từ đầu tới chạy.

Bước 1 — init shadcn (giả định Tailwind v4 & alias đã có như mục 3):

npx shadcn@latest init
# Style: new-york · Base color: zinc · CSS variables: yes

Bước 2 — add các component cần:

npx shadcn@latest add button dialog form input label

add form kéo theo react-hook-form, zod, @hookform/resolvers và component Form* (bọc quanh react-hook-form + Radix Label). add dialog cài @radix-ui/react-dialog.

Bước 3 — ráp lại:

// src/components/CreateProjectDialog.tsx
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
import {
  Dialog, DialogTrigger, DialogContent, DialogHeader,
  DialogTitle, DialogFooter,
} from '@/components/ui/dialog';
import {
  Form, FormField, FormItem, FormLabel, FormControl, FormMessage,
} from '@/components/ui/form';

const schema = z.object({
  name: z.string().min(2, 'Tên tối thiểu 2 ký tự'),
});

export function CreateProjectDialog() {
  const form = useForm<z.infer<typeof schema>>({
    resolver: zodResolver(schema),
    defaultValues: { name: '' },
  });

  function onSubmit(values: z.infer<typeof schema>) {
    console.log('Tạo project:', values.name);
  }

  return (
    <Dialog>
      <DialogTrigger asChild>
        <Button>New project</Button>          {/* Phần 8 — asChild gắn hành vi vào Button của bạn */}
      </DialogTrigger>

      <DialogContent className="sm:max-w-md">
        <DialogHeader>
          <DialogTitle>Create project</DialogTitle>
        </DialogHeader>

        <Form {...form}>
          <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
            <FormField
              control={form.control}
              name="name"
              render={({ field }) => (
                <FormItem>
                  <FormLabel>Project name</FormLabel>
                  <FormControl>
                    <Input placeholder="acme-web" {...field} />
                  </FormControl>
                  <FormMessage />        {/* tự hiện lỗi zod, đã nối a11y */}
                </FormItem>
              )}
            />
            <DialogFooter>
              <Button type="submit">Deploy</Button>
            </DialogFooter>
          </form>
        </Form>
      </DialogContent>
    </Dialog>
  );
}

Để ý cách bốn mảnh xuất hiện tự nhiên: Dialog* là Radix (focus trap, ESC, ARIA — Phần 7/8), DialogTrigger asChild hợp nhất hành vi vào Button của bạn (Phần 8), Button/Input mang style Tailwind + cva/cn (Phần 2/4/5), FormMessage tự nối lỗi zod với input qua aria-describedby. Bạn không viết một dòng CSS nào và vẫn có dialog dễ tiếp cận, form validate đầy đủ.

10. Tailwind v4 + React 19 — những điểm cần biết

shadcn đã cập nhật cho hệ sinh thái mới. Vài điểm đáng ghi nhớ:

Nâng cấp project shadcn cũ (v3 → v4): chạy npx @tailwindcss/upgrade cho Tailwind trước (đổi @tailwind → @import, di chuyển config sang @theme), rồi npx shadcn@latest diff từng component để áp các thay đổi cấu trúc (vd bỏ forwardRef, thêm data-slot). Đừng làm cả hai một lúc — tách bước cho dễ soát.

11. Gotchas thường gặp khi setup

Hai lỗi alias (Vite chưa khai báo & aliases.utils lệch) chiếm phần lớn sự cố “mới setup mà đỏ tùm lum”. Khi gặp import @/... không resolve, kiểm tra cả hai nơi alias: tsconfig.json và vite.config.ts, rồi đối chiếu aliases.utils với đường dẫn file cn thật.

12. Bài tập

1. Một câu: shadcn khác MUI căn bản ở chỗ nào?

2. npx shadcn@latest init tạo/sửa ba thứ gì?

3. Sau add dialog, dependency nào được cài tự động và vì sao?

4. Trong components.json, vì sao field aliases.utils lại đặc biệt dễ gây lỗi? Giá trị của nó nên trỏ tới đâu?

5. Bạn đã sửa button.tsx thêm một variant brand. Giờ muốn lấy bản cập nhật mới từ registry mà không mất variant đó — làm thế nào? Vì sao không dùng --overwrite?

6. Ở vite.config.ts cần thêm gì để @/components/ui/button resolve được, dù tsconfig.json đã có paths?

import path from 'node:path';
export default defineConfig({
  resolve: { alias: { '@': path.resolve(__dirname, './src') } },
});

Nâng cao: mở file button.tsx trong project của bạn và ánh xạ từng dòng với phần series đã dạy nó (đối chiếu bảng ở mục 8).

Điểm chính

• shadcn là bản phân phối mã nguồn (“open code”), không phải thư viện cài đặt — CLI copy .tsx thật vào components/ui/, bạn sở hữu và sửa mọi dòng, không hộp đen, không !important, không kẹt version.
• Mỗi component = Radix (hành vi + a11y, Phần 7/8) + Tailwind (vẻ ngoài, Phần 2/4) + cva (variants, Phần 5) + cn (merge class, Phần 5) + token ngữ nghĩa (theme, Phần 3). shadcn chỉ ráp lại có gu.
• init ghi components.json (manifest), chèn token CSS theme, và tạo cn(). Đọc kỹ từng field của components.json — đặc biệt aliases.utils và tailwind.css.
• add <comp> copy mã nguồn vào components/ui/, tự cài dep Radix, thêm cva/clsx/tailwind-merge. add <URL> lấy từ registry bất kỳ (cơ chế Distribution).
• Cập nhật là merge tay qua diff, không phải npm update. --overwrite chỉ an toàn khi bạn chưa sửa file.
• Tailwind v4: tailwind.config rỗng, token trong CSS, màu OKLCH. React 19: bỏ forwardRef. Hai lỗi alias (Vite + aliases.utils) là sự cố setup phổ biến nhất.

Tiếp theo

Phần 10 — Theme & tùy biến shadcn: cách theme biến-CSS hoạt động sâu, dựng light/dark mode, tạo theme brand riêng, tùy biến component đã copy, và dựng registry của bạn để phát hành & chia sẻ component qua URL.