popular CMS の柔軟性を Next.js で実現する Theme Engine 設計

Theme system の目的

Theme は layout、header、footer、typography、color、content template、navigation、block、responsive behavior を制御します。一方で raw database access、authorization bypass、無制限な business logic は持たせません。Business logic は plugin、presentation layer は theme が担当します。

Theme package と manifest

Theme package には layouts、templates、blocks、styles、public assets、theme.json を含めます。Manifest は version、compatibility、template mapping、design token、許可 dependency を宣言します。

Theme contract と view model

Theme は database schema に直接依存しません。Core は data を PostPageModel、SiteViewModel、NavigationViewModel、SeoViewModel などの stable view model に変換します。Contract が維持されれば persistence layer の変更で theme は壊れません。

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

Template resolution

Theme Resolver は route type、content type、editor selection から template を選びます。優先順位は custom template → content-type template → generic template → Core fallback です。Theme に PostPage がなくても default template で render できます。

Block-based rendering

Page content は hard-coded layout ではなく block data として保存します。Theme は hero、feature-grid、CTA、plugin 提供 block の renderer を登録します。Custom renderer がない場合は plugin default renderer または Core fallback を使います。

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

Design token と Theme Customizer

Color、font、spacing、container width を theme.json に宣言します。Administrator は Theme Customizer で変更し、Core は --z-color-primary のような CSS variables を生成します。Source code の変更は不要です。

Server Component と Client Component

多くの template は Server Component とし、browser に送る JavaScript を減らし、SEO と data fetching を改善します。Mobile menu や slider など interaction が必要な component だけ use client を利用します。

Theme sandboxing と SDK boundary

Theme は @z-cms/theme-sdk と allowlist dependency のみ import できます。node:fs、raw database adapter、server internals への access は許可しません。Source は activation 前に scan と build を行います。

Inheritance、preview、hot activation

Child theme は parent theme の一部 template や style を override できます。Preview context により administrator だけが新 theme を確認し、public user は現行 theme を見続けます。Build validation と render smoke test 成功後に active pointer を切り替え、tenant・theme ID・version 単位で cache を invalidate します。

Multi-tenant と plugin compatibility

各 tenant は独立した active theme を持ちます。Plugin は block や UI contract を登録し、theme が対応 renderer を提供します。これにより同じ plugin business logic を複数 theme で利用できます。

結論

Next.js 向け Theme Engine は CSS の切り替えだけではありません。Package contract、template resolution、block renderer、Server/Client Component boundary、design token、inheritance、preview、build validation、cache invalidation、multi-tenant resolution が必要です。

Key takeaways

• Security boundary は plugin の善意ではなく Core 側で enforce する必要があります。
• Lifecycle、permission、tenant context、observability は同じ platform contract の一部です。
• 優れた developer experience は、安全な runtime と supply chain の設計によって持続可能になります。

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