Giới thiệu
Sanity là một headless CMS — tức là hệ thống quản lý nội dung tách biệt hoàn toàn phần backend (lưu trữ và chỉnh sửa dữ liệu) khỏi phần frontend (hiển thị ra trình duyệt). Điều này có nghĩa là bạn viết schema để định nghĩa cấu trúc dữ liệu, còn Sanity lo phần lưu trữ và cung cấp API để frontend kéo dữ liệu về.
Trong bài này bạn sẽ khởi tạo dự án Sanity đầu tiên, làm quen với Sanity Studio — giao diện quản trị chạy ngay trên trình duyệt — và viết schema cho hai loại nội dung hay gặp nhất trong website doanh nghiệp: sản phẩm và bài viết.
Khởi tạo dự án Sanity
Trước tiên bạn cần có Node.js (từ v18 trở lên) và một tài khoản Sanity miễn phí tại sanity.io. Sau đó chạy lệnh sau trong terminal, bên trong thư mục gốc của dự án website:
CLI sẽ hỏi bạn một vài câu: đăng nhập tài khoản Sanity, đặt tên project, chọn dataset (cứ giữ nguyên "production"). Khi xong, bạn sẽ thấy một thư mục mới — mặc định tên là studio hoặc tên bạn đặt — chứa toàn bộ mã nguồn của Sanity Studio.
Để chạy Studio lên môi trường local:
Truy cập http://localhost:3333 trên trình duyệt, bạn sẽ thấy giao diện Sanity Studio. Lúc mới khởi tạo với template clean thì Studio trống — chưa có document type nào vì chúng ta chưa định nghĩa schema.
Hiểu cấu trúc thư mục và schema
Bên trong thư mục studio, phần quan trọng nhất là schemaTypes. Đây là nơi bạn định nghĩa các loại dữ liệu. Cấu trúc cơ bản:
Mỗi file schema là một object TypeScript (hoặc JavaScript) mô tả cấu trúc của một loại document — tương tự như bạn định nghĩa một bảng trong cơ sở dữ liệu, nhưng linh hoạt hơn nhiều.
Định nghĩa schema sản phẩm
Tạo file schemaTypes/product.ts với nội dung sau:
Một vài điểm cần chú ý: type: 'slug' giúp Sanity tự sinh URL-friendly slug từ tên sản phẩm, chỉ cần nhấn nút Generate trong Studio. options: { hotspot: true } cho phép người dùng chọn vùng ảnh quan trọng khi crop. validation là tùy chọn nhưng rất nên dùng để tránh nhập thiếu dữ liệu.
Tiếp theo tạo schemaTypes/post.ts cho bài viết blog:
type: 'array' kết hợp of: [{ type: 'block' }] là cách Sanity biểu diễn rich text — gọi là Portable Text. Đây là định dạng chuẩn của Sanity, sau này khi render ra HTML bạn sẽ dùng thư viện @portabletext/html để chuyển đổi.
Cuối cùng, đăng ký cả hai schema vào schemaTypes/index.ts:
Lưu file, Studio đang chạy sẽ tự reload. Bạn sẽ thấy hai mục Sản phẩm và Bài viết xuất hiện trong sidebar trái của Studio.

Lỗi thường gặp
Lỗi hay gặp nhất khi mới bắt đầu là quên đăng ký schema vào file index.ts. Schema đã tạo nhưng không import vào mảng schemaTypes thì Studio sẽ không hiển thị document type đó.
Lỗi thứ hai là đặt name trùng nhau giữa các field hoặc giữa các schema. Sanity dùng name (không phải title) làm định danh nội bộ, nên name phải là chuỗi không dấu, không khoảng trắng, viết camelCase.
Nếu chạy npm run dev mà gặp lỗi xác thực, hãy chắc chắn bạn đã chạy sanity login trong terminal và tài khoản đang đăng nhập có quyền truy cập project đó.
Tổng kết
Bạn đã khởi tạo xong dự án Sanity, hiểu cấu trúc thư mục schema, và định nghĩa được hai document type cơ bản cho website doanh nghiệp. Quy trình sẽ lặp lại mỗi khi cần thêm loại nội dung mới: tạo file schema, định nghĩa các field phù hợp, đăng ký vào index.ts. Bài tiếp theo sẽ kết nối Studio này với phần frontend HTML để kéo và hiển thị dữ liệu sản phẩm thực tế lên trang web.
Bài kiểm tra cuối bài
Ôn lại kiến thức, thử sức và nhận góp ý cho bài làm.