edgeone.json
In addition to configuring the project via console, you can also create the
edgeone.json file in the project root directory. This file allows you to define and override the project's default behavior, so that you can configure the project more flexibly.
The configuration file includes the following settings:
buildCommand
Can be used to override the compilation command in console - project setting - build deployment configuration.
{"buildCommand": "next build"}
installCommand
Can be used to override the installation command in Console - Project Setting - Build Deployment Configuration. This configuration item can customize the package manager used in the build process.
{"installCommand": "npm install"}
outputDirectory
Can be used to override the output directory in Console - Project Setting - Build Deployment Configuration.
{"outputDirectory": "./build"}
nodeVersion
Used to specify the node version for building the environment. It is recommended to use the system-preinstalled node versions: 14.21.3, 16.20.2, 18.20.4, 20.18.0, 22.11.0. If other version numbers are filled in, it may cause deployment failure.
{"nodeVersion": "22.11.0"}
redirects
Can be used to redirect a request from one URL to another URL. The following are some examples of redirection.
This example uses a 301 permanent redirect to redirect requests 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 redirect to redirect the 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 requests 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, while also supporting reverse redirect (only applicable to custom domain names):
{"redirects": [{"source": "$host","destination": "$wwwhost","statusCode": 301}]}
Note:
The maximum number of redirects is limited to 30.
source and destination are no more than 500 characters each
rewrites
This example rewrites all requests starting with /assets/ to the /assets-new/ directory while retaining the path section of the original request.
{"rewrites": [{"source": "/assets/*","destination": "/assets-new/:splat"}]}
We can further refine the rewrite rules to specifically process image files in PNG format. The following example will ensure all requests ending with .png are rewritten to a new path while retaining the file name.
{"rewrites": [{"source": "/assets/*.png","destination": "/assets-new/:splat.png"}]}
Note:
Note: The maximum number limit for rewrite is 30.
- source and destination must be no more than 500 characters.
This configuration is applicable only to static resource access.
- Does not support frontend route rewriting for SPA (single-page application).
The source path must start with `/`
SPA Application Rewriting Advice
If needed to implement URL rewriting in SPA, recommendation adoption of the following solution:
Frontend route redirection
Use the built-in routing system of the framework to perform path redirection
Define rewrite rules in the routing configuration
headers
Applicable 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; meanwhile, it specifies the Cache-Control header to allow responses to be cached for 2 hours, improving performance and reducing server load.
{"headers": [{"source": "/*","headers": [{"key": "X-Frame-Options","value": "DENY"},{"key": "Cache-Control","value": "max-age=7200"}]}]}
We can further optimize the cache policy for specific resources, especially static resources under the /assets/ directory. This example will set a longer cache time for all files in this directory.
{"headers": [{"source": "/assets/*","headers": [{"key": "Cache-Control","value": "s-maxage=10000, max-age=31536000"},{"key": "Pages-Cache-Control","value": "s-maxage=10000"}]}]}
Note:
Note: The maximum number limit for header is 30.
Each header's key is limited to 1 - 100 characters, allowing digits, letters, and the special symbol '-'.
Each header's value is limited to 1 - 1000 characters, Chinese characters are not allowed.
caches
Applicable to targeting different resource configurations to adjust edge cache time, optimize edge cache policies for different resources, and enhance the loading speed of requested resources.
This example sets all files in the images directory to be cached for 1 day.
"caches": [{"source": "/images/*","cacheTtl": 86400}]
We can also set cache for specific files. This example sets the sitemap.xml file to not be cached, and sets all jpg files under the images folder to be cached for 1 hour.
"caches": [{"source": "/sitemap.xml","cacheTtl": 0},{"source": "/images/*.jpg","cacheTtl": 3600}]
Note:
cacheTtl is in seconds, does not allow decimals and cannot be less than 0, set to 0 means no caching
Source Match Rule Description
When configuring redirects, rewrites, and headers, the source field is used to define the match rule for the request path. The following are the main matching features:
1.Path matching
source supports using specific patterns to match request paths. The match rule will be parsed according to the request's URL.
2.Wildcard
Use an asterisk (
*) as a wildcard to match any character in a path. Please note that source can only contain one wildcard.
3.Placeholder
Placeholder starts with a colon (
:) followed by the placeholder name. Each placeholder can only be used once in source and will match all characters except separators.
Note:
Edgeone.Json File Example
This example shows how to combine multiple settings in one configuration file, but it does not cover all available options. Please note that each setting item in the file is not required.
{"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"}]}]}