artifacts-builder

Artifacts Builder

claude.ai のアーティファクトをビルドするには、次の手順に従ってください。

1. scripts/init-artifact.sh を使ってフロントエンドのリポジトリを初期化します
2. 生成されたコードを編集して、アーティファクトを開発します
3. scripts/bundle-artifact.sh を使って、すべてのコードを単一の HTML ファイルにバンドルします
4. アーティファクトをユーザーに表示します
5. （任意）アーティファクトをテストします

スタック：React 19 + TypeScript + Vite + Tailwind CSS v4 + shadcn/ui（Radix）。Bun でインストールして実行します。バンドルには vite-plugin-singlefile を使用します。

要件：Bun および Node.js 20.19+ または 22.12+ が必要です（Vite の最小要件です。これより古いバージョンは初期化スクリプトで拒否されます）。

デザインとスタイルのガイドライン

非常に重要：「AI スロップ」と呼ばれることが多いものを避けるため、過度に中央寄せしたレイアウト、紫のグラデーション、統一された角丸、Inter フォントは使用しないでください。

クイックスタート

ステップ 1：プロジェクトを初期化する

初期化スクリプトを実行して、新しい React プロジェクトを作成します（同じ名前のプロジェクトがすでに存在し、そのディレクトリが空でない場合は拒否されます）。

bash scripts/init-artifact.sh <project-name>
cd <project-name>

これにより、次の設定がすべて済んだプロジェクトが作成されます。

• ✅ React + TypeScript（bun create vite 経由）
• ✅ Tailwind CSS v4（CSS ファースト）：src/index.css の @import "tailwindcss"、@theme inline 内のトークン、@tailwindcss/vite プラグイン。tailwind.config.* はありません
• ✅ shadcn/ui の初期化（components.json、OKLCH テーマ変数、cn ユーティリティ、tw-animate-css）。src/components/ui にすべてのコンポーネントが含まれます
• ✅ tsconfig と Vite で設定されたパスエイリアス（@/）
• ✅ Button と Card を使ったスターターの src/App.tsx

後から bunx shadcn@latest add <component> でコンポーネントを追加または更新できます。

ステップ 2：アーティファクトを開発する

アーティファクトをビルドするには、生成されたファイルを編集します。

ステップ 3：単一の HTML ファイルにバンドルする

React アプリを単一の HTML アーティファクトにバンドルするには、次のコマンドを実行します。

bash scripts/bundle-artifact.sh

これにより、JavaScript、CSS、依存関係がすべてインライン化された、自己完結型のアーティファクト bundle.html が作成されます。このファイルは、アーティファクトとして Claude との会話で直接共有できます。

要件：プロジェクトのルートディレクトリに index.html が必要です。

スクリプトの処理内容：

• 不足している場合は、vite-plugin-singlefile、parse5、css-tree を（バージョンを正確に固定して）開発依存関係としてインストールします。同一プロジェクト内で複数の実行が競合しないよう、ロックを使用します
• vite.config.* を拡張し、すべての JS、CSS、フォント、アセットを index.html にインライン化する vite.singlefile.config.ts を書き込みます
• この設定と実行ごとの --outDir を使って bunx vite build を実行します（オブジェクト形式、Promise 形式、関数形式の vite.config.* のいずれも動作します。また、保持されているカスタムの vite.singlefile.config.ts が build.outDir をハードコードしている場合も、その設定が尊重されます）
• HTML または CSS が参照するファイル（画像、フォント、アイコン、有効な srcset／imagesrcset の候補、リンクされたスタイルシート、拡張子に関係なく CSS として処理される @import の参照先、およびそのスタイルシートの URL ディレクトリを基準に解決される独自の url() 依存関係）をデータ URI としてインライン化し、#fragments は保持します。インライン化できないローカル参照がある場合は、その一覧を表示して失敗します
• parse5 で HTML を解析します（ブラウザー相当のトークン化：<!--> コメントの復元、大文字・小文字を区別しない属性、引用符で囲まれていない属性、&copy や € などの文字参照に対応）。また、解析後も同じ DOM になるように HTML を書き戻します（pre、textarea、listing の先頭の改行と doctype 識別子を保持します）。CSS は css-tree の CSS Syntax 3 トークナイザーでトークン化します。url()、URL()、u\72l()、@import／@IMPORT、image-set の文字列は対象となりますが、content:"url(x)" とコメントは対象外です。また、CSS のエスケープは仕様に従います（\61 の後ろに続く NBSP は保持されます）。不正な url() トークンがある場合、バンドルは失敗します。記述子が無効な srcset 候補（0w、1x 2x、100w 2x など）はブラウザーと同様に破棄されますが、有効な候補が見つからない場合は失敗します
• 実行ごとに専用の一時作業ディレクトリでビルドするため、複数の実行が競合しません。参照される各ファイルは、パスの各要素を順にたどり、ビルド内および public/ 内のシンボリックリンク、ハードリンクされたファイル、通常のファイル以外を拒否しながら、まず専用のスナップショットディレクトリ（モード 0700、処理後に削除）にコピーされます。インライン化ではスナップショットのみを読み取るため、処理中に親ディレクトリを差し替えて他のバイト列を注入することはできません
• 書き戻した HTML を再解析して検証することで、元と同じ DOM になることを確認します（ドキュメントモード、名前空間、属性、すべての script 要素と style 要素を検証）。書き換えた CSS の文字列では < と > をエスケープし、データ URI のフラグメントはパーセントエンコードします。差異（例：<plaintext> 要素）があれば、ページが変更されるのではなく、バンドルが失敗します
• 依存関係のインストールは、所有者（pid と開始時刻）を記録するロックディレクトリで直列化します。強制終了された実行が残したロックは検出され、引き継がれます
• すべての手順が成功してから bundle.html を置き換えるため、ビルドに失敗しても以前のバンドルは失われません

脅威モデル：保護の対象は、プロジェクトに含まれるシンボリックリンクとハードリンク、および悪意のあるページ、スタイルシート、public/ ツリーが参照できるものです。スクリプトの実行中にスナップショットのコピーそのものを競合させる、同じマシン上の攻撃者に対する防御ではありません。

JavaScript 内にハードコードされたパス文字列だけで参照されるファイルは検出されません。コードからインポートしてください（Vite がインライン化します）。または、HTML か CSS から参照してください。

ステップ 4：アーティファクトをユーザーと共有する

最後に、バンドルした HTML ファイルを会話でユーザーと共有し、アーティファクトとして表示できるようにします。

ステップ 5：成果物のテスト／可視化（任意）

成果物をテスト／可視化するには、利用可能なツール（他のスキルや、Playwright、Puppeteer などの組み込みツールを含む）を使用してください。一般的には、成果物を事前にテストするのは避けてください。リクエストから完成した成果物を確認できるまでの時間が長くなるためです。ユーザーから依頼された場合や問題が発生した場合は、成果物を提示した後でテストしてください。

参考資料

• shadcn/ui：https://ui.shadcn.com/docs（このマーケットプレイスの shadcn および tailwind スキルも参照してください）