kuroco_front.jsonとは何ですか？

Q: kuroco_front.jsonとは何ですか？

kuroco_front.jsonとは、KurocoFrontoを利用するために必要なJSONファイルです。Kuroco_front.jsonを利用することで、リダイレクト設定やBasic認証設定、エラーページの設定が可能となります。

kuroco_front.jsonとは、KurocoFrontを利用するために必要なJSONファイルです。
Kuroco_front.jsonを利用することで、リダイレクト設定やBasic認証設定、エラーページの設定が可能となります。

配置場所

KurocoFrontを利用する際は、ビルド後の出力ディレクトリのルート(公開ディレクトリの直下)にkuroco_front.jsonを配置してください。ただし、このファイルは公開されません。

ヒント

例えば、Nuxt.jsやNext.jsの場合は以下のディレクトリに配置します。
Nuxt2:/static
Nuxt3:/public
Next.js:/public

設定できるキー一覧

kuroco_front.jsonで設定できるキーは以下の9個です。

キー	説明
`rewrites`	URLリライトの設定
`redirects`	リダイレクトの設定
`redirects_by_ie`	IEでのアクセス時にリダイレクト
`basic`	Basic認証
`ip_restrictions`	IPアドレス制限
`ip_restricted_maintenance`	IPアドレス制限付きメンテナンスページ
`error_page`	エラーページの設定
`stale_while_revalidate`	キャッシュが更新されるまでCDNから期限切れのコンテンツを配信する期限
`headers`	レスポンスヘッダーの設定

注意

上記以外のキーを記述してもエラーにはならず、無視されます。他のホスティングサービスの設定キーやキー名のタイポは動作しないため注意してください。
また、値の型が想定と異なる場合（例：stale_while_revalidateをJSONの数値で記述した場合）も、その設定は無視されます。

サンプルコード

{
    "rewrites": [
        {
          "source": ".*",
          "destination": "/index.html"
        }
    ],
    "redirects": [
        {
          "source": "^/old_path/",
          "destination": "/new_path/"
        },
        {
          "source": "^/old_articles/([^/]+?)/",
          "destination": "/new_articles/$1/"
        },
        {
          "source": "^/old_articles2/([^/]+?)/",
          "destination": "status:404"
        },
        {
          "source": "^/articles2/([^/]+?)/",
          "destination": "status:302:/temp_articles2/$1/"
        }
    ],
    "redirects_by_ie": [
        {
          "source": ".*",
          "destination": "/ie/"
        }
    ],
    "basic":[
        "user:pass",
        "user2:pass2"
    ],
    "ip_restrictions":[
        "111.111.111.111/32",
        "222.222.222.222/32"
    ],
    "ip_restricted_maintenance":[
        "111.111.111.111/32",
        "222.222.222.222/32"
    ],
    "stale_while_revalidate":"86400",
    "headers": [
        {
          "source": ".*",
          "headers": {
            "Content-Security-Policy": "default-src 'self'; img-src 'self' data:",
            "Strict-Transport-Security": "max-age=31536000"
          }
        },
        {
          "source": "^/admin/.*",
          "headers": {
            "X-Robots-Tag": "noindex, nofollow"
          }
        }
    ],
    "error_page": {
        "status404":"/404.html",
        "status401":"/401.html",
        "status_ip_503":"/ip_503.html"
    }
}

kuroco_front.jsonの役割

上記サンプルコードの役割を詳しく解説します。

rewrites：URLリライトの設定

"rewrites": [
        {
          "source": ".*",
          "destination": "/index.html"
        }
    ],

項目	説明	設定例
source	URLリライト対象URIを正規表現で記述します。部分一致で判定します。ただし`".*"`は特殊な指定として扱われます。	.*
destination	リライト先を記述します。	/index.html

sourceに".*"を指定した場合は特殊な指定として扱われ、ファイルの存在確認の有無が変わります。

`source`の指定	扱い	ファイルの存在確認	動作
`".*"`	特殊な指定	あり	リクエストされたURIに対応するファイルが存在しない場合のみリライトします。存在するファイル（JS・CSS・画像など）はそのまま配信します。
`".*"`以外	正規表現	なし	ファイルの有無に関わらず、マッチしたリクエストを常にリライトします。

