What is kuroco_front.json?

kuroco_front.json is a required JSON file for KurocoFront that enables you to configure the redirect, basic authentication, and error page settings.

Location

When using KurocoFront, place kuroco_front.json in the root folder of the output directory (directly under the public directory) after building. The file will not be made public.

tip

when using Nuxt.js or Next.js, place the file in the directory that follows.
Nuxt2:/static
Nuxt3:/public
Next.js:/public

Available keys

The following 9 keys can be set in kuroco_front.json.

Key	Description
rewrites	URL rewrite settings
redirects	Redirect settings
redirects_by_ie	Redirect when accessed via IE
basic	Basic access authentication
ip_restrictions	IP address restrictions
ip_restricted_maintenance	IP address restrictions for the maintenance page
error_page	Error page settings
stale_while_revalidate	Period for delivering expired content from the CDN until the cache is refreshed
headers	Response header settings

caution

Keys other than the above do not cause an error and are ignored. Note that configuration keys for other hosting services or typos in key names have no effect.
A setting is also ignored when its value has an unexpected type (e.g., writing stale_while_revalidate as a JSON number).

Example code

{
    "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"
    }
}

Functions in kuroco_front.json

The following sections explain the functions in the example code above in more detail.

rewrites: URL rewrite settings

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

Expression	Description	Example
source	Describe the URL to be rewritten using regular expressions. Matching is partial, not anchored. Note that ".*" is handled as a special value.	.*
destination	Describe the rewrite path.	/index.html

When source is set to ".*", it is handled as a special value, and whether the existence of the file is checked changes accordingly.

Value of source	Handling	File existence check	Behavior
".*"	Special value	Yes	The request is rewritten only when no file matching the requested URI exists. Existing files (JS, CSS, images, and so on) are served as they are.
Other than ".*"	Regular expression	No	Any request that matches is always rewritten, whether or not the file exists.

It is the literal value ".*" that is handled as a special value. Even a regular expression that matches the same URIs, such as "^.*$", does not trigger the file existence check. Because a source other than ".*" is matched partially, add ^ and $ when the pattern should match only at the start or end of the URI.
Matching is case-insensitive.
A URI ending with / is tested with index.html appended. For example, a request for /login/ is tested as /login/index.html.

Multiple values are allowed. Execute in order from the top.

note

When you let the front end handle routing in an SPA, set source to ".*". A regular expression that excludes static files, such as "/((?!assets/).*)", is a value other than ".*", so the file existence check is not performed as shown in the table above, and existing JS and CSS files are also rewritten to destination (/index.html). See Reloading the page or accessing it directly will result in 404 Not Found. for the 404 issue in an SPA.

redirects: Redirect settings

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

Expression	Description	Example
source	Describe the URL to be redirected using regular expressions. You can define capture groups with ().	^/old_articles/([^/]+?)/
destination	Describe the redirect path. You can reference the capture groups from source with $1 and so on. If no status is specified, a 301 Moved Permanently redirect is returned. If you set a path starting in status:302:, it will generate a 302 Found redirect status code as the response. A path starting in status:404 will result in a 404 Not Found status.	/new_articles/$1/

The value .* is valid even when the file does not exist. Multiple values are allowed. Execute in order from the top.

The redirection process retains the query string. You can specify a query string for destination but not for source.

Using capture groups

Capture groups defined with () in the source regular expression can be referenced in destination with $1, $2, and so on, in order. Use this when you want to carry part of the original URL over to the redirect path.

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

With the configuration above, requests are redirected according to the accessed URL as follows.

Accessed URL	Redirect path
/old_articles/123/	/new_articles/123/
/old_articles/abc/	/new_articles/abc/

You can define multiple () groups, which correspond to $1, $2, and so on, from left to right.

redirects_by_ie: Redirect when accessed via IE

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

Expression	Description	Example
source	Describe the URL to be redirected using regular expressions.	.*
destination	Describe the redirect path.	/ie/

This type of redirect is enabled when the UserAgent contains MSIE or Trident as a string. It does not verify the existence of the file, and multiple values are allowed. Execute in order from the top.

basic: Basic access authentication

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

Join the ID and password as a set using :. For example:

• ID:user, password: pass
• ID: user2, password: pass2

caution

Be careful of password security here, as it is entered as plain text.

Multiple values are allowed.

ip_restrictions: IP address restrictions

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

Set the IP address. Subnet mask is also available in slash notation. Multiple values are allowed.

ip_restricted_maintenance: IP address restrictions for the maintenance page

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

The maintenance page is accessible to all except the specified IP addresses. Subnet mask is also available in slash notation. Multiple values are allowed.

stale_while_revalidate: Deliver expired content from the CDN

