はじめに

ZeroCode.jsは、フレームワーク非依存のWeb ComponentsベースのCMSエディターライブラリです。Vue.jsで実装されており、カスタムHTMLテンプレート構文を使用して動的なコンテンツ管理を提供します。

プロダクトの位置づけ・設計方針の詳細はZeroCode.js とはを参照してください。

読む順ガイド

組み込むエンジニア

パーツ（テンプレート）を書く人

サーバー側を実装する人

English reader? See the README (English) for an overview and quick start. This documentation is currently Japanese only.

ZeroCode.js とは

ZeroCode.js は、既存 Web サービスの認証・永続化・バックエンドデータをホスト側で担いながら、フロントエンドに後付けできる 埋め込み型 CMS ライブラリ です。

目的

既存 Web サービスの運営者が、開発者に依存せずページを更新・運用できる環境を提供します。

そのために、既存サービスの 認証・データ・HTML 構造の方針 を維持したまま導入できる CMS を、フロントエンドライブラリとして実現します。

解決したい課題

一般的な CMS やページビルダーは、CMS 独自の仕組みを持つことが多く、既存システムとの統合コストが発生します。

システム面

CMS 独自の認証を持つ
CMS 独自のデータ管理を持つ
既存システムとの連携・同期が必要になる

編集面

編集画面と公開画面に差異がある
実際の表示を確認しながら編集しづらい
CMS 都合の HTML や DOM 構造が生成される

運用面

CMS とアプリケーションの二重管理が発生する
ページ修正のたびに開発工数が発生しやすい
開発者と編集者の責務分離が曖昧になりやすい

設計方針

ZeroCode.js は、次の方針に基づいて設計されています。

システム

方針	内容
埋め込み型	既存 Web サービスへ後付けで導入する
バックエンド非提供	永続化・認証・認可はホストアプリが担当する
既存認証の利用	CMS 独自のログイン機能は持たない
イベント駆動の保存	保存ボタンで `save-request` を発火し、ホストが `getData()` で取得して永続化する

表示

方針	内容
WYSIWYG に近い編集	公開画面とほぼ同じ見た目・構造で編集する
編集用メタデータの分離	編集時のみ識別用の属性等を付与し、公開 HTML には載せない
差異の最小化	編集画面と公開画面の DOM 構造の差を小さく保つ

編集モードでは、主に data-zcode-id・data-zcode-path・data-zcode-part などの data-zcode-* 属性 が付与されます。公開レンダリング（SSR 含む）では enableEditorAttributes: false（デフォルト）により、これらは出力されません。

出力

方針	内容
開発者定義の HTML	公開 HTML は開発者が定義したパーツテンプレートから生成する
CMS 都合の DOM を挟まない	WordPress ブロックやページビルダー的な CMS 専用ラッパー markup は生成しない
記法の展開	`{$field}` や `z-if` などのテンプレート記法はレンダリング時に展開・除去される

補足: ZeroCode.js は「HTML を生成しない」のではなく、「CMS 内部都合の HTML を生成しない」という意味です。公開ページの HTML 構造の正は、開発者が定義したパーツテンプレート（part.body）です。

編集者向け（`<zcode-cms>`）

パーツの追加・削除・並べ替え
パーツ設定（フィールド）の編集
テキスト・画像の編集
パーツの組み合わせによるレイアウト構築

開発者向け（`<zcode-editor>` / `<zcode-studio>`）

独自記法でパーツテンプレートを定義する
編集可能な領域・設定項目（フィールド）を定義する
パーツ・画像・CSS を管理画面で登録・管理する
スロットでパーツの入れ子構成を定義する

定義

ZeroCode.js は、既存 Web サービスの認証・永続化・バックエンドデータをホスト側で担いながら、フロントエンドに後付けできる埋め込み型 CMS ライブラリです。

開発者が定義した パーツテンプレート を組み合わせ、運営者はノーコードでページを構築・編集できます。

公開 HTML はパーツテンプレートから生成され、CMS 都合の DOM は挟みません。編集時のみ data-zcode-* 等の識別情報を付与し、公開レンダリングでは除去してクリーンな HTML を出力します。

データの扱い

ZeroCode.js には2種類のデータがあります。