特殊な指定として扱われるのは".*"という記述そのものです。"^.*$"のように結果として同じURIにマッチする正規表現を書いても、ファイルの存在確認は行われません。 ".*"以外のsourceは部分一致で判定するため、URIの先頭や末尾に限定する場合は^・$を付けてください。
判定では大文字と小文字を区別しません。
末尾が/のURIはindex.htmlを補ったパスに対して判定します。たとえば/login/へのリクエストは/login/index.htmlとして判定されます。

複数設定可能です。
上から順番にチェックをします。

注記

SPAでルーティングをフロントエンド側に任せる場合は、sourceに".*"を指定します。
"/((?!assets/).*)"のように静的ファイルを除外する正規表現を指定すると".*"以外の指定となり、上表のとおりファイルの存在確認が行われないため、実在するJSやCSSもdestination（/index.html）にリライトされます。
SPAの404についてはページをリロードしたり、URLに直接アクセスすると 404 Not Found になります。を参照ください。

redirects：リダイレクトの設定

"redirects": [
        {
          "source": "/old_path/",
          "destination": "/new_path/"
        }
    ],

項目	説明	設定例
source	リダイレクト対象URIを正規表現で記述します。`()`でキャプチャグループを指定できます。	^/old_articles/([^/]+?)/
destination	リダイレクト先を記述します。`$1`などでsourceのキャプチャグループを参照できます。何も指定しない場合は301リダイレクトになります。status:302:を先頭にセットすると302リダイレクトになります。status:404をセットすると404エラーになる特別な挙動が設定可能です。	/new_articles/$1/

".*"の時のみ、ファイルの存在がしない時のみ動作する挙動になります。
複数設定可能です。
上から順番にチェックをします。
リダイレクト時はQueryStringを保持してリダイレクトします。destinationにもQueryStringは指定できますが、sourceの指定にQueryStringは利用できません。

キャプチャグループの利用

sourceの正規表現に()で指定したキャプチャグループは、destinationで$1、$2…の順に参照できます。リダイレクト元URLの一部をリダイレクト先に引き継ぎたい場合に利用します。

"redirects": [
    {
        "source": "^/old_articles/([^/]+?)/",
        "destination": "/new_articles/$1/"
    }
],

上記の場合、アクセスされたURLに応じて次のようにリダイレクトされます。

アクセスされたURL	リダイレクト先
/old_articles/123/	/new_articles/123/
/old_articles/abc/	/new_articles/abc/

()は複数指定でき、左から順に$1、$2…に対応します。

redirects_by_ie：IEでのアクセス時にリダイレクト

"redirects_by_ie": [
    {
        "source": ".*",
        "destination": "/ie/"
    }
],

項目	説明	設定例
source	リダイレクト対象URIを正規表現で記述します。	.*
destination	リダイレクト先を記述します。	/ie/

UserAgentにMSIEかTridentが文字列として含まれている場合のみ有効になるリダイレクトです。ファイルの存在確認はしません。
複数設定可能です。上から順番にチェックをします。

basic：Basic認証

"basic":[
    "user:pass",
    "user2:pass2"
],

IDとパスワードのセットを:で結合してセットします。
（上記の場合、「ID：user、パスワード：pass」または「ID：user2、パスワード：pass2」となります。）

注意

プレーンにパスワードを記述しますので、扱いに気をつけてください。

複数設定可能です。

ip_restrictions：IPアドレス制限

"ip_restrictions":[
     "111.111.111.111/32",
     "222.222.222.222/32"
],

IPアドレスをセットします。スラッシュ表記でサブネットマスクも利用可能です。
複数設定可能です。

ip_restricted_maintenance：IPアドレス制限付きメンテナンスページ

"ip_restricted_maintenance":[
     "111.111.111.111/32",
     "222.222.222.222/32"
],

