cloudcannon-dev-server

CloudCannon 開発サーバー

cloudcannon dev は、ログインせずに、単一のオリジンでローカルファイルを使って実際の CloudCannon アプリを実行します。このスキルは、ローカルでの編集ループを開始し、ユーザーに引き継ぎます。

最も多くのセッションを無駄にするルール

変更を加えるたびに、必ずサイトを再ビルドしてください。cloudcannon dev はビルドを実行しません。

理由： サーバーはディレクトリを配信し、ソースファイルを同期しますが、SSG は実行しません。--app-sync はエディターでの保存内容をディスクに反映するため、フィールドには新しいテキストが表示されます。しかし、プレビューはビルド済みの出力をレンダリングするため、何も再生成されていなければ、ユーザーにはフィールド内の編集内容と、その横に古いページが表示されます。どこにもエラーは表示されません。

ループ

cloudcannon configure detect-build-commands   # build command and output directory
<build the site>                              # see The build command, below
cloudcannon dev <output-dir> --port 10101     # leave running

次に、http://localhost:10101 を開くよう伝え、Ctrl-C でサーバーを停止できることも伝えてください。

ユーザーの操作	起きること
エディターでソースファイルを変更	ディスクに反映されます。再ビルドすると、プレビューが自動で更新されます
ディスク上のソースファイルを変更	同様に、サーバーがアプリ内に同期します。再ビルドすると、同じ結果になります

出力ディレクトリが変更されるたびにプレビューが自動で再読み込みされるため、2 つ目のターミナルで再ビルドすれば、ほかに何も実行しなくてもループが完結します。dev-server-api.md § イベントを参照してください。

次の 2 つの方法を提示し、どちらにするかユーザーに選んでもらってください。

方法	ユーザーの操作	コスト
手動	編集をまとめて行った後にビルドを再実行する	ありません。プレビューを更新したいときに再ビルドします
監視	watch-build.mjs を実行する	変更ごとにフルビルドを行います

デフォルトでは手動を選んでください。保存のたびに監視ビルドを行うと出力ディレクトリが変更され、プレビューはページ全体を再読み込みします。その再読み込みによって、編集可能な領域が個別に行うインプレース再レンダリングが隠れてしまうため、ビジュアル編集のテストが不自然に感じられます。手動方式は、ビルドに時間がかかる場合や、ビルド後に出力全体を書き換える処理がある場合にも適しています。

編集可能な領域だけでは自動で再レンダリングされない編集内容（ソースエディターで編集したコンテンツ、データファイル、テンプレート、スタイルなど）もプレビューに反映したい場合は、監視方式を提案してください。

ビルドコマンド

設定ファイルを探すのではなく、CLI を使ってビルドを必ず検出してください。 cloudcannon configure detect-build-commands は、この製品独自の検出機能で、CLI が対応するすべての SSG を対象にしています。このスキル内のどこにも、別の検出用テーブルを作成してはいけません。CLI の検出結果と食い違うためです。提示されたコマンド（npm run build）を使い、SSG のコマンドをそのまま使わないでください。setup.md § ビルドコマンドを参照してください。

使用する場合

• ユーザーが、サイトのデプロイ先を決める前に CloudCannon 上でサイトを確認し、編集したい場合
• 編集可能な領域、コレクション、入力項目を作成したばかりで、ユーザーが試す必要がある場合
• ユーザーから CloudCannon でページが表示されない、空白になる、または壊れていると報告があり、実際のアプリを使ってローカルで再現する必要がある場合

使用しない場合

• コレクション、入力項目、構造の作成 — その場合は cloudcannon-configuration を使用してください。このスキルは結果を提供しますが、結果を決定するものではありません。
• 編集可能領域の作成 — その場合は cloudcannon-visual-editing を使用してください。
• サイトの出力が正しいかどうかの確認 — URL がコレクション設定と一致しているか、孤立したページがないかなどの確認です。このスキルはサーバーを起動しますが、サイトを評価するものではありません。
• ブラウザーでのエディター操作 — 領域のクリック、入力項目の出力、スクリーンショットの撮影などです。ユーザーに確認してもらってください。
• 最終承認。 ローカルの CloudCannon には、実際の Git への保存機能もビルドパイプラインも権限設定もありません。ホストされたサイトで人間が確認する必要があります。
• ホスト環境でのみ発生する動作のテスト。 ローカルアプリには SSG が指定されていないため、SSG 固有のルールはローカルでは適用されません。たとえば Hugo サイトでは、include_developer_files がなくても、設定ファイルがローカルのコレクションに表示されます（サイト設定をデータとして扱う）。新しいファイルの作成も忠実なテストにはなりません。未保存の新しいエントリーには一時的なフラット名が付けられるためです。

内容

ファイル	内容
setup.md	前提条件、cloudcannon dev が実行することと実行しないこと、ビルド、ポート
dev-server-api.md	/__api の仕様 — すべてのルートとイベントストリーム
troubleshooting.md	症状 → 原因 → 解決策
scripts/README.md	watch-build.mjs とそのフラグ

よくある誤解

言い訳	実際のところ
「cloudcannon dev が動いているので、反映の流れは機能しています。」	ディレクトリを配信しているだけで、それ以外の機能はありません。何かが再ビルドするまでは、最後にビルドされた内容がプレビューに表示されます。
「エディターで保存したのに、ページが変わりません。」	それは想定どおりです。再ビルドしてください。ウォッチャーを使っている場合は、ビルドが完了するまで待ちます。
「ビルド済みページを見るために /index.html を開きます。」	/ と /index.html はどちらも CloudCannon アプリを配信します。ビルド済みのホームページは /__output/index.html にあります。
「/about/ が 500 を返すので、サーバーが壊れています。」	サーバーにはディレクトリーインデックスがありません。/about/index.html をリクエストしてください。
「ポート 10101 が応答するので、サイトが起動しています。」	開発サーバーがそこにあることは示していますが、それが自分のサーバーだとは限りません。自分で選び、空いていることがわかっているポートで配信してください。
「差分が大きいので、何かが破損しました。」	保存時に CloudCannon はフロントマター全体を再シリアライズします。変更したフィールドを差分で確認してください。