Build and route Pages projects

Benefits

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

• Seamless team collaboration: All team members share one configuration file, ensuring consistency between local development and cloud deployment.

• Convenient rollbacks: Roll back to any historical commit and reproduce its exact build environment.

Configuration priority

esa.jsonc settings take precedence over console settings:

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

  • You can adjust the build options on the project's details page. For more information, see Modify build settings in the console.

  • Console settings apply to the current and all subsequent deployments.

• If an esa.jsonc file exists in your project:

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

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

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

Configuration example

Add an esa.jsonc file to your Pages repository on GitHub. Example:

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

Default mode

When notFoundStrategy is not set in esa.jsonc:

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

ESA routes requests as follows:

1. When a request URL reaches an edge node, ESA checks for a matching static asset. If found, ESA serves the file directly. If not, proceed to step 2.

2. If an Edge Routine (ER) function script exists, ESA executes it. Otherwise, a 404 Not Found response is returned.

Single-page application

For single-page applications, set notFoundStrategy to singlePageApplication in esa.jsonc. Example:

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

ESA routes requests as follows:

1. When a request URL reaches an edge node, ESA checks for a matching static asset. If found, ESA serves the file directly. If not, proceed to step 2.

2. Check if the request is a navigation request (contains the Sec-Fetch-Mode: navigate header). If not, proceed to step 3. If so, route to /index.html and proceed to step a:

   1. If /index.html exists, respond with 200 OK and return its content. Otherwise, proceed to step 3.

3. If an ER function script exists, ESA executes it. Otherwise, a 404 Not Found response is returned.

Static site generation

For static site generation applications, set notFoundStrategy to 404Page in esa.jsonc. Example:

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

ESA routes requests as follows:

1. When a request URL reaches an edge node, ESA checks for a matching static asset. If found, ESA serves the file directly. If not, proceed to step 2.

2. Check if the request is a navigation request (contains the Sec-Fetch-Mode: navigate header). If not, proceed to step 3. If so, route to /404.html and proceed to step a:

   1. If /404.html exists, respond with 200 OK and return its content. Otherwise, proceed to step 3.

3. If an ER function script exists, ESA executes it. Otherwise, a 404 Not Found response is returned.