特定のIPアドレス以外はメンテナンスページを表示します。
IPアドレスをセットします。スラッシュ表記でサブネットマスクも利用可能です。
複数設定可能です。

stale_while_revalidate：キャッシュが更新されるまでCDNから期限切れのコンテンツを配信する期限

"stale_while_revalidate":"86400",

Cache-Controlヘッダーにstale_while_revalidateを追加して、CDN側で失効済みコンテンツ配信を可能にします。
stale_while_revalidateに86400をセットすると、CDNのキャッシュがクリアされてもコンテンツを1日間（86400秒）保持し、キャッシュクリア後1回目のアクセスでは失効済みコンテンツを配信します。
この間にキャッシュの再作成することでキャッシュがない時のレスポンス遅延を防ぎます。
HTTPレスポンスが200の時だけ有効になります。

注意

値は数字の文字列（"86400"）で記述します。JSONの数値（86400）で記述した場合は無視されます。

error_page：エラーページの設定

"error_page": {
    "status404":"/404.html",
    "status401":"/401.html",
    "status_ip_503":"/ip_503.html"
},

項目	説明	設定例
status404	404エラー時にレスポンスするHTMLファイルのパスを記述します。	/404.html
status403	403エラー時にレスポンスするHTMLファイルのパスを記述します。	/403.html
status401	401エラー時にレスポンスするHTMLファイルのパスを記述します。	/401.html
status_ip_503	IPアドレス付きメンテナンスページ表示時にレスポンスするHTMLファイルのパスを記述します。	/ip_503.html

パスは/始まり（デプロイルートからの絶対パス）で記述します。/始まりでないパスは無視されます。

headers：レスポンスヘッダーの設定

"headers": [
    {
      "source": ".*",
      "headers": {
        "Content-Security-Policy": "default-src 'self'; img-src 'self' data:",
        "Strict-Transport-Security": "max-age=31536000"
      }
    },
    {
      "source": "^/admin/.*",
      "headers": {
        "X-Robots-Tag": "noindex, nofollow"
      }
    }
],

項目	説明	設定例
source	ヘッダーを付与する対象URIを正規表現で記述します。部分一致で判定します。`rewrites`と異なり、`".*"`に特別な扱いはなく、すべてのURIにマッチする正規表現として動作します。	^/admin/.*
headers	付与するヘッダー名と値の組をオブジェクトで記述します。値に空文字（`""`）を指定すると、そのヘッダーをレスポンスから削除します。	`{"X-Robots-Tag": "noindex, nofollow"}`

複数設定可能です。
マッチしたルールはすべて上から順番に適用します。同じヘッダーが複数のルールにある場合は、後のルールの値で上書きします。

判定のルール

sourceはリライト前のリクエストURIに対して判定します。rewritesで/index.htmlにリライトされるリクエストでも、sourceには元のURI（例：/about/）がマッチする必要があります。
判定では大文字と小文字を区別しません。
末尾が/のURIはindex.htmlを補ったパスに対しても判定します。たとえば/login/へのリクエストは/login/と/login/index.htmlのどちらかにマッチすれば適用されます。
通常のページだけでなく、リダイレクト、Basic認証の401、IPアドレス制限の403、メンテナンスページの503、404エラーページのレスポンスにも適用します。

デフォルトで付与されるヘッダー

KurocoFrontはすべてのレスポンスに次のヘッダーを付与しています。headersで値を上書きしたり、空文字を指定して削除したりできます。

ヘッダー	デフォルト値
Content-Security-Policy	upgrade-insecure-requests
X-Frame-Options	sameorigin
X-XSS-Protection	1; mode=block
X-Permitted-Cross-Domain-Policies	master-only

X-Content-Type-Options: nosniffも付与していますが、こちらは変更・削除できません。

設定できるヘッダー

設定できるのは次のヘッダーのみです。それ以外のヘッダーは記述してもエラーにならず無視され、空文字を指定しても削除できません。