"stale_while_revalidate":"86400",

Adding stale_while_revalidate to the cache control header enables delivery of expired content on the CDN side. When this value is set to 86400, the content will be retained for one day (86400 seconds) after the CDN cache is cleared, and the the expired content will be delivered on the first access after the cache clearing.

Regenerating the cache will prevent response delays during this time. This is enabled for HTTP 200 reponses.

caution

Write the value as a string of digits ("86400"). If it is written as a JSON number (86400), it is ignored.

error_page: Error page settings

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

Expression	Description	Example
status404	Path of the response HTML to 404 errors.	/404.html
status403	Path of the response HTML to 403 errors.	/403.html
status401	Path of the response HTML to 401 errors.	/401.html
status_ip_503	Path of the response HTML to the maintenance page (not accessible to specified IP addresses).	/ip_503.html

Describe the path starting with / (an absolute path from the deploy root). Paths that do not start with / are ignored.

headers: Response header settings

"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"
      }
    }
],

Expression	Description	Example
source	Regular expression for the URIs that receive the headers. It is evaluated as a partial match. Unlike rewrites, ".*" has no special meaning here; it is simply a regular expression that matches every URI.	^/admin/.*
headers	Object of header names and values to add. Setting a value to an empty string ("") removes that header from the response.	{"X-Robots-Tag": "noindex, nofollow"}

Multiple rules are allowed.
Every matching rule is applied from top to bottom. If the same header appears in more than one matching rule, the value from the later rule wins.

Matching rules

• source is evaluated against the request URI before rewrites. Even when rewrites rewrites a request to /index.html, source must match the original URI (e.g. /about/).
• Matching is case-insensitive.
• A URI ending in / is also evaluated with index.html appended. For example, a request to /login/ is matched against both /login/ and /login/index.html.
• The headers are applied not only to normal pages but also to redirects, the 401 response of basic authentication, the 403 response of IP restrictions, the 503 maintenance page, and the 404 error page.

Default headers

KurocoFront adds the following headers to every response. You can override their values or remove them with an empty string in headers.

Header	Default value
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 is also added, but it cannot be changed or removed.

Allowed headers

Only the following headers can be set. Any other header does not cause an error but is ignored, and it cannot be removed with an empty string either.

Category	Headers
Security	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	Content-Type, Content-Disposition, Content-Language
Other	X-DNS-Prefetch-Control, Refresh

caution

• Strict-Transport-Security is added only on custom domains. On kuroco-front.app and its subdomains it is ignored, because once a browser has stored it, it cannot be revoked.
• Cache-related headers such as Cache-Control, as well as Set-Cookie, Location, and Vary, cannot be set. The CDN cache lifetime is managed by KurocoFront.

Limits and ignored settings

Anything beyond the following limits is ignored for that rule or header only. Other rules and the delivery of the site are not affected.

Item	Limit
Number of rules	50
Length of source	256 characters
Length of a header value	4096 characters
Total size of header names and values	8192 bytes (across the whole kuroco_front.json)

The following rules and headers are also ignored:

• A rule whose source or headers is missing, empty, or of the wrong type
• A rule whose source is not a valid regular expression
• A rule whose source repeats a variable-length group, such as (a+)+
• A header whose name contains characters that are not allowed in a header name
• A header whose value contains line breaks or control characters

When a setting is ignored, the response does not carry any information about it. Check the response headers with your browser's developer tools to confirm that the setting is applied.

Note

• If kuroco_front.json is not found or if the JSON format is invalid, a "404 Not Found (CONFIG FILE NOT FOUND)" message will be displayed. When the JSON format is invalid, the response also carries the header X-Kuroco-Config-Error: json-parse-error, so you can tell it apart from a missing file.
• Requests for files or directories whose names start with .env, .git, .svn or .ht (including .env.local, .gitignore, .htaccess, etc.) return "404 Not Found" even if they are included in the deployed files. This applies at any directory level and is case-insensitive. status404 in error_page is not applied to them. Other dot files such as .well-known are served as usual.
• For cases of authentication failure due to IP restrictions, a "403 Forbidden" error or the error_page content will be displayed.
• Since browsing restrictions are based on the user's Kuroco ID and password, the "Authentication required" message or the error_page content will be displayed in cases of authentication failures.
• You can use the GitHub Actions build file to modify the contents of kuroco_front.json for all the branches of the same repository (e.g., to set up basic authentication in the development environment). See: How to deploy the source from GitHub to KurocoFront for details.

Related documents

• KurocoFront
• KurocoFront Settings
• Deploying the data source from GitHub to KurocoFront
• 404 Not Found error when reloading the page or accessing the URL directly
• Can I use basic authentication?
• How to display maintenance page except for specific IP addresses?