種類	説明	永続化
ページ編集データ	`page`・`parts`・`images`・`css` など ZeroCode 形式の JSON	ホストが `save-request` 受信後に永続化
バックエンドデータ	既存 API / DB から渡す参照用データ（`{@user.name}` 等）	ZeroCode は参照のみ。更新はホスト側

「データは既存システムを利用する」とは、認証・永続化・動的参照をホストに委ねる という意味です。ページ構成データそのものは ZeroCode 形式で管理されます。

コンポーネントと役割

コンポーネント	想定ユーザー	主な用途
`<zcode-cms>`	運営者・編集者	ページの編集・追加・削除・並べ替え
`<zcode-editor>`	開発者	パーツ管理・画像管理・データビューアを含むフル機能
`<zcode-studio>`	制作会社など信頼できるユーザー	`zcode-editor` 同等 UI。専用パーツ・専用 CSS・専用画像の編集に限定

ZeroCode.js が提供しないもの

次は 意図的に提供しません。ホストアプリ側で実装してください。

ユーザー認証・認可
データベース・API（永続化層）
自動保存（保存は保存ボタンと save-request のみ）
既存ページ DOM のその場直接編集（パーツテンプレートベースの構成）

技術的特徴（概要）

フレームワーク非依存 — Web Components として React / Vue / 素の HTML などに埋め込める
カスタムテンプレート記法 — フィールド・条件分岐・ループ・スロット等
SSR 対応 — zerocodejs/ssr の renderToHtml() で公開 HTML をサーバー生成可能
Beta — API・データ形式は変更される可能性があります

編集体験改善ロードマップ

社内ユーザーテスト（2026年）を踏まえ、ZeroCode.js 本体で対応した項目を Issue 分割しています。埋め込み先プロダクト固有の機能（公開画面・下書きフロー・スタッフ表示等）は含みません。

詳細・実装方針・受け入れ条件は TODO.md – Phase 5 を参照してください。GitHub Issue 作成時は ID（ZC-n）をタイトルに含めると追いやすいです。

順	ID	内容	状態
1	ZC-1	編集プレビューで `z-empty` によりパーツ内容が消える	完了
2	ZC-2	リッチテキスト空値の正規化	完了
3	ZC-3	編集パネル内ドラッグでパネルが閉じる（`useClickHandlers`）	完了
4	ZC-4	パーツ間の追加ボタン（追加モード時・先頭・入れ子対応）	完了
5	ZC-5	並べ替え D&D（構造リスト・スロット含む）	完了

クイックスタート

ZeroCode.jsをすぐに使い始めるための基本的な手順です。

インストール

npm install zerocodejs

ZeroCode.jsは内部でVue 3を使用しています。npm 7以降では、peer dependenciesが自動的にインストールされるため、npm install zerocodejsだけでVueも一緒にインストールされます。

注意: npm 6以前を使用している場合は、明示的にnpm install zerocodejs vueを実行してください。

基本的な使用例

CDNを使用した最も簡単な例（HTMLファイルをブラウザで開くだけで動作）：

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://unpkg.com/zerocodejs/dist/zerocodejs.css">
</head>
<body>
  <zcode-editor></zcode-editor>

  <script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
  <script src="https://unpkg.com/zerocodejs/dist/zerocode.umd.js"></script>
</body>
</html>

npmを使用した例：

<zcode-editor></zcode-editor>

<script type="module">
  import 'zerocodejs';
</script>

zcode-editorはエンジニア・デザイナー向けの管理画面で、パーツ管理・画像管理・データビューアが利用できます。はじめての方におすすめです。

zcode-cmsはエンドユーザー向けの管理画面で、編集・追加・削除・並べ替えのみが利用できます。

複数インスタンス対応

ZeroCode.jsは、同じページに複数のzcode-cmsやzcode-editorインスタンスを配置することができます。各インスタンスは独立したデータを管理し、互いに影響を与えません。

<!-- インスタンス1 -->
<zcode-cms id="cms-1">
  <link slot="css" rel="stylesheet" href="/css/common.css" />
</zcode-cms>

<!-- インスタンス2 -->
<zcode-cms id="cms-2">
  <link slot="css" rel="stylesheet" href="/css/common.css" />
