Hoàn thành bài "Bài 4: Xây Dựng Các Trang Chính của Website" trước để mở khoá bài này.Đến bài trước

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.

sơ đồ kiến trúc headless CMS gồm 3 khối: Editor dùng Sanity Studio, Sanity Cloud lưu dữ liệu, Frontend HTML kéo dữ liệu qua API

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:

bash
npm create sanity@latest -- --template clean --create-project "my-business-site" --dataset production

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:

bash
cd studio
npm install
npm run dev

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:

text
studio/
schemaTypes/
index.ts ← đăng ký tất cả schema ở đây
product.ts ← schema sản phẩm (sẽ tạo)
post.ts ← schema bài viết (sẽ tạo)
sanity.config.ts ← cấu hình chính của Studio

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:

typescript
import { defineType, defineField } from 'sanity'
export const productType = defineType({
name: 'product',
title: 'Sản phẩm',
type: 'document',
fields: [
defineField({
name: 'name',
title: 'Tên sản phẩm',
type: 'string',
validation: (Rule) => Rule.required(),
}),
defineField({
name: 'slug',
title: 'Slug (URL)',
type: 'slug',
options: { source: 'name' },
validation: (Rule) => Rule.required(),
}),
defineField({
name: 'price',
title: 'Giá (VNĐ)',
type: 'number',
validation: (Rule) => Rule.required().min(0),
}),
defineField({
name: 'mainImage',
title: 'Ảnh đại diện',
type: 'image',
options: { hotspot: true },
}),
defineField({
name: 'description',
title: 'Mô tả',
type: 'text',
}),
],
})

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:

typescript
import { defineType, defineField } from 'sanity'
export const postType = defineType({
name: 'post',
title: 'Bài viết',
type: 'document',
fields: [
defineField({
name: 'title',
title: 'Tiêu đề',
type: 'string',
validation: (Rule) => Rule.required(),
}),
defineField({
name: 'slug',
title: 'Slug',
type: 'slug',
options: { source: 'title' },
validation: (Rule) => Rule.required(),
}),
defineField({
name: 'publishedAt',
title: 'Ngày đăng',
type: 'datetime',
}),
defineField({
name: 'body',
title: 'Nội dung',
type: 'array',
of: [{ type: 'block' }],
}),
],
})

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:

typescript
import { productType } from './product'
import { postType } from './post'
export const schemaTypes = [productType, postType]

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.

sơ đồ luồng từ định nghĩa schema TypeScript qua Sanity Studio đến document được lưu trên Sanity Cloud

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.

Luyện tập sau buổi học

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.

0/7
01Sanity được gọi là 'headless CMS' vì điều gì?
02Sau khi chạy lệnh khởi tạo Sanity và cài đặt xong, bạn truy cập Sanity Studio local tại địa chỉ nào?
03Trong schema sản phẩm, field 'slug' được cấu hình với options: { source: 'name' } có tác dụng gì?
04Để định nghĩa nội dung rich text (bài viết có định dạng) trong Sanity, cách kết hợp đúng là gì?
05Sau khi tạo file schema mới (ví dụ product.ts), bước bắt buộc tiếp theo để schema xuất hiện trong Studio là gì?
06Field name trong schema Sanity khác với title ở điểm quan trọng nào?
07options: { hotspot: true } trong field kiểu 'image' có tác dụng gì?
Đã trả lời · 0/7