edgeone.json
In addition to performing project settings on the console, you can also create an
edgeone.json file in the project root directory 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
Override the build command in
Console - Project Setting - Build Deployment Configuration.{"buildCommand": "next build"}
installCommand
Override the installation command in
Console - Project Setting - Build Deployment Configuration. This configuration allows customizing the package manager used in the build process.{"installCommand": "npm install"}
outputDirectory
Override the output directory in
Console - Project Setting - Build Deployment Configuration.{"outputDirectory": "./build"}
nodeVersion
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. Using other versions may cause deployment failure.
{"nodeVersion": "22.11.0"}
redirects
Redirect a request from one URL to another URL. The following is examples of redirection.
Use a 301 permanent redirect to redirect requests from the URL
/articles/+ ID (such as /articles/123) to the URL /news-articles/ + ID (such as /news-articles/123):{"redirects": [{"source": "/articles/:id","destination": "/news-articles/:id","statusCode": 301}]}
Use a 302 temporary redirect to redirect requests from
/old-path to /new-path:{"redirects": [{"source": "/old-path","destination": "/new-path","statusCode": 302}]}
Use a 301 permanent redirect to redirect requests from
/template-source to the absolute path of the 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}]}
Use a 301 permanent redirect to redirect non-www requests to www, and also support reverse redirect (only applicable to custom domain name):
{"redirects": [{"source": "$host","destination": "$wwwhost","statusCode": 301}]}
Note:
The maximum number of redirects is limited to 100.
source and destination must not exceed 500 characters
rewrites
Rewrite all requests starting with /assets/ to the /assets-new/ directory, retaining the path section of the original request.
{"rewrites": [{"source": "/assets/*","destination": "/assets-new/:splat"}]}
Further refine rewrite rules, targeting PNG image files. The following example will ensure 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:
The maximum number of rewrites is limited to 100.
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
Source path must start with `/`
SPA Application Rewriting Advice
If needed, implement URL rewriting in SPA with 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
Customize and manage HTTP response headers to improve website performance and security while enhancing user experience.
Enhance website security by setting the X-Frame-Options header for all requests to prevent clickjacking attacks. Meanwhile, specify a 2-hour cache 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"}]}]}
Further optimize the cache policy for specific resources, targeting 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 30
The key of each header must be 1-100 characters long, and can contain digits, letters, and the special symbol '-'.
The value of each header must be 1-1000 characters long. Chinese characters are not allowed.
caches
Configure edge cache time for different resources, optimize edge cache policies for different resources, and enhance the loading speed of requested resources.
Set all files in the images directory to cache for 1 day.
{"caches": [{"source": "/images/*","cacheTtl": 86400}]}
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 a decimal and cannot be less than 0. It is set to 0 for no caching.
Source Match Rule Description
When configuring redirects, rewrites, headers, and caches, 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:
node-functions
included_files: If your node function directly needs to read files, configure the included_files list. The builder will copy these files to the build artifact so the function can read them correctly after deployment. The path format is a relative path to the project root directory (do not start with ./ or /). glob mode is supported.
{"node-functions": {"included_files": ["assets/**","assets2/**/*.json", // glob mode"public/font-example.ttf", // exact match"assets/**", // Include all files in the assets directory"!assets/**/*.tmp", // Exclude all .tmp files"assets/images/**/*.{png,jpg,jpeg,gif,webp}", // image resources]}
Currently only support relative path in function code usage for importing files.
import { readFileSync } from 'fs';export function onRequest() {const image = readFileSync('../../assets/your-file.png');return new Response(image);}
external_node_modules: Some dependency packages contain native modules or static files. Configure external_node_modules to enable the builder to correctly separate these dependencies and copy them to the build artifacts.
{"node-functions": {"external_node_modules": ["svg-captcha"]}}
nodeFunctionsConfig
The maximum running time limit for Node Functions is configurable from 10 to 120 seconds, with a default of 30 seconds when not configured.
{"nodeFunctionsConfig": {"maxDuration": 10}}
edgeone.json File Example
The following example shows how to combine multiple settings in a configuration file, including but not limited to all available options. Please note that 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"}]}],"node-functions": {"external_node_modules": ["svg-captcha"],"included_files": ["assets/**",]}}