</zcode-cms>

<script type="module">
  import 'zerocodejs';

  // 各インスタンスに独立したデータを設定
  const cms1 = document.getElementById('cms-1');
  cms1.setAttribute('page', JSON.stringify([...]));
  cms1.setAttribute('parts-common', JSON.stringify([...]));

  const cms2 = document.getElementById('cms-2');
  cms2.setAttribute('page', JSON.stringify([...]));
  cms2.setAttribute('parts-common', JSON.stringify([...]));
</script>

動作：

独立したデータ管理: 各インスタンスはid属性で識別され、独立したデータを管理します
セッションストレージの分離: セッションストレージはインスタンスIDごとに分離され、データが混在することはありません
イベントリスナーの分離: 各インスタンスのイベントリスナーは独立して動作します
IDの自動生成: id属性が指定されていない場合、自動的に一意のIDが生成されます

注意: 複数インスタンスを使用する場合は、各インスタンスに一意のid属性を指定することを推奨します。これにより、データの管理が明確になり、デバッグも容易になります。

CDN経由で使用する場合

CDN経由で使用する場合は、Vueを先に読み込む必要があります。

<!-- Vueを先に読み込む -->
<script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
<!-- ZeroCode.jsを読み込む -->
<script src="https://unpkg.com/zerocodejs/dist/zerocode.umd.js"></script>
<link rel="stylesheet" href="https://unpkg.com/zerocodejs/dist/zerocodejs.css">

<zcode-cms id="cms">
  <link slot="css" rel="stylesheet" href="/css/common.css" />
</zcode-cms>

<script>
  const cms = document.getElementById('cms');
  cms.setAttribute('page', JSON.stringify([]));
  cms.setAttribute('parts-common', JSON.stringify([]));
  cms.setAttribute('parts-individual', JSON.stringify([]));
  cms.setAttribute('parts-special', JSON.stringify([]));
  cms.setAttribute('images-common', JSON.stringify([]));
  cms.setAttribute('images-individual', JSON.stringify([]));
  cms.setAttribute('images-special', JSON.stringify([]));
</script>

Shadow DOM

ZeroCode.jsは、デフォルトでShadow DOMを使用してCSS/JSを完全に分離します。これにより、呼び出し側のCSSやJavaScriptとの競合を防ぎ、副作用のない安全な統合を実現します。

Shadow DOMの利点

CSS分離: ZeroCode.jsのスタイルが呼び出し側のCSSに影響を与えません
JavaScript分離: Shadow DOM内のスクリプトが外部のJavaScriptと競合しません
セキュリティ: 外部からのスタイルやスクリプトの干渉を防ぎます

ホストスタイルのリセット（:host）

Shadow DOM を使うとき、カスタム要素（zcode-cms / zcode-editor / zcode-studio）にはホストページ側からフォントや文字色などが継承されることがあります。ZeroCode.js がシャドウ内に注入するスタイルシートの先頭では、:host に対して all: initial を指定し、この継承を一度リセットしています。

続けて明示しているのはレイアウト上ほぼ必須な display: block と、内部の .zcode-* と整合させるための box-sizing: border-box のみです。サイト固有のタイポグラフィや配色をライブラリ側で決めることはなく、ページに合わせた見た目が必要な場合は従来どおり slot="css" でシャドウに渡すスタイルシートなどで追加してください。

注意: Light DOM（use-shadow-dom="false"）では :host は効きません。ホストの CSS がそのまま影響するため、競合対策は別途検討してください。

Shadow DOMの無効化

use-shadow-dom="false"属性を指定することで、Shadow DOMを無効化できます（Light DOMモード）。

<zcode-cms id="cms" use-shadow-dom="false">
  <link slot="css" rel="stylesheet" href="/css/common.css" />
</zcode-cms>

注意: Shadow DOMを無効化すると、CSSやJavaScriptの競合が発生する可能性があります。通常はShadow DOMを使用することを推奨します。

Shadow DOM内でのjQuery使用

ZeroCode.jsは、Shadow DOM内でjQueryを使用する場合に自動的に拡張を行います。これにより、Shadow DOM内の要素に対してjQueryのセレクターやイベントハンドラーが正常に動作します。