コンテンツへスキップ

設定

Blockstudioには強力な設定APIがあり、テーマフォルダー内のblockstudio.jsonファイルやフィルターを使ってオプションを設定できます。また、許可されたユーザーは管理画面で設定を視覚的に変更できます。

JSON経由

テーマフォルダー内にblockstudio.jsonファイルがある場合、現在のサイトのデフォルトオプションとして使用されます。ファイルの検証やIDEでの自動補完に役立つJSONスキーマも用意されています。

このファイルは省略可能です。ファイルがない場合、Blockstudioは組み込みのデフォルトに加えて、管理画面に保存された設定を使用します。ファイルの追加、変更、削除は自動的に検出されるため、キャッシュの消去や手動での再読み込みは不要です。

利用可能なプロパティは次のとおりです:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "users": {
    "ids": [],
    "roles": []
  },
  "assets": {
    "enqueue": true,
    "reset": {
      "enabled": false,
      "fullWidth": []
    },
    "minify": {
      "css": false,
      "js": false
    },
    "process": {
      "scss": false
    }
  },
  "cache": {
    "enabled": true,
    "path": "blockstudio/cache"
  },
  "themeDefaults": {
    "titleTag": false,
    "suppressDirectoryUpdates": false
  },
  "performance": {
    "profile": "compat",
    "wordpress": {
      "headNoise": false,
      "embeds": false,
      "xmlrpc": false,
      "editor": false,
      "frontendAssets": false,
      "media": false,
      "heartbeat": false
    },
    "preload": {
      "links": "off"
    },
    "media": {
      "lazy": false,
      "skeleton": false,
      "metadata": false,
      "rootMargin": "300px"
    },
    "measurement": {
      "enabled": false,
      "queryMonitor": false,
      "headers": false,
      "timings": false
    }
  },
  "content": {
    "enabled": false,
    "id": "default",
    "path": "content",
    "includePageSyncManaged": false,
    "authors": "ignore",
    "postTypes": [],
    "meta": {
      "include": [],
      "exclude": ["_edit_lock", "_edit_last", "_wp_old_slug"],
      "references": {}
    },
    "taxonomies": [],
    "media": "manifest"
  },
  "editor": {
    "formatOnSave": false,
    "assets": [],
    "markup": false
  },
  "tailwind": {
    "enabled": false,
    "config": "",
    "output": "inline"
  },
  "blockTags": {
    "enabled": false,
    "allow": [],
    "deny": [],
    "prefixes": {}
  },
  "ui": {
    "enabled": false
  },
  "blockEditor": {
    "disableLoading": false,
    "enhance": false,
    "cssClasses": [],
    "cssVariables": [],
    "blocks": {
      "allow": [],
      "deny": [],
      "directory": true,
      "categories": {
        "allow": [],
        "deny": [],
        "rename": {},
        "order": []
      },
      "styles": {
        "deny": {}
      },
      "legacyWidgets": {
        "hide": []
      }
    },
    "patterns": {
      "core": true,
      "remote": true,
      "theme": true,
      "blockstudio": true,
      "categories": {
        "allow": [],
        "deny": [],
        "rename": {},
        "order": []
      }
    },
    "media": {
      "openverse": true,
      "imageSizes": {
        "allow": [],
        "deny": []
      }
    }
  },
  "dev": {
    "grab": {
      "enabled": false
    },
    "perf": false,
    "canvas": {
      "enabled": false,
      "adminBar": true
    }
  },
  "githooks": {
    "commit": false
  },
  "phpstan": {
    "preset": "base",
    "configuration": "",
    "roots": ["."],
    "excludePaths": [],
    "maxFiles": 10000
  },
  "ai": {
    "enableContextGeneration": false
  }
}

フィルター経由

または、blockstudio/settings/${setting}フィルターを使ってPHP経由でオプションを設定すると、柔軟性が高まります。

PHP
add_filter('blockstudio/settings/assets/enqueue', '__return_false');
add_filter('blockstudio/settings/editor/formatOnSave', '__return_true');
add_filter('blockstudio/settings/ui/enabled', '__return_true');
add_filter('blockstudio/settings/block_editor/patterns/remote', '__return_false');

blockstudio/settings/${setting}フィルターで設定したオプションは、blockstudio.jsonファイルで設定したオプションより優先されます。両方の方法を併用できます。

