Edge Developer Platform
  • Pages
    • Product Introduction
    • Quick Start
    • Framework Guide
    • Project Guide
      • Project Management
      • edgeone.json
      • Error Codes
    • Build Guide
    • Deployment Guide
    • Domain Management
    • Pages Functions
    • KV Storage
    • EdgeOne CLI
    • FAQs
    • Contact Us
    • Release Notes
    • Migration Guides
      • Migrating from Vercel to EdgeOne Pages
      • Migrating from Cloudflare Pages to EdgeOne Pages
      • Migrating from Netlify to EdgeOne Pages
Docs Overview/
Edge Developer Platform/
Pages/
Project Guide/
edgeone.json/

edgeone.json

In addition to configuring project settings through the console, you can create an edgeone.json file in the root directory of the project. This file allows you to define and override the default behavior of the project for more flexible configuration.

The configuration file includes the following settings:

buildCommand

It can be used to override the build command in the Console - Project Settings - Build Deployment Configuration.
{
    "buildCommand": "next build"
}


installCommand

It can be used to override the install command in the Console - Project Settings - Build Deployment Configuration. This configuration item can customize the Package Manager used during the build process.
{
    "installCommand": "npm install"
}


outputDirectory

It can be used to override the output directory in the Console - Project Settings - Build Deployment Configuration.
{
    "outputDirectory": "./build"
}


nodeVersion

Node versions that can be specified for the build environment. It is recommended to use the system-preinstalled versions 14.21.3, 16.20.2, 18.20.4, 20.18.0, and 22.11.0. Using other version numbers may lead to deployment failure.
{
    "nodeVersion": "22.11.0"
}


redirects

Can be used to redirect a request from one URL to another. Here are some examples of redirection.

This example uses a 301 permanent redirection to redirect a request from the URL /articles/+ ID (e.g., /articles/123) to the URL /news-articles/+ ID (e.g., /news-articles/123):
{
    "redirects": [
      {
        "source": "/articles/:id",
        "destination": "/news-articles/:id",
        "statusCode": 301
      }
    ]
}

This example uses a 302 temporary redirection to redirect a request from /old-path to /new-path:
{
    "redirects": [
      {
        "source": "/old-path",
        "destination": "/new-path",
        "statusCode": 302
      }
    ]
}

This example uses a 301 permanent redirect to redirect a request from /template-source to the absolute path of an external site https://github.com/TencentEdgeOne/pages-templates/tree/main/examples/chrome-ai:
{
    "redirects": [
      {
        "source": "/template-source",
        "destination": "https://github.com/TencentEdgeOne/pages-templates/tree/main/examples/chrome-ai",
        "statusCode": 301
      }
    ]
}

This example uses a 301 permanent redirect to redirect non-www requests to www, and also supports reverse redirect:
{
    "redirects": [
      {
        "source": "$host",
        "destination": "$wwwhost",
        "statusCode": 301
      }
    ]
}
Notes:
The maximum number of redirects is limited to 30
The source and destination must not exceed 500 characters


rewrites

This example rewrites all requests starting with /assets/ to the /assets-new/ directory, while retaining the original request's path portion.
{
    "rewrites": [
      {
        "source": "/assets/*",
        "destination": "/assets-new/:splat"
      }
    ]
}

We can further refine the rewriting rules specifically for PNG image files. The following example ensures that all requests ending with .png are rewritten to a new path while retaining the filename.
{
    "rewrites": [
      {
        "source": "/assets/*.png",
        "destination": "/assets-new/:splat.png"
      }
    ]
}

Notes:
The maximum number of rewrites is limited to 30
The source and destination must not exceed 500 characters
This configuration is only applicable to static resource access
Does not support frontend routing rewrite for SPA (Single Page Application)
The source path must start with `/`

SPA Application Rewriting Suggestions
If you need to implement URL rewriting in SPA, it is recommended to use the following solutions:
Frontend Routing Redirect
Use the routing system provided by the framework for path redirection
Define rewriting rules in the routing configuration


headers

Can be used to customize and manage HTTP response headers to improve website performance and security, while enhancing user experience.

This example enhances website security by setting the X-Frame-Options header for all requests to prevent clickjacking attacks; at the same time, Cache-Control specifies that the response can be cached for 2 hours to improve performance and reduce server load.
{
    "headers": [
      {
        "source": "/*",
        "headers": [
          {
            "key": "X-Frame-Options",
            "value": "DENY"
          },
          {
            "key": "Cache-Control",
            "value": "max-age=7200"
          }
        ]
      }
    ]
}

We can further optimize the caching strategy for specific resources, particularly for static resources under the /assets/ directory. This example sets a longer caching time for all files in that directory.
{
    "headers": [
      {
        "source": "/assets/*",
        "headers": [
          {
            "key": "Cache-Control",
            "value": "max-age=31536000"
          }
        ]
      }
    ]
}

Notes:
The maximum number of headers is limited to 30
The key for each header is limited to 1-100 characters, allowing numbers, letters, and special symbols '-'
The value for each header is limited to 1-1000 characters, Chinese is not supported


Source match rules description

When configuring redirects, rewrites, and headers, the source field is used to define the request path matching rules. Below are the main matching features:

1.Path matching
The source supports using specific patterns to match the request path. The matching rules are parsed according to the request URL.

2.Wildcard
Using an asterisk (*) as a database table name can match any characters in the path. Note that only one database table name can be included in the source.

3.Placeholder
Placeholders start with a colon (:) followed by the placeholder name. Each placeholder can only be used once in the source and will match all characters except separators.

Notes:
To learn more about custom configuration usage, see Glthub TencentEdgeOne.


edgeone.json file example

This example demonstrates how to combine multiple settings into a single configuration file, but it does not cover all available options. Please note, not every setting in the file is mandatory.
{
  "name": "example-app",
  "buildCommand": "next build",
  "installCommand": "npm install",
  "outputDirectory": "./build",
  "nodeVersion": "22.11.0",
 
  "redirects": [
    {
      "source": "/articles/:id",
      "destination": "/news-articles/:id",
      "statusCode": 301
    },
    {
      "source": "/old-path",
      "destination": "/new-path",
      "statusCode": 302
    }
  ],
  "rewrites": [
    {
      "source": "/assets/*",
      "destination": "/assets-new/:splat"
    }
  ],
  "headers": [
    {
      "source": "/*",
      "headers": [
        {
          "key": "X-Frame-Options",
          "value": "DENY"
        },
        {
          "key": "Cache-Control",
          "value": "max-age=7200"
        }
      ]
    },
    {
      "source": "/assets/*",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "max-age=31536000"
        }
      ]
    }
  ]
}