edgeone.json
In addition to project setting via console, you can also create the
edgeone.json file in the project root directory. This file allows you to define and override the default behavior of the project so that you can configure the project more flexibly.
The configuration file includes the following settings:
buildCommand
Can be used to override the build command in console - project setting - build deployment configuration.
{"buildCommand": "next build"}
installCommand
Applicable 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 the build environment. Recommend using the pre-installed versions 14.21.3, 16.20.2, 18.20.4, 20.18.0, or 22.11.0. Filling in other versions may cause deployment failure.
{"nodeVersion": "22.11.0"}
redirects
Can be used to redirect a request from one URL to another. The following is examples of redirection.
This example uses a 301 permanent redirect to route requests from the URL
/articles/+ ID (such as /articles/123) to the URL /news-articles/ + ID (for example, /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 route non-www requests to www, and also supports reverse redirect (only applicable to custom domain names):
{"redirects": [{"source": "$host","destination": "$wwwhost","statusCode": 301}]}
Note:
Maximum number of redirects is limited to 30
source and destination must not exceed 500 characters
rewrites
This example rewrites all requests beginning with /assets/ to under the directory /assets-new/, retaining the path section of the original request simultaneously.
{"rewrites": [{"source": "/assets/*","destination": "/assets-new/:splat"}]}
We can further refine rewrite rules, specialized for PNG image files. The following example ensures ALL requests ending with .png are rewritten to the new path while retaining the filename.
{"rewrites": [{"source": "/assets/*.png","destination": "/assets-new/:splat.png"}]}
Note:
Maximum number of rewrites is limited to 30
source and destination must not exceed 500 characters
This configuration is applicable only to static resource access
- Frontend route rewriting is not supported for SPAs (single-page applications)
Source path must start with `/`
SPA application rewriting advice
Note: If needed, implement URL rewriting in SPA with the following solution:
Warning: 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 a 2-hour cache duration for responses via Cache-Control to improve performance and reduce server burden.
{"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:
Maximum number of headers is limited to 30
The key of each header is limited to 1-100 characters, and numbers, letters, and special symbols '-' are allowed.
The value of each header is limited to 1-1000 characters. Chinese characters are not allowed.
caches
Applicable to different resources to configure edge cache time, optimize edge cache policy, and enhance loading speed of requested resources.
This example sets all files in the images directory to caching for 1 day.
"caches": [{"source": "/images/*","cacheTtl": 86400}]
We can also set cache for specific files. This example sets the sitemap.xml file to no-cache and all jpg files under images to cache for 1 hr.
"caches": [{"source": "/sitemap.xml","cacheTtl": 0},{"source": "/images/*.jpg","cacheTtl": 3600}]
Note:
cacheTtl is in seconds, cannot be less than 0 and does not allow decimals. Set to 0 for no-cache.
Source Match Rule Description
When configuring redirects, rewrites and headers, the source field is for defining the request path match rule. The following is the main matching feature:
1.Path matching
The source field supports the use of specific modes to match request paths. The match rule parses based on the request URL.
2.Wildcards
Use an asterisk (
*) as a wildcard to match any character in the path. Please note, the source can only contain one wildcard.
3.Placeholder
A placeholder starts with a colon (
:) followed by the placeholder name. Each placeholder can only be used once in the source and will match all characters except the separator.
Note:
Edgeone.Json File Example
This example shows how to combine multiple settings in a configuration file, but does not include all available options. Please note, each setting item in the file is optional.
{"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"}]}]}