The
edgio.config.js
config file in your app’s root directory contains configuration properties (referred to by their key) that control how your app runs on Edgio. This file is automatically created when you run edgio init
. It should export an object with the following properties:name
The
name
key is the name your property will be deployed under. If this is omitted, the name
key in your package.json
will be used.team
The
team
key is the name of the organization your property will be deployed under. If this is omitted, the deployment will be created under your personal (Private Space) organization.routes
The
routes
key is the path to your routes file relative to the root of your project. Defaults to routes.js
.origins
Origins are the backends that Edgio will proxy requests to, and define how Edgio will communicate with your web server(s). Origins defined here will be available across all environments and can be overridden on a per-environment basis.
The
origins
key is an array of objects whose properties are:Property | Type | Description |
---|---|---|
name | string | (Required) The origin name referred within the router. |
override_host_header | string | The host header sent from the browser when connecting to the origin. This is useful when you want to connect to a backend that is configured to serve content from a different domain than the one that the browser is connecting to. For example, if you want to connect to a backend that is configured to serve content from example.com but the browser is connecting to www.example.com , you can set override_host_header to example.com to ensure that the backend receives the correct host header. |
hosts | Array<Object> | An array of objects that define how Edgio will proxy requests for this origin configuration. |
hosts[].location | string | Array<string> | Array<{ hostname: string; port?: number; }> | Contains properties that define the location to which Edgio will proxy requests for this origin configuration. |
hosts[].location[].hostname | string | (Required) The domain name or IP address of the origin server. |
hosts[].location[].port | number | The port on which the backend receives https requests. Defaults to 443 but you can specify any other acceptable port value. Note that specifying 80 has no special meaning as Edgio will never send secured requests to unsecured backends. To enable HTTP traffic on a backend you must have a route matching http protocol in your router and serve content from that route. All HTTP traffic assumes port 80 on the backend. |
hosts[].scheme | string | The scheme to use when connecting to the origin. Possible values are https , http , and match . Defaults to match , using the same scheme as the incoming request. Required when hosts[].location[].port is defined. |
shields | Object | Defines how Edgio will shield your origin configuration. |
shields.apac | string | The POP code for the Asia Pacific shield. |
shields.emea | string | The POP code for the Europe, Middle East, and Africa shield. |
shields.us_west | string | The POP code for the US West shield. |
shields.us_east | string | The POP code for the US East shield. |
tls_verify | Object | An object that specifies how Edgio should verify the TLS certificate presented by the origin. |
tls_verify.use_sni | boolean | Whether to use SNI when connecting to the origin. Defaults to false . |
tls_verify.sni_hint_and_strict_san_check | string | SNI hint and enforce origin SAN/CN checking. |
tls_verify.allow_self_signed_certs | boolean | Whether to allow self-signed certificates. Defaults to false . |
tls_verify.pinned_certs | Array<string> | An array of SHA256 hashes of pinned certificates. |
Sample Configuration
JavaScript
1/* ... */2origins: [3 {4 // The name of the backend origin5 name: 'origin',67 // Use the following to override the host header sent from the browser when connecting to the origin8 override_host_header: 'test-origin.edgio.net',910 // The list of origin hosts to which to connect11 hosts: [12 {13 // The domain name or IP address of the origin server14 location: 'test-origin.edgio.net',15 },16 ],1718 tls_verify: {19 use_sni: true,20 sni_hint_and_strict_san_check: 'test-origin.edgio.net',21 },2223 // Uncomment the following to configure a shield24 // shields: { us_east: 'DCD' },25 },26],27/* ... */
environments
This configuration allows you to define different deployment environments, hostnames, and override origin configurations on a per-environment basis.
The
environments
key is an object whose properties define the name of the environment and whose values are objects with the following properties:Property | Type | Description |
---|---|---|
<ENV_NAME> | String | (Required) The name of the environment. |
<ENV_NAME>.hostnames | Object[] | A list of hostnames specific to the environment. |
<ENV_NAME>.hostnames[].hostname | String | (Required) The hostname for the environment. |
<ENV_NAME>.hostnames[].default_origin_name | String | Optional default origin this hostname should use |
<ENV_NAME>.hostnames[].tls | Object | Optional TLS configuration |
<ENV_NAME>.origins | Object[] | A list of origin configurations that override those defined within the origins property. An origin configuration defined within this property is ignored when a corresponding one is not found at the root. |
Sample Configuration
JavaScript
1/* ... */23// Global origins configuration4origins: [5 {6 // The name of the backend origin7 name: 'web',89 // Use the following to override the host header sent from the browser when connecting to the origin10 override_host_header: 'test-origin.edgio.net',1112 // The list of origin hosts to which to connect13 hosts: [14 {15 // The domain name or IP address of the origin server16 location: 'test-origin.edgio.net',17 },18 ],1920 tls_verify: {21 use_sni: true,22 sni_hint_and_strict_san_check: 'test-origin.edgio.net',23 },2425 // Uncomment the following to configure a shield26 // shields: { us_east: 'DCD' },27 },28],2930// Environment-specific configuration31environments: {32 production: {33 hostnames: [{ hostname: 'www.mysite.com' }],34 },35 staging: {36 hostnames: [{ hostname: 'staging.mysite.com' }],3738 // Override the `web` origin configuration for the staging environment39 origins: [40 {41 name: 'web',42 hosts: [{ location: 'staging-origin.mysite.com' }],43 override_host_header: 'staging-origin.mysite.com',44 tls_verify: {45 use_sni: true,46 sni_hint_and_strict_san_check: 'staging-origin.mysite.com',47 },48 shields: { us_east: 'DCD' },49 },50 ],51 },52},5354/* ... */
connector
The name of the connector package corresponding to the framework your app uses, or the path to a directory that implements the connector interface.
Example
To use a connector package:
JavaScript
1module.exports = {2 connector: '@edgio/next',3};
To implement a connector directly within your project:
JavaScript
1// this directory should have build.js, prod.js, and dev.js2module.exports = {3 connector: './path/to/connector/dir',4};
staticAssets
The
staticAssets
key is an array of objects determining how Edgio handles static assets in your app configured with the following properties:Property | Type | Description |
---|---|---|
permanent | Boolean | Set to true if the file has a hash in path so that it can be considered unique across deployments. |
glob | String[] | A list of glob patterns that match or omit files to be included. |
serverless
The
serverless
key is an object with the following properties:Property | Type | Description |
---|---|---|
includeNodeModules | Boolean | If true , the packages listed in the dependencies property of package.json will be included in the build that is deployed to Edgio. |
include | String[] | A list of glob patterns that match or omit files to be included in the serverless bundle. Example: lang/**/* |
sources
A list of glob patterns identifying which source files should be uploaded when running
edgio deploy --includeSources
. This option is primary used to share source code with Edgio support personnel for the purpose of debugging. If omitted, edgio deploy --includeSources
will result in all files which are not gitignored being uploaded to Edgio.Example:
JavaScript
1sources: [2 '**/*', // include all files3 '!(**/secrets/**/*)', // except everything in the secrets directory4];
interpolationValues
The following feature variables are only populated in a deployed environment. You can use the
interpolationValues
key to set these values in your local development environment for testing rules. Values set in this configuration are not propagated to the deployed environment.Property | Type |
---|---|
geo_city | string |
geo_country | string |
geo_latitude | string |
geo_longitude | string |
geo_postal_code | string |
is_origin_shield | string |
is_subrequest | string |
physical_doc_root | string |
physical_path | string |
physical_rel_path | string |
referring_domain | string |
virt_dst_asnum | string |
virt_dst_continent | string |
virt_dst_country | string |
virt_dst_port | string |
virt_http_version | string |
virt_ssl_cipher | string |
virt_ssl_client_cipher_codes | string |
virt_ssl_client_ciphers | string |
virt_ssl_client_tlsext_ids | string |
virt_ssl_protocol | string |
wurfl_cap_is_tablet | string |
wurfl_cap_mobile_browser | string |
wurfl_vcap_is_android | string |
wurfl_vcap_is_full_desktop | string |
wurfl_vcap_is_ios | string |
wurfl_vcap_is_robot | string |
wurfl_vcap_is_smartphone | string |
For instance, the value
virt_dst_country
is only available in a production environment. To enable this value for local development, you should set the following property:JavaScript
1interpolationValues.virt_dst_country: 'US'
Setting these properties can replicate the behavior of the production environment within your local development workspace.
cloudRuntime
Requires Edgio v7.4.0 or later.
The
cloudRuntime
key (string) determines which version of Node.js will run your app on our platform. Supported values are:nodejs16.x
(v7.4.0 through v7.4.4)nodejs18.x
(v7.4.0 or later)nodejs20.x
(v7.5.0 or later)
Edgio Applications’s support for Node.js version 16 is undergoing end-of-life. View the end-of-life plan.
If the
cloudRuntime
key is not defined, then Edgio will detect your project’s Node.js version upon running edgio deploy
. If an unsupported version is detected when using Edgio v7.4.0 or later, then it will set your version to nodejs18.x
. For instance:Bash
1# The Node.js 18 runtime is valid for Edgio v7.4.0 or later2$ node --version3v18.18.24$ edgio deploy56...78# Unsupported Node.js 21 runtime; defaults to Node.js 18 with a warning for Edgio v7.4.0 or later9$ node --version10v21.0.011$ edgio deploy
Unexpected behavior may occur when there is a mismatch between your project’s Node.js version and the one that runs your app on our platform. For example, if the
cloudRuntime
key is set to nodejs18.x
while the project is bundled with Node.js 20, the project will build with Node.js 20 but run in a Node.js 18 environment. Ensure the cloudRuntime
key aligns with your project’s Node.js version to prevent these types of issues.Default edgio.config.js
By default, the following
edgio.config.js
file is created by edgio init
. The contents of this file may differ when a framework supported by Edgio Sites is detected during initialization.See the full API specification for the
edgio.config.js
file here.JavaScriptedgio.config.js
1// This file was automatically added by edgio init.2// You should commit this file to source control.3// Learn more about this file at https://docs.edg.io/applications/edgio_config4module.exports = {5 // The name of the site in Edgio to which this app should be deployed.6 // name: 'my-site-name',78 // The name of the organization in Edgio to which this app should be deployed.9 // organization: 'my-organization-name',1011 // Overrides the default path to the routes file. The path should be relative to the root of your app.12 // routes: 'routes.js',1314 // When set to true or omitted entirely, Edgio includes the deployment number in the cache key,15 // effectively purging the cache each time you deploy.16 // purgeCacheOnDeploy: false,1718 origins: [19 {20 // The name of the backend origin21 name: 'origin',2223 // Use the following to override the host header sent from the browser when connecting to the origin24 override_host_header: 'test-origin.edgio.net',2526 // The list of origin hosts to which to connect27 hosts: [28 {29 // The domain name or IP address of the origin server30 location: 'test-origin.edgio.net',31 },32 ],3334 tls_verify: {35 use_sni: true,36 sni_hint_and_strict_san_check: 'test-origin.edgio.net',37 },3839 // Uncomment the following to configure a shield40 // shields: { us_east: 'DCD' },41 },42 ],4344 // Uncomment the following to specify environment specific configs45 // environments: {46 // production: {47 // hostnames: [{ hostname: 'www.mysite.com' }],48 // },49 // staging: {50 // hostnames: [{ hostname: 'staging.mysite.com' }],51 // origins: [52 // {53 // name: 'origin',54 // hosts: [{ location: 'staging-origin.mysite.com' }],55 // override_host_header: 'staging-origin.mysite.com',56 // tls_verify: {57 // use_sni: true,58 // sni_hint_and_strict_san_check: 'staging-origin.mysite.com',59 // },60 // shields: { us_east: 'DCD' },61 // },62 // ],63 // },64 // },6566 // Options for hosting serverless functions on Edgio67 // serverless: {68 // // Set to true to include all packages listed in the dependencies property of package.json when deploying to Edgio.69 // // This option generally isn't needed as Edgio automatically includes all modules imported by your code in the bundle that70 // // is uploaded during deployment71 // includeNodeModules: true,72 //73 // // Include additional paths that are dynamically loaded by your app at runtime here when building the serverless bundle.74 // include: ['views/**/*'],75 // },7677 // The maximum number of URLs that will be concurrently prerendered during deployment when static prerendering is enabled.78 // Defaults to 200, which is the maximum allowed value.79 // prerenderConcurrency: 200,8081 // A list of glob patterns identifying which source files should be uploaded when running edgio deploy --includeSources.82 // This option is primarily used to share source code with Edgio support personnel for the purpose of debugging. If omitted,83 // edgio deploy --includeSources will result in all files which are not gitignored being uploaded to Edgio.84 //85 // sources : [86 // '**/*', // include all files87 // '!(**/secrets/**/*)', // except everything in the secrets directory88 // ],89};