puck

Puck

Puck は React 用のビジュアルエディターです。config でアプリのコンポーネントのうち編集可能にするものを宣言し、エディターが JSON の Data ペイロードを生成します。アプリはそのペイロードを保存し、<Render> で再びレンダリングします。データはアプリが所有するため、ホスト型のコンテンツストアはありません。

基本原則

1. まずドキュメントを確認します。 Puck のコードを記憶だけで書いてはいけません。関連するページを取得してください（下記のドキュメントを参照）。API は変化するため、フィールド名やプロパティ名を間違えるコストは取得の手間を上回ります。0.21 でパッケージのスコープが変更されました（@measured/puck → @puckeditor/core）。バージョンに左右される案内をする前に、npm ls @puckeditor/core を実行してください。
2. アプリの実際のコンポーネントを公開します。 統合の価値は config にあります。アプリにすでにコンポーネントがある場合、汎用的な Hero／Text／Button ブロックを作らないでください。
3. Puck に合わせてアプリの形を変えないでください。 アプリのコンポーネントを編集するのではなく、コンポーネントの render 内で調整してください。
4. 編集を始める前に範囲を確認します。 どのコンポーネントを編集可能にするか、どのルートを追加するか、Data をどこに保存するかはユーザーが決めることです。誤った場合のコストが大きい項目でもあります。
5. 型チェックではなくブラウザーで検証します。 コンパイルできても、すべてのコンポーネントがスタイルなしでレンダリングされるのは、初回実行時にはよくある結果であり、成功ではありません。

ドキュメント

すべてのドキュメントページは、URL の末尾に .md を追加すると Markdown 形式で取得できます。HTML ではなく、こちらを取得してください。

https://puckeditor.com/docs/getting-started.md
https://puckeditor.com/docs/api-reference/fields/slot.md

https://puckeditor.com/llms.txt はページの完全なインデックスです。どのページに情報があるか分からない場合は、まずこれを取得してから、該当ページの .md を取得してください。

注意：現在、.md への変換ではコードブロックから import 行が削除されるため、取得した例には必要な import が含まれず、使い方のみが示されます。ページに別の記載がない限り、すべて @puckeditor/core からインポートします。

最小限の統合

API 全体を 3 つのファイルで示します。型、フィールド、プロパティについては、コンポーネントの設定と<Puck> リファレンスに記載されています。

// puck.config.tsx — maps the app's components to editable Puck components
import type { Config } from "@puckeditor/core";
import { Hero } from "@/components/Hero";

type Props = { Hero: { title: string } };

export const config: Config<Props> = {
  components: {
    Hero: {
      fields: { title: { type: "text" } },
      defaultProps: { title: "Hello, world" },
      render: ({ title }) => <Hero title={title} />,
    },
  },
};

// The editor — client-only. Import "@puckeditor/core/puck.css" from the server parent.
"use client";
import { Puck } from "@puckeditor/core";
import { config } from "@/puck.config";

export function Editor({ data }: { data: any }) {
  // onPublish receives the Data payload — persist it wherever the app stores content
  return <Puck config={config} data={data} onPublish={save} />;
}

// The page — server-safe
import { Render } from "@puckeditor/core";
import { config } from "@/puck.config";

export default function Page({ data }: { data: any }) {
  return <Render config={config} data={data} />;
}

新しいアプリケーションの開始

npx create-puck-app my-app は、レシピを使ってひな形を作成します。レシピは next、next-ai、react-router、react-router-ai です。ユーザーが使うフレームワークに合わせて選び、Puck AI を使いたい場合に限り -ai 版を選んでください（references/ai.md）。

変更を加える前に、生成された README を読んでください。レシピには、実際のアプリで置き換える必要がある意図的な簡略化が含まれています。認証なしの /edit ルートと、データベースではなくローカルファイルシステムへの永続化です。どちらもデプロイ前に修正する必要があります。その後は、references/integration.md の config、永続化、認証に関するガイダンスをそのまま適用できます。

ユースケース別リファレンス

• 既存アプリケーションへの Puck のエンドツーエンドでの追加：references/integration.md
• 公開する既存コンポーネントの選択と、そのフィールドの設計：references/config-authoring.md
• 特定のフレームワークやルーター向けのエディターおよびレンダールートの設定：references/frameworks.md
• 統合の不具合の診断（スタイルなしのプレビュー、FOUC、RSC エラー、ハイドレーション、ドラッグ＆ドロップ）：references/troubleshooting.md
• チャットでページを生成するプラグイン、Puck AI の追加：references/ai.md
• このスキルに関するフィードバックの送信：references/skill-feedback.md

読む前に知っておくべき事実

• <Puck> はクライアント側専用です。RSC セーフな API は <Render> と resolveAllData だけです。
• <Puck> のマウント後に data を変更することはできません。レンダリング前に読み込んでください。
• Puck はキャンバスを iframe 内にレンダリングし、ホストのスタイルシートを iframe 内に同期します。「Puck が 動作しない」という報告の大半は、アプリのスタイルがその iframe に適用されていないことが原因です — references/troubleshooting.md。
• 入れ子になったドラッグ＆ドロップ領域には slot フィールドを使用してください。従来の DropZone コンポーネントには RSC に関する問題があります。
• エディタールートと保存エンドポイントは、コンテンツを書き込む場所です。公開前に、アプリの認証を必ず適用してください。