分類	ヘッダー
セキュリティ	Content-Security-Policy、Content-Security-Policy-Report-Only、Strict-Transport-Security、X-Frame-Options、Referrer-Policy、Permissions-Policy、Cross-Origin-Opener-Policy、Cross-Origin-Embedder-Policy、Cross-Origin-Resource-Policy、X-XSS-Protection、X-Permitted-Cross-Domain-Policies、Reporting-Endpoints
CORS	Access-Control-Allow-Origin、Access-Control-Expose-Headers、Access-Control-Allow-Credentials、Timing-Allow-Origin
SEO	X-Robots-Tag、Link
コンテンツ	Content-Type、Content-Disposition、Content-Language
その他	X-DNS-Prefetch-Control、Refresh

注意

Strict-Transport-Securityは独自ドメインでのみ付与します。kuroco-front.appおよびそのサブドメインでは、記述しても無視します。一度ブラウザに記憶されると取り消せないためです。
Cache-Controlなどキャッシュに関するヘッダー、Set-Cookie、Location、Varyは設定できません。CDNのキャッシュ期間はKurocoFront側で管理します。

上限と無視される設定

次の上限を超えた分は、該当するルールまたはヘッダーのみが無視されます。他のルールやサイトの配信には影響しません。

項目	上限
ルール数	50件
`source`の長さ	256文字
ヘッダー値の長さ	4096文字
ヘッダー名と値の合計サイズ	8192バイト（kuroco_front.json全体）

また、次のルールやヘッダーも無視されます。

sourceまたはheadersがない、空である、または型が異なるルール
sourceが正規表現として不正なルール
(a+)+のように、可変長のグループを繰り返す正規表現をsourceに指定したルール
ヘッダー名に使用できない文字を含むもの
値に改行や制御文字を含むもの

無視された設定があっても、レスポンスにはその情報は含まれません。設定が反映されているかは、ブラウザの開発者ツールなどでレスポンスヘッダーを確認してください。

補足

kuroco_front.jsonが見つからない、JSON形式が間違っていると「404 Not Found (CONFIG FILE NOT FOUND)」になります。JSON形式が間違っている場合は、レスポンスヘッダーにX-Kuroco-Config-Error: json-parse-errorが付くため、ファイルが見つからない場合と区別できます。
.env、.git、.svn、.ht で始まるファイルやディレクトリ（.env.local、.gitignore、.htaccess なども含む）へのアクセスは、デプロイしたファイルに含まれていても「404 Not Found」になります。どの階層にあっても対象で、大文字・小文字は区別しません。error_pageのstatus404は適用されません。.well-known など、これら以外のドットで始まるファイルは通常どおり配信されます。
IPアドレス制限での認証に失敗すると、「403 Forbidden」、またはerror_pageでセットした内容となります。
閲覧制限はKurocoのID・PWDでの認証になるため、認証に失敗すると、「Authentication required」、またはerror_pageでセットした内容となります。
同一リポジトリ内でブランチ毎にkuroco_front.jsonの内容を切り替えたい場合はGitHubActionsのビルドファイルで切り替えることが出来ます。
具体的な運用ケースとしては開発環境のみBasic認証を設定したい場合に利用出来ます。

実際の設定例はGitHubからKurocoFrontへソースをデプロイする方法を参照してください。

サポート

お探しのページは見つかりましたか？解決しない場合は、問い合わせフォームからお問い合わせいただくか、Slackコミュニティにご参加ください。

フォームから問い合わせをする

Slackコミュニティに参加する

配置場所​

設定できるキー一覧​

サンプルコード​

kuroco_front.jsonの役割​

rewrites：URLリライトの設定​

redirects：リダイレクトの設定​

キャプチャグループの利用​

redirects_by_ie：IEでのアクセス時にリダイレクト​

basic：Basic認証​

ip_restrictions：IPアドレス制限​

ip_restricted_maintenance：IPアドレス制限付きメンテナンスページ​

stale_while_revalidate：キャッシュが更新されるまでCDNから期限切れのコンテンツを配信する期限​

error_page：エラーページの設定​

headers：レスポンスヘッダーの設定​

判定のルール​

デフォルトで付与されるヘッダー​

設定できるヘッダー​

上限と無視される設定​

補足​

関連ドキュメント​