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 - Makers Project - Project Settings - Build and Deployment Configuration.{"buildCommand": "next build"}
installCommand
Override the installation command in
Console - Makers Project - Project Settings - Build and Deployment Configuration. This configuration item allows you to customize the package manager used in the build process.{"installCommand": "npm install"}
outputDirectory
Override the output directory in
Console - Makers Project - Project Settings - Build and Deployment Configuration.{"outputDirectory": "./build"}
nodeVersion
Specify the Node version for the build environment. It is recommended to use 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 100.
The
source and destination must not exceed 500 characters.rewrites
Rewrite all requests starting with
/assets/ to the /assets-new/ directory, while preserving the path part of the original request.{"rewrites": [{"source": "/assets/*","destination": "/assets-new/:splat"}]}
The following example only rewrites PNG files in the
/assets/ directory and retains the file names.{"rewrites": [{"source": "/assets/*.png","destination": "/assets-new/:splat.png"}]}
SPA Frontend Routing
For single-page applications that use
/index.html as the entry point, you can explicitly declare an SPA fallback with the following configuration:{"rewrites": [{"source": "/*","destination": "/index.html"}]}
Makers identifies this precise configuration as an SPA fallback: requests first attempt to match other routes in the project (including static resources and functions), and only return
/index.html when no other route is matched, then hand it over to the frontend routing for processing. This rule does not take effect as a regular rewrite rule.Note:
The maximum number of rewrites is 100.
The
source and destination must not exceed 500 characters.The source path must start with
/.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": "max-age=31536000"}]}]}
Note:
The maximum number of headers is 30.
The key of each header must be 1-100 characters long, and digits, letters, and the special symbol '-' are allowed.
The value of each header must be 1-1000 characters long. Chinese characters are not allowed.
URL Path Matching Rules
In
redirects, rewrites, and headers, the source is used to match the request URL path. The destination can reference parameters captured in the source.Type | source Example | Description |
Exact Path | /api/hello | Matches only the specified path. |
Placeholder | /articles/:id | Matches single-level path parameters, which can be referenced in destination via :id. |
Wildcard | /assets/* | * matches any content and can be referenced in destination via :splat. |
Wildcard with Suffix | /assets/*.png | Matches PNG paths under the specified directory, and the wildcard part can be referenced via :splat. |
Note:
The
* is a URL path wildcard, not a file system Glob. A source can contain at most one *.The file system Glob is used only for file path fields such as
cloudFunctions.nodejs.includeFiles.For more information on custom configuration usage, see GitHub TencentEdgeOne.
cloudFunctions
includeFiles
If your Node.js function needs to directly read files, configure the includeFiles list. The builder copies these files to the build artifacts, enabling the function to read them correctly after deployment. The path format is a relative path to the project root directory (do not start with ./ or /) and supports glob patterns.
{"cloudFunctions": {"nodejs": {"includeFiles": ["assets/**","assets2/**/*.json", // glob mode"public/font-example.ttf", // exact match"assets/**", // Include all files in 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);}
externalNodeModules
If your Node.js function has dependencies that contain native modules or static files, configure externalNodeModules. This enables the builder to correctly separate these dependencies and copy them to the build artifacts.
{"cloudFunctions": {"nodejs": {"externalNodeModules": ["svg-captcha"]}}}
maxDuration
The maximum running time limit for a single Cloud Functions execution is configurable within a range of 10 - 120 seconds. The default is 30 seconds if not configured. Different runtime environments require separate settings.
{"cloudFunctions": {"nodejs": {"maxDuration": 60},"python": {"maxDuration": 60},"go": {"maxDuration": 60}}}
mainlandRegions / overseasRegions
Specify the deployment region for Cloud Functions, overriding the function region configuration in the console. The Chinese mainland region is set by
mainlandRegions (default ap-guangzhou), and regions outside the Chinese mainland are set by overseasRegions (default ap-singapore). Only one region ID can be configured in each array. For details, see Cloud Functions multi-region deployment.{"cloudFunctions": {"mainlandRegions": ["ap-beijing"],"overseasRegions": ["ap-tokyo"]}}
schedules
Configure a scheduled task to periodically trigger the specified Makers Functions based on a cron expression.
{"schedules": [{"name": "daily-cleanup","cron": "0 2 * * *","path": "/api/cron/cleanup"}]}
Each scheduled task object supports the following fields:
Parameter | Type | Required | Default Value | Description |
name | string | Yes | - | The unique identifier name for a scheduled task. It must be unique within the same project and can be up to 128 characters long. |
cron | string | Yes | - | A standard 5-segment cron expression (minute hour day month weekday). For example, 0 10 * * * means 10:00 every day, and 0 0 1 * * means the 1st day of every month. Second-level (6-segment format) is not supported. |
path | string | Yes | - | The path to the Makers Functions to be triggered. For example, /api/cron/tick and /api/scheduled/report. |
method | enum | No | POST | The HTTP method for triggering the request. Optional values: GET, POST, PUT, DELETE, PATCH, HEAD. |
payload | object | No | - | The JSON data body sent with the request. It is meaningful only when the method is POST/PUT/PATCH, and can be used to pass task parameters. |
timezone | string | No | The local system timezone at build time | The timezone context for the cron expression. Use IANA timezone identifiers, such as Asia/Shanghai, America/New_York, and UTC. If not specified, the CLI automatically uses and writes the local system timezone during build time. |
cron Expression Quick Reference:
Minutes (0-59)Hours (0-23)Day of Month (1-31)Month (1-12)Day of Week (0-7, where both 0 and 7 represent Sunday)│ │ │ │ │* * * * *
Expression | Meaning |
0 * * * * | On the hour, every hour |
0 9 * * * | Daily at 09:00 |
0 9 * * 1-5 | Weekdays at 09:00 |
0 0 1 * * | On the 1st of each month at 00:00 |
0 0 * * 0 | Every Sunday at 00:00 |
Note:
cron has a minimum precision of one minute and a minimum interval of one day. The actual trigger time may have second-level deviations, which is normal behavior.
During each deployment, the platform automatically compares configurations. Tasks that have been removed in the new deployment are automatically stopped and deleted.
If team members are distributed across different time zones, it is recommended to explicitly specify the
timezone field to prevent the scheduled task's execution time from being affected by the build machine's local time zone.agents
It is used to configure the runtime parameters for the AI Agent and the sandbox within the project.
{"agents": {"framework": "claude-agent-sdk", // claude-agent-sdk / openai-agents-sdk / langgraph / crewai / deepagents"dir": "agents", // Optional. Defaults to "agents"."timeout": 300, // Optional. The maximum duration in seconds for a single task execution (30 ~ 3600)."sandbox": {"timeout": 300 // Optional. The maximum lifetime in seconds for a sandbox instance (300 ~ 3600).}}}
Field | Feature |
agents.framework | Determines the framework adaptation form for context.store / context.tools. Options include claude-agent-sdk / openai-agents-sdk / langgraph / crewai / deepagents. |
agents.dir | Agent source code directory, default agents/. |
agents.timeout | Maximum seconds for a single task execution, ranging from 30 to 3600, with a default of 1800s. |
agents.sandbox.timeout | Sandbox instance survival duration, ranging from 300 to 3600, with a default of 300s. |
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"}]}],"cloudFunctions": {"mainlandRegions": ["ap-guangzhou"],"nodejs": {"externalNodeModules": ["svg-captcha"],"includeFiles": ["assets/**"],"maxDuration": 60}}}
