Thiết kế Theme Engine giống popular CMS nhưng dành cho Next.js

Mục tiêu của theme system

Theme kiểm soát layout, header, footer, typography, color, content template, navigation, block và responsive behavior. Theme không nên truy cập trực tiếp database, bypass authorization hoặc chứa business logic không kiểm soát. Business logic thuộc về plugin; theme tập trung vào presentation layer.

Theme package và manifest

Theme được đóng gói với layouts, templates, blocks, styles, public assets và theme.json. Manifest khai báo version, compatibility, template mapping, design token và dependency được phép.

Theme contract và view model

Theme không phụ thuộc trực tiếp database schema. Core chuyển dữ liệu thành stable view model như PostPageModel, SiteViewModel, NavigationViewModel và SeoViewModel. Core có thể thay đổi persistence layer mà không phá theme nếu contract vẫn tương thích.

z-theme-orchid/
├── theme.json
├── src/layouts/
├── src/templates/
├── src/blocks/
├── src/styles/
└── public/assets/

Template resolution

Theme Resolver chọn template theo route type, content type và lựa chọn của editor. Thứ tự thường là custom template → content-type template → generic template → Core fallback. Nếu theme thiếu PostPage, Core vẫn có thể render bằng default template.

Block-based rendering

Nội dung trang được lưu thành block data thay vì hard-coded layout. Theme đăng ký renderer cho hero, feature-grid, CTA hoặc block do plugin cung cấp. Nếu theme không có custom renderer, plugin default renderer hoặc Core fallback sẽ được sử dụng.

Core View Model
    ↓
Template Resolver
    ↓
Theme Template
    ↓
Block Renderer
    ↓
Server/Client Components

Design token và Theme Customizer

Color, font, spacing và container width được khai báo trong theme.json. Administrator chỉnh trong Theme Customizer; Core sinh CSS variables như --z-color-primary để theme sử dụng mà không cần sửa source.

Server Component và Client Component

Phần lớn template nên là Server Component để giảm JavaScript gửi xuống browser, hỗ trợ SEO và data fetching. Chỉ component tương tác như mobile menu hoặc slider mới cần use client. Theme build pipeline phải bundle đúng hai loại component.

Theme sandboxing và SDK boundary

Theme chỉ import từ @z-cms/theme-sdk và dependency allowlist. Nó không được import node:fs, raw database adapter hoặc server internals. Source được scan và build trước activation.

Inheritance, preview và hot activation

Child theme có thể override một số template hoặc style của parent theme. Preview context cho administrator xem theme mới mà public user vẫn thấy theme hiện tại. Activation chỉ diễn ra sau build validation và render smoke test, sau đó cache được invalidate theo tenant, theme ID và version.

Multi-tenant và plugin compatibility

Mỗi tenant có active theme riêng. Plugin có thể đăng ký block hoặc UI contract, còn theme cung cấp renderer phù hợp. Cùng một plugin vì vậy có thể hoạt động với nhiều theme mà không sửa business logic.

Kết luận

Theme Engine cho Next.js không chỉ là đổi CSS. Nó cần package contract, template resolution, block renderer, Server/Client Component boundary, design token, inheritance, preview, build validation, cache invalidation và multi-tenant resolution. Z-CMS giữ sự linh hoạt của theme ecosystem truyền thống nhưng sử dụng TypeScript, React và Next.js.

Key takeaways

• Security boundary phải được enforce trong Core, không dựa vào thiện chí của plugin.
• Lifecycle, permission, tenant context và observability là các phần của cùng một platform contract.
• Developer experience tốt chỉ bền vững khi runtime và supply chain được thiết kế an toàn từ đầu.

GitHub: https://github.com/zscontributor/z-cms
Website: https://z-cms.org