Edgio

edgio.config.js Configuration

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:
PropertyTypeDescription
namestring(Required) The origin name referred within the router.
override_host_headerstringThe 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.
hostsArray<Object>An array of objects that define how Edgio will proxy requests for this origin configuration.
hosts[].locationstring | 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[].hostnamestring(Required) The domain name or IP address of the origin server.
hosts[].location[].portnumberThe 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[].schemestringThe 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.
shieldsObjectDefines how Edgio will shield your origin configuration.
shields.apacstringThe POP code for the Asia Pacific shield.
shields.emeastringThe POP code for the Europe, Middle East, and Africa shield.
shields.us_weststringThe POP code for the US West shield.
shields.us_eaststringThe POP code for the US East shield.
tls_verifyObjectAn object that specifies how Edgio should verify the TLS certificate presented by the origin.
tls_verify.use_snibooleanWhether to use SNI when connecting to the origin. Defaults to false.
tls_verify.sni_hint_and_strict_san_checkstringSNI hint and enforce origin SAN/CN checking.
tls_verify.allow_self_signed_certsbooleanWhether to allow self-signed certificates. Defaults to false.
tls_verify.pinned_certsArray<string>An array of SHA256 hashes of pinned certificates.
Sample Configuration
JavaScript
1/* ... */
2origins: [
3 {
4 // The name of the backend origin
5 name: 'origin',
6
7 // Use the following to override the host header sent from the browser when connecting to the origin
8 override_host_header: 'test-origin.edgio.net',
9
10 // The list of origin hosts to which to connect
11 hosts: [
12 {
13 // The domain name or IP address of the origin server
14 location: 'test-origin.edgio.net',
15 },
16 ],
17
18 tls_verify: {
19 use_sni: true,
20 sni_hint_and_strict_san_check: 'test-origin.edgio.net',
21 },
22
23 // Uncomment the following to configure a shield
24 // 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:
PropertyTypeDescription
<ENV_NAME>String(Required) The name of the environment.
<ENV_NAME>.hostnamesObject[]A list of hostnames specific to the environment.
<ENV_NAME>.hostnames[].hostnameString(Required) The hostname for the environment.
<ENV_NAME>.hostnames[].default_origin_nameStringOptional default origin this hostname should use
<ENV_NAME>.hostnames[].tlsObjectOptional TLS configuration
<ENV_NAME>.originsObject[]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/* ... */
2
3// Global origins configuration
4origins: [
5 {
6 // The name of the backend origin
7 name: 'web',
8
9 // Use the following to override the host header sent from the browser when connecting to the origin
10 override_host_header: 'test-origin.edgio.net',
11
12 // The list of origin hosts to which to connect
13 hosts: [
14 {
15 // The domain name or IP address of the origin server
16 location: 'test-origin.edgio.net',
17 },
18 ],
19
20 tls_verify: {
21 use_sni: true,
22 sni_hint_and_strict_san_check: 'test-origin.edgio.net',
23 },
24
25 // Uncomment the following to configure a shield
26 // shields: { us_east: 'DCD' },
27 },
28],
29
30// Environment-specific configuration
31environments: {
32 production: {
33 hostnames: [{ hostname: 'www.mysite.com' }],
34 },
35 staging: {
36 hostnames: [{ hostname: 'staging.mysite.com' }],
37
38 // Override the `web` origin configuration for the staging environment
39 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},
53
54/* ... */

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.js
2module.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:
PropertyTypeDescription
permanentBooleanSet to true if the file has a hash in path so that it can be considered unique across deployments.
globString[]A list of glob patterns that match or omit files to be included.

serverless

The serverless key is an object with the following properties:
PropertyTypeDescription
includeNodeModulesBooleanIf true, the packages listed in the dependencies property of package.json will be included in the build that is deployed to Edgio.
includeString[]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 files
3 '!(**/secrets/**/*)', // except everything in the secrets directory
4];

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.
PropertyType
geo_citystring
geo_countrystring
geo_latitudestring
geo_longitudestring
geo_postal_codestring
is_origin_shieldstring
is_subrequeststring
physical_doc_rootstring
physical_pathstring
physical_rel_pathstring
referring_domainstring
virt_dst_asnumstring
virt_dst_continentstring
virt_dst_countrystring
virt_dst_portstring
virt_http_versionstring
virt_ssl_cipherstring
virt_ssl_client_cipher_codesstring
virt_ssl_client_ciphersstring
virt_ssl_client_tlsext_idsstring
virt_ssl_protocolstring
wurfl_cap_is_tabletstring
wurfl_cap_mobile_browserstring
wurfl_vcap_is_androidstring
wurfl_vcap_is_full_desktopstring
wurfl_vcap_is_iosstring
wurfl_vcap_is_robotstring
wurfl_vcap_is_smartphonestring
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 later
2$ node --version
3v18.18.2
4$ edgio deploy
5
6...
7
8# Unsupported Node.js 21 runtime; defaults to Node.js 18 with a warning for Edgio v7.4.0 or later
9$ node --version
10v21.0.0
11$ 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_config
4module.exports = {
5 // The name of the site in Edgio to which this app should be deployed.
6 // name: 'my-site-name',
7
8 // The name of the organization in Edgio to which this app should be deployed.
9 // organization: 'my-organization-name',
10
11 // Overrides the default path to the routes file. The path should be relative to the root of your app.
12 // routes: 'routes.js',
13
14 // 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,
17
18 origins: [
19 {
20 // The name of the backend origin
21 name: 'origin',
22
23 // Use the following to override the host header sent from the browser when connecting to the origin
24 override_host_header: 'test-origin.edgio.net',
25
26 // The list of origin hosts to which to connect
27 hosts: [
28 {
29 // The domain name or IP address of the origin server
30 location: 'test-origin.edgio.net',
31 },
32 ],
33
34 tls_verify: {
35 use_sni: true,
36 sni_hint_and_strict_san_check: 'test-origin.edgio.net',
37 },
38
39 // Uncomment the following to configure a shield
40 // shields: { us_east: 'DCD' },
41 },
42 ],
43
44 // Uncomment the following to specify environment specific configs
45 // 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 // },
65
66 // Options for hosting serverless functions on Edgio
67 // 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 that
70 // // is uploaded during deployment
71 // 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 // },
76
77 // 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,
80
81 // 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 files
87 // '!(**/secrets/**/*)', // except everything in the secrets directory
88 // ],
89};