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

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"
    ],
    "stale_while_revalidate":"86400",
    "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.	.*
destination	Describe the rewrite path.	/index.html

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

redirects: Redirect settings

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

Expression	Description	Example
source	Describe the URL to be redirected using regular expressions.	/old_path/
destination	Describe the redirect path. 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_path/

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.

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.

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

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.
• 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.