Unlock 1 Year of EdgeOne + 1TB CDN: Join Our Developer Journey
Get Started Now !
edgeone.json
Besides setting up the project through the console, you can also create
edgeone.json in the project root directory. 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
Can be used to override the build command in Console - Project Settings - Build Deployment Configuration.
{"buildCommand": "next build"}
InstallCommand
Can be used to override the installation command in Console - Project Settings - Build Deployment Configuration. This configuration item allows you to customize the package manager used in the build process.
{"installCommand": "npm install"}
OutputDirectory
Can be used to override the output directory in Console - Project Settings - Build Deployment Configuration.
{"outputDirectory": "./build"}
NodeVersion
Can be used to specify the Node Version of the build environment. It is recommended to use the system pre-installed Node Versions 14.21.3, 16.20.2, 18.20.4, 20.18.0, or 22.11.0. Entering other version numbers may cause deployment to fail.
{"nodeVersion": "22.11.0"}
Redirects
Can be used to redirect a request from one URL to another. Here are several redirection examples.
This example uses a 301 permanent redirect to redirect requests from the URL of
/articles/+ ID (for example, /articles/123) to the URL of /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 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 (only effective for custom domain names):
{"redirects": [{"source": "$host","destination": "$wwwhost","statusCode": 301}]}
Note:
The quantity limit for redirects is 30.
The source and destination should not exceed 500 characters.
Rewrites
This example rewrites all requests starting with /assets/ to the /assets-new/ directory while retaining the original path part of the request.
{"rewrites": [{"source": "/assets/*","destination": "/assets-new/:splat"}]}
We can further refine the rewrite rules to specifically handle PNG image files. The following example ensures that all requests ending with .png are rewritten to a new path while preserving the file name.
{"rewrites": [{"source": "/assets/*.png","destination": "/assets-new/:splat.png"}]}
Note:
The quantity limit for rewrites is 30.
The source and destination should not exceed 500 characters.
This configuration is only applicable to static resource access.
Front-end routing rewriting for SPA (single-page application) is not supported.
The source path must start with `/`.
SPA Application Rewriting Suggestion
If URL rewriting needs to be implemented in SPA, the following schemes are recommended:
Frontend route redirection
Use the routing system built into the framework for path redirection
Define rewrite rules in the routing configuration
Headers
Can be used to customize and manage HTTP response headers to improve the performance and security of the website 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, it specifies through Cache-Control 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, especially for static resources under the /assets/ directory. This example will set a longer caching time for all files in that directory.
{"headers": [{"source": "/assets/*","headers": [{"key": "Cache-Control","value": "max-age=31536000"}]}]}
Note:
The quantity limit for headers is 30.
The key of each header is limited to 1 - 100 characters, and digits, letters and the special character '-' are allowed.
The value of each header is limited to 1-1000 characters and does not support Chinese.
Caches
It can be used to set the caching logic of resources on EdgeOne nodes. You can customize the edge caching time for different resources according to business requirements, optimize the edge caching strategy for different resources, and improve the loading speed of requested resources.
This example sets all file resources in the images directory to cache for 1 day.
"caches": [{"source": "/images/*","cacheTtl": 86400}]
We can also set caching for specific files. In this example, the sitemap.xml file is set to not cache, and all jpg files under images are set to cache for 1 hour.
"caches": [{"source": "/sitemap.xml","cacheTtl": 0},{"source": "/images/*.jpg","cacheTtl": 3600}]
Note:
cacheTtl is in seconds, decimals are not allowed and it cannot be less than 0. When set to 0, caching is disabled.
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:
Path Matching
The source supports the use of specific patterns to match the request path. The matching rules are resolved based on the requested URL.
2.Wildcard
Use an asterisk (
*) as a wildcard to match any character in the path. Note that the source can only contain one wildcard.
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:
Example Of Edgeone.Json File
This example shows how to combine multiple settings in one configuration file, but it doesn't cover all available options. Note that not every setting item in the file is 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"}]}]}