Edge Security Acceleration:Pages building and routing

Why use it

• Infrastructure as code: Your configuration is version-controlled with your code, making every change traceable.

• Easy team collaboration: All team members share the same configuration file, ensuring consistency between local development and cloud Deployments.

• Convenient rollbacks: You can roll back to any commit, precisely reproducing its build environment.

Configuration priority

Settings in the esa.jsonc file take precedence over settings in the console:

• If your project does not have an esa.jsonc file:

  • Adjust build options on the project's details page in the console. See Modify basic configuration in the console.

  • The console configuration is used for the current and subsequent deployments.

• If your project has an esa.jsonc file:

  • The system automatically detects the file and uses it as the sole configuration source.

  • To modify the configuration, edit the esa.jsonc file and push the changes to your GitHub repository.

  • On the project's details page in the console, any settings managed by esa.jsonc are ignored.

Configuration example

Add an esa.jsonc file to your Pages repository in GitHub. Here is an example configuration:

{
  "name": "vite-react-template",
  "entry": "./src/index.js",
  "installCommand": "npm install",
  "buildCommand": "npm run build",
  "assets": {
    "directory": "./dist",
    "notFoundStrategy": "singlePageApplication"
  }
}

Default

If notFoundStrategy is not configured in esa.jsonc, such as:

{
  "name": "vite-react-template",
  "entry": "./src/index.js",
  "assets": {
    "directory": "./dist"
  }
}

ESA routes requests according to the following flow:

1. When a request reaches a point of presence (POP), the system checks for a matching static asset. If it does, the asset is served. If not, the process continues to step 2.

2. The system checks if an edge function script exists. If it does, the script is executed. If not, it returns a 404 Not Found response.

Single-page application

When you build a single-page application, set notFoundStrategy to singlePageApplication in esa.jsonc, for example:

{
  "name": "vite-react-template",
  "entry": "./src/index.js",
  "assets": {
    "directory": "./dist",
    "notFoundStrategy": "singlePageApplication"
  }
}

ESA routes requests according to the following flow:

1. When a client request URL reaches a POP, the system checks for a corresponding static asset. If a match is found, the static file is returned. If a match is not found, the process continues to step 2.

2. The system checks if the request is a navigation request (containing the Sec-Fetch-Mode: navigate Request Header). If not, the process continues to step 3. If it is, the request is routed to the /index.html file, and the process continues to step a:

   a. The system checks if an index.html page exists. If it does, it returns the content of /index.html with a 200 OK status. If not, the process continues to step 3.

3. The system checks if a function script exists. If it does, the script is executed. If not, it returns a 404 Not Found response.

Build a static site

When you build a static site, set notFoundStrategy to 404Page in esa.jsonc, for example:

{
  "name": "vite-react-template",
  "entry": "./src/index.js",
  "assets": {
    "directory": "./dist",
    "notFoundStrategy": "404Page"
  }
}

ESA routes requests according to the following flow:

1. When a client request URL reaches an edge node, the system checks for a corresponding static asset. If a match is found, the static file is returned directly. If a match is not found, the process continues to step 2.

2. The system checks if the request is a navigation request (containing the Sec-Fetch-Mode: navigate Request Header). If not, the process continues to step 3. If it is, the request is routed to the /index.html file, and the process continues to step a:

   a. The system checks if an index.html page exists. If it does, it returns the content of /index.html with a 200 OK status. If not, the process continues to step 3.

3. The system checks if a function script exists. If it does, the script is executed. If not, it returns a 404 Not Found response.