実行時の値はblockstudio/performance/${setting}フィルターと最後のblockstudio/performance/configフィルターにも公開されます。後者は有効な設定オブジェクトを返す必要があります。

設定ソースの優先順位

各ソースを読み込み、優先度の低いものから順に統合します:

  1. 組み込みのデフォルト
  2. 管理画面UIから保存した設定(blockstudio_settingsオプション)
  3. テーマ内のblockstudio.json
  4. blockstudio/settings/*フィルター

blockstudio.jsonは、宣言したキーのみを上書きします。以前は保存済み設定全体を置き換えていたため、ファイルが現れた時点で無関係な管理画面の保存値が適用されなくなっていましたが、現在は保存済み設定の上に重ねられます。その一方で、管理画面UIから保存した古い値は、ファイルでそのキーを宣言するか、保存値を削除するまで適用され続けます。ファイルの記述どおりに設定が動作しない場合は、wp bs settingsまたはSettings::get_raw()で保存済みの層を確認してください。これらは、現在有効なJSONまたはオプションソースで明示的に宣言された値のみを返します。

PHPから設定を読み取る

Blockstudio\Settingsは有効なソースを読み込み、不正なJSONを報告し、blockstudio.jsonが変更されると自動的に再読み込みします:

PHP
use Blockstudio\Settings;

$enabled = Settings::get_bool('performance/media/lazy');
$margin = Settings::get_string('performance/media/rootMargin', '300px');
$roles = Settings::get_array('users/roles');
$ttl = Settings::get_int('performance/staticPrerender/ttl', 86400);

foreach (Settings::errors() as $error) {
    error_log($error);
}

有効な JSON またはオプションソースで明示的に宣言された値だけが必要な連携には、Settings::get_raw() を使います。Settings::fingerprint() は、決定的な実効設定の識別子を返します。長時間実行するプロセスでは、ファイルの変更をすぐに反映するために Settings::reload() を明示的に呼び出せます。通常のアクセスでは、同じサイズの編集も含め、リクエスト内または長時間実行する PHP プロセス内で、ファイルの確認は最大1秒に1回です。設定したパスの変更は次の読み取り時に反映されます。有効な JSON ファイルがない場合、保存済みのデータベース設定はこの待機時間の影響を受けません。

解決済みのパフォーマンスプロファイルはBlockstudio\Runtime_Settings::current()から利用できます。スラッシュ区切りまたはドット区切りのパスに対応しています:

PHP
use Blockstudio\Runtime_Settings;

$runtime = Runtime_Settings::current();

if ($runtime->enabled('measurement/queryMonitor')) {
    $hash = $runtime->hash();
}

利用可能な設定

users

オプション 型 デフォルト 説明
ids 配列 [] エディターへのアクセス権を持つユーザーID
roles 配列 [] エディターへのアクセス権を持つユーザーロール

assets

オプション 型 デフォルト 説明
enqueue boolean true ブロックアセットを自動的にキューへ追加
reset.enabled boolean false コアブロックのスタイルを削除し、エディター用ユーティリティのリセットを適用
reset.fullWidth array [] 全幅エディターレイアウトを使用する投稿タイプ
minify.css boolean false CSS の出力を圧縮
minify.js boolean false JS の出力を圧縮
process.scss boolean false SCSS ファイルを処理
output string source コンパイル済みアセットの出力先: source または cache
inlineLimit integer 0 ページごとにインライン出力する外部ブロック CSS のバイト数

outputのデフォルトはsourceで、各ブロックの横に_distディレクトリを作成します。cacheに設定すると、コンパイル済みアセットはBlockstudioキャッシュディレクトリに出力されるため、ブロックのソースツリーをクリーンな状態に保ち、変更不可のチェックアウトからデプロイできます。ソースBlockstudioは、この設定にかかわらずキャッシュへのリダイレクトを書き込めません。

inlineLimit は 0 で無効になっているため、すべての外部スタイルシートは <link> タグを保持します。代わりにバイト数を設定すると、合計がその数以内である限り、ページ内の外部ブロックスタイルシートのうちサイズの小さいものからインライン出力します。40000 は、コアが同じルールに使用する上限 WordPress です。詳しくは、小さなスタイルシートをインライン出力 を参照してください。

reset.enabledが有効な場合、Blockstudioはサニタイズ済みのフロントエンドbody_class値もエディターキャンバスにコピーします。エディター専用のクラス一覧を調整するにはblockstudio/editor/canvas/body_classを使用します。

cache

オプション 型 デフォルト 説明
enabled 真偽値 true Blockstudioファイルベースのキャッシュを有効化
path 文字列 "blockstudio/cache" WP_CONTENT_DIRからの相対パス、または絶対パスで指定するキャッシュパス
namespaceGrace 整数 86400 廃止されたキャッシュ名前空間を削除まで保持する秒数

デフォルトでは、キャッシュファイルはwp-content/blockstudio/cacheに書き込まれ、uploadsディレクトリの外に保存されます。相対pathはWP_CONTENT_DIRを基準に解決され、絶対パスはそのまま使用されます。専用の書き込み可能なキャッシュボリュームを提供するホストに対応しています。

有効にすると、Blockstudioはビルドデータ、事前構築済みブロック登録データ、解決済みエディターアセット、Tailwind CSS、レンダリングドキュメント、アイランドフラグメント、静的プリレンダリング、グラフインデックス、キュー、診断情報をこの単一のルートに保存します。各オブジェクトは、ネットワーク、サイト、完全な実行時識別情報、スコープごとに分離されます。実行時識別情報には、Blockstudio、設定、WordPress、PHP、有効なテーマ、有効なプラグイン、論理的な検出ソース、ホストコンテキスト、所有する処理が指定する明示的な依存関係のハッシュが含まれます。

コンテンツ、ターム、ユーザー、メタデータの変更は、入力済みのフィールド選択肢を無効化しますが、ブロックの構造的な検出やコンパイル済みアセットには影響しません。選択肢は、固定されたビルドパスロックのもとで個別に更新されます。翻訳の同期やインポートなど、書き込みが短時間に集中した場合はまとめて処理されます。静かな期間の後の最初の書き込みで即時に更新され、集中した書き込みの最後の内容は、30秒が経過した時点で反映されます。この時間はblockstudio/cache/populate_debounceで調整できます。投稿編集ロックなど、WordPressが記録用に書き込むメタデータは変更として扱われません。blockstudio/cache/populate_ignored_meta_keysでそのリストを拡張できます。エディターは常に最新のオプションを照会するため、この時間枠が影響するのはレンダリング時に読み込まれるキャッシュ済みの選択肢だけです。ソースファイルとビルド設定は、引き続き通常どおり構造キャッシュを無効化します。選択肢を上書きしても、コンテンツが変更されるたびにキャッシュディレクトリを再スキャンすることはありません。定期的な整理では、孤立した一時ファイルが引き続き削除されます。言語固有のランタイムIDは分離されたままです。多言語サイトに複数のキャッシュ名前空間ディレクトリがあること自体は、キャッシュミスの証拠にはなりません。

ブロックのdbデータディレクトリ内でSQLiteのジャーナルが更新されても、キャッシュ済みのブロックメタデータは破棄されません。db.php、監視対象のソースファイル、またはデータディレクトリ内のソースファイルやサブディレクトリの構造に変更があった場合は、引き続きキャッシュが無効化されます。

実行時の同時再構築では、選出された1つのビルダーだけが処理します。他のリクエストは最大5秒待機し、その後、ソースファイルと必要なコンパイル済みアセットが存在すれば、最後に正常だったブロックメタデータを再利用します。安全なデータがないコールドリクエストは、別のビルドを開始する代わりに、Retry-Afterを含むHTTP503を返します。blockstudio/cache/build_wait_budgetフィルターで、構造の再構築と選択肢の更新の両方における待機時間をミリ秒単位で調整できます。アドバイザリファイルロックに対応していないホストでは、選択肢をロックなしで更新して公開するため、次のリクエストでキャッシュがヒットします。

以前のバージョンが残した、アイドル状態のキー固有の.build.lockファイルは、WP-Cronによってこのサイトのキャッシュ名前空間全体から削除されます。アップグレードの5分後に開始し、10秒の予算内で1分あたり最大10,000個のロックを削除します。wp bs cache statusは残りの数を報告し、wp bs cache cleanupは保留分を直ちに処理します。また、wp bs cache clearは実行時キャッシュを消去します。cronが動作せず、予定されたバッチが10分以上遅れた場合は、処理が滞らないよう、リクエストによって1時間に1回、上限付きでロックを走査します。最近作成されたロックや保持中のロックはそのまま残し、新しい固定パスのロックは削除しません。保留分の処理が完了すると、同じバッチが廃止されたキャッシュ名前空間をnamespaceGraceの経過後に削除します。サイトごとに最大1時間に1回実行し、そのための日次の定期実行も維持します。猶予期間は、名前空間が廃止済みと初めて判定された時点から数えます。最新ファイルの作成時点からではありません。いずれかのスコープで現在も使用中の名前空間は削除されません。 内部キャッシュのクリーンアップでは、WordPressの添付ファイル削除フィルターは呼び出されません。WP-Cronを無効にしているホストでは、通常のスケジュールcronワーカーを引き続き実行してください。保留を解消するために、稼働中のロックファイルを無差別に削除しないでください。

blockstudio/settings/cache/path設定フィルターは、設定値を変更します。デプロイ環境に応じたパス解決には、blockstudio/cache/dirで解決済みのベースディレクトリをフィルタリングします:

PHP
add_filter('blockstudio/cache/dir', function (string $directory): string {
    return WP_CONTENT_DIR . '/cache/blockstudio';
});

テナント識別情報がWordPressのネットワークIDまたはブログIDと異なるホストでは、blockstudio/cache/site_keyをフィルタリングできます。結果はサニタイズされ、ディレクトリのセグメントとしてのみ使用されます。変更をオブジェクトの識別情報に反映するシリアライズ可能な実行時バリアントには、blockstudio/cache/contextが適切です。

themeDefaults

オプション 型 デフォルト 説明
titleTag 真偽値 false WordPressのtitleタグに関するテーマサポートを有効化
suppressDirectoryUpdates 真偽値 false ディレクトリの更新結果から、有効な子テーマと親テーマを除外

パターンでは引き続き既存のBlockstudio\PatternsAPIを使用します。これらのデフォルトによって、別のページ用またはパターン用のファサードが導入されることはありません。

performance

compatプロファイルでは、汎用のWordPressの動作は変わりません。speedとstrictは同じフロントエンド用デフォルトをオプトインで有効にし、個々の子設定でプロファイルの値を上書きできます。

オプトイン設定は機能の登録を制御します。オプション機能がfalseの場合、Blockstudioはその機能のフロントエンド、管理画面、エディター、REST、定期実行のコールバックを登録しません。Early Serveまたはスケジュール済みウォーム処理を使用後に無効化すると、所有するデータは一度クリーンアップされます。それ以降のリクエストでは何も実行されません。

オプション 型 互換性優先の既定値 速度・厳密性優先の既定値 説明
profile string "compat" 該当なし compat、speed、またはstrict
wordpress.headNoise boolean false true 汎用的なheadの検出と絵文字の出力を削除
wordpress.embeds boolean false true oEmbedの検出とホストスクリプトを削除
wordpress.xmlrpc boolean false true XML-RPCとピンバックを無効化
wordpress.editor boolean false true リモートエディターの検出機能を無効化
wordpress.frontendAssets boolean false true 汎用的なコアのフロントエンドアセットを削除
wordpress.media boolean false true 画像出力の既定値を適用
wordpress.heartbeat boolean false true エディター以外でHeartbeatを制限
preload.links string "off" "intent" ユーザーの操作後に同一オリジンのドキュメントをプリフェッチ
media.lazy boolean false true Blockstudioの画像ローダーを使用
media.skeleton boolean false true 組み込みのローディングスケルトンを表示
media.metadata boolean false true assets/media.jsonの使用を宣言
media.rootMargin string "300px" "300px" 遅延ローダーの交差判定マージン
measurement.enabled boolean false false 実行時の計測APIを有効化
measurement.queryMonitor boolean false false 50ms以上かかるクエリを含める
measurement.headers boolean false false プロファイルと設定ハッシュのヘッダーを送信
measurement.timings boolean false false 経過実行時間のヘッダーを送信
staticPrerender.enabled boolean false false 匿名ユーザーにも安全なHTMLキャッシュを有効化
staticPrerender.ttl integer 86400 86400 キャッシュされたドキュメントの最大保持時間(秒)
staticPrerender.invalidate string "signature" "signature" signatureまたは増分graphの識別方式を使用
staticPrerender.earlyServe boolean false false WordPressの起動前に安全なキャッシュヒットを提供
staticPrerender.serveLoggedIn boolean false false ユーザーによるキャッシュヒットの利用を許可(作成は不可)
staticPrerender.dynamicPaths array [] [] 動的な状態を維持する必要があるパスのプレフィックス
staticPrerender.replayHeaders array ["Link"] ["Link"] キャッシュヒット時に保存・送信するレスポンスヘッダー
staticPrerender.warm.enabled boolean false false 永続的なスケジュール済みウォームキューを有効化
staticPrerender.warm.interval integer 3600 3600 ウォーム処理の間隔(秒)
staticPrerender.warm.concurrency integer 2 2 1回のウォーム処理で処理するジョブの最大数
staticPrerender.warm.transport string "http" "http" httpまたはホストが提供するinternalレンダラーを使用

明示的に有効化しない限り、静的プリレンダリングは無効のままです。 マスタースイッチが無効の場合、プリレンダリング用リクエストフックは登録されません。また、earlyServeとwarm.enabledが無効の場合、管理画面用フックやcronフックも登録されません。シグネチャモードでは、通常のリクエストに対して低コストの有効化済みIDを使用します。グラフモードは明示的なビルド向けで、ページごとのソース依存関係を記録するため、あるページを変更しても無関係なドキュメントは無効化されません。ウォーム処理、デプロイ、早期配信、安全性の詳細は静的プリレンダリングを参照してください。

測定値はプログラムから取得できます。

PHP
use Blockstudio\Performance_Measurement;

$snapshot = Performance_Measurement::snapshot();

ヘッダーが有効な場合、BlockstudioはX-Blockstudio-Performance-Profile、X-Blockstudio-Performance-Config、および必要に応じてX-Blockstudio-Performance-Timeを送信します。blockstudio/performance/measurement_enabledアクションには、解決済みのランタイム設定が渡されます。

mediaオプションは、bs_media_image()、assets/media.jsonマニフェスト、およびフロントエンドの遅延ローダーを制御します。ヘルパー、マニフェストビルダー、ローダーの動作についてはメディアを参照してください。

content

オプション 型 デフォルト 説明
enabled boolean false Content Syncの設定を有効化
id string "default" 同期されたエンティティに保存されるコンテンツセットの名前空間
path string "content" テーマ内のコンテンツファイルディレクトリ
includePageSyncManaged boolean false 本文を所有せず、Page Sync管理の投稿を含める
authors string "ignore" 作成者の処理方法(ignoreまたは既存ユーザーlogin)
postTypes array [] 許可リストに登録する投稿タイプ
meta.include array [] 同期するメタキーのGlobパターン
meta.exclude array ["_edit_lock", "_edit_last", "_wp_old_slug"] 除外するメタキーのGlobパターン
meta.references object {} 宣言されたメタ参照をIDとUIDの間で書き換え
taxonomies array [] タームと関連付け用に許可リストへ登録する登録済みタクソノミー
media string "manifest" 添付ファイル参照の動作(manifestまたはnone)

Content Syncはwp bs contentで管理され、許可リストに登録された投稿、postmeta、宣言済み参照を持ち運び可能なファイルに書き出します。ワークフローとファイル形式についてはContent Syncを参照してください。

editor

オプション 型 デフォルト 説明
formatOnSave boolean false 保存時にblock.jsonをフォーマット
assets array [] エディターで読み込む追加アセット
markup boolean false マークアップ編集を有効化

tailwind

オプション 型 デフォルト 説明
enabled boolean false Tailwind CSSのコンパイルを有効化
config string "" Tailwind v4のCSS優先設定

コンパイルの動作とCSS優先の設定形式についてはTailwind CSSを参照してください。

blockTags

オプション 型 デフォルト 説明
enabled boolean false 投稿本文とウィジェットエリアでページ単位のbs:タグレンダリングを有効化
allow array [] ブロック名パターンの許可リスト。fnmatch()ワイルドカードに対応
deny array [] ブロック名パターンの拒否リスト。allowより優先
prefixes object {} 短縮名に付ける名前空間の接頭辞。値には名前空間または順序付き配列を指定

テンプレート単位のタグレンダリングは常に有効です。これらのオプションはページ単位の置換を制御します。タグ構文と解決ルールについてはレンダリングを参照してください。

ui

オプション 型 デフォルト 説明
enabled boolean false 同梱のbsui/*UIコンポーネントとapp/*デモアプリを登録

blockEditor

オプション 型 デフォルト 説明
disableLoading boolean false エディターでのブロック読み込みを無効化
enhance boolean false Blockstudioエディターのホバーと選択用の操作機能を有効化
cssClasses array [] クラス欄の自動補完用にCSSクラスを抽出するスタイルシートURL
cssVariables array [] コード欄の自動補完用にCSS変数を抽出するスタイルシートURL

blockEditor.blocks

プロジェクト全体のブロック挿入ポリシーにはblockEditor.blocksを使用します。allowとdenyには、core/*などのブロック名やワイルドカードパターンを指定できます。

JSON
{
  "blockEditor": {
    "blocks": {
      "allow": ["core/*", "my-theme/*"],
      "deny": ["core/embed", "core/freeform"],
      "directory": false,
      "categories": {
        "rename": {
          "text": "Writing",
          "design": "Layout"
        },
        "order": ["my-theme", "text", "media"]
      },
      "legacyWidgets": {
        "hide": ["archives", "calendar"]
      }
    }
  }
}

blocks.styles.denyは、WordPressのPHPブロックスタイルレジストリを通じて登録されたスタイルの登録を解除します。

JSON
{
  "blockEditor": {
    "blocks": {
      "styles": {
        "deny": {
          "my-theme/card": ["outline"],
          "my-theme/media": ["framed"]
        }
      }
    }
  }
}

blockEditor.patterns

blockEditor.patternsを使用すると、グローバルなパターンソースを無効化し、パターンカテゴリを絞り込めます。

JSON
{
  "blockEditor": {
    "patterns": {
      "core": false,
      "remote": false,
      "theme": true,
      "blockstudio": true,
      "categories": {
        "deny": ["gallery"],
        "rename": {
          "featured": "Featured Layouts"
        },
        "order": ["featured", "buttons"]
      }
    }
  }
}

blockEditor.media

グローバルなメディア挿入ポリシーにはblockEditor.mediaを使用します。

JSON
{
  "blockEditor": {
    "media": {
      "openverse": false,
      "imageSizes": {
        "allow": ["thumbnail", "large"],
        "deny": ["medium_large"]
      }
    }
  }
}

dev

オプション 型 デフォルト 説明
grab.enabled boolean false フロントエンドの要素取得ツールを有効化
perf boolean false ページ読み込みごとにパフォーマンスプロファイラーを有効化
canvas.enabled boolean false キャンバスを有効化
canvas.adminBar boolean true キャンバス表示時にWordPress管理バーを表示

githooks

オプション 型 デフォルト 説明
commit boolean false blockstudio-githooks sync実行時に解析のみを行うpre-commitフックを生成

生成されるフックの動作と同期を維持する方法については、管理対象のコミットフックを参照してください。

phpstan

オプション 型 デフォルト 説明
preset string "base" コマンドラインでプリセットを指定しない場合の解析プリセット:base、theme、extreme-theme、またはwordpress-render
configuration string "" プリセットと併用するプロジェクトのPHPStan設定。blockstudio.jsonから解決
roots array ["."] 標準コマンドで解析するテーマのルート
excludePaths array [] 設定済みの各ルートを基準とする追加のスキャナー除外項目
maxFiles integer 10000 テーマスキャナーが調査するファイルの最大数
blockTags object {} 要素のマッピング、タグの別名、およびブロックタグルール用のscanPhp

これらの設定は標準のblockstudio-phpstanコマンドを制御します。プリセット、レイヤー、導入方法についてはPHPStanを参照してください。

ai

オプション 型 デフォルト 説明
enableContextGeneration boolean false LLMツール向けに、ブロック、設定、スキーマ、ドキュメントをまとめたコンテキストファイルを生成

ドキュメントの索引と生成されるテキスト全文についてはAI連携を参照してください。

UI コンポーネント

7.3で導入されたバンドル済みのヘッドレスUIコンポーネントを有効化して組み合わせられますBlockstudio。