Introducing Edgio Applications v7Find out what's new.

Upgrading to Edgio Applications Version 7

The Edgio Applications platform consists of the following products:
  • Edgio Performance improves your site’s performance and speeds up your development lifecycle. Learn more.
  • Edgio Security provides robust, multi-layered Web Application and API Protection. Learn more.
  • Edgio Sites provides optimal performance and development efficiency to your headless Jamstack applications. Learn more.
    Edgio Sites version 7 currently only supports Next, Nuxt, and Nuxt 3. We plan on introducing support for a wide variety of web application frameworks in the near future. If your property is a traditional website, uses a supported framework, or if you have not integrated your web application framework through Edgio Sites, then you may proceed to upgrade to version 7.
Upgrading to Edgio Applications to version 7 involves the following steps:
  1. Layer0 (Version 4 and Earlier): Rename layer0.config.js and Edgio packages.
  2. Version 5 and Earlier: Upgrade Node.js to version 16.x and update your application to be compatible with Node.js 16.x.
  3. Create an Edgio account.
  4. Create a team.
  5. Create a property.
  6. Define environments.
  7. Upgrade the Edgio CLI.
  8. Upgrade Edgio packages.
  9. Update your CDN-as-code configuration to reflect changes introduced in version 7.
  10. Real User Monitoring (RUM) Token
  11. Build your Edgio properties.
  12. Deploy to Edgio
  13. Configure your Firewall
  14. Update your DNS

Step 1: Rename layer0 Components

This section only applies to Edgio Applications 4 and earlier. Skip this step if you are using a later version.
Edgio Applications now uses Edgio branding for our CLI, packages, and a configuration file. Additionally, our service will no longer modify duplicate query string parameters.
Perform the following steps for each of your properties:
  1. Rename layer0.config.js to edgio.config.js.
    Edgio Applications version 5+ ignores the layer0.config.js configuration file.
  2. Rename all references to Edgio packages from @layer0 to @edgio.
    • package.json: In addition to renaming the Edgio packages, you should also set their version to ^7.0.0.
      For example, the following excerpt from a package.json file references several @layer0 packages:
      JSONpackage.json version 4 and earlier
      2 "dependencies": {
      3 "@layer0/rum": "4.18.1",
      4 },
      5 "devDependencies": {
      6 "@layer0/cli": "4.18.1",
      7 "@layer0/core": "4.18.1",
      8 "@layer0/devtools": "4.18.1",
      You should update all of these references as shown below.
      JSONpackage.json version 7
      2 "dependencies": {
      3 "@edgio/rum": "^7.0.0",
      4 },
      5 "devDependencies": {
      6 "@edgio/cli": "^7.0.0",
      7 "@edgio/core": "^7.0.0",
      8 "@edgio/devtools": "^7.0.0",
    There may be additional @layer0/* dependencies listed in your site’s package.json file that are not listed above. Update those dependencies to @edgio/*. After which, there should be no remaining @layer0/* references in the file.
    • Import Statements: Rename Edgio packages within each import statement from @layer0 to @edgio. You can find these import statements within various files, such as routes.ts, sw/service-worker.js, and your Next and Nuxt configuration files.
      For example, the following excerpt from a routes.ts file imports various @layer0 packages:
      JavaScriptroutes.ts version 4 and earlier
      1import {isProductionBuild} from '@layer0/core/environment';
      2import {Router} from '@layer0/core/router';
      3import {nextRoutes} from '@layer0/next';
      You should update all of these import statements as shown below.
      JavaScriptroutes.ts version 7
      1import {isProductionBuild} from '@edgio/core/environment';
      2import {Router} from '@edgio/core/router';
      3import {nextRoutes} from '@edgio/next';
    • edgio.config.js: If you are using an Edgio connector, then you should also rename the connector defined in the connector property.
      For example, you should update connector: '@layer0/next' to connector: '@edgio/next'.
    • Next app: Rename all Edgio references within your next.config.js from @layer0 to @edgio.
      For example, the following excerpt from a next.config.js file contains several @layer0 references:
      JavaScriptnext.config.js version 4 and earlier
      1const { withServiceWorker } = require('@layer0/next/sw')
      2const withLayer0 = require('@layer0/next/withLayer0')
      3module.exports = withLayer0(
      You should update all of these references as shown below.
      JavaScriptnext.config.js version 7
      1const withEdgio = require('@edgio/next/withEdgio')
      2module.exports = withEdgio(
      Version 7 no longer requires the withServiceWorker function to be explicitly defined within the next.config.js file and therefore it may be safely removed.
  3. Install the dependencies defined in the previous step.
    1npm install
    This should generate an updated dependency tree in your package-lock.json or yarn.lock file. Be sure to commit these changes.
  4. Update all references to the Edgio CLI within your package.json scripts from 0 | layer0 to either edg or edgio.
  5. Exclude build artifacts from being tracked in version control by updating your .gitignore file to:
    2# Edgio generated build directory

Step 2: Upgrade to Node.js 16.x

This section only applies to Edgio Applications version 5.x and earlier. If you are using version 6.x, proceed to the Create an Edgio account step.
Edgio Applications version 6+ runs your apps in Node.js v16. Therefore, we strongly recommend that you use Node.js v16.x when developing your web application.
Learn how to use nvm to install Node.js v16.x.
Once you are using Node.js v16, update your application code to be compatible with Node.js v16.
If package.json or .npmrc explicitly sets the Node.js engine version to 14.x, then you will need to update it to 16.x.
Additionally, check your CI/CD environment for Node.js version settings. If your workflow targets Node.js 14.x, then you will need to update your files and settings to target Node.js 16.x.

Step 3: Create an Edgio Account

Although you already have an existing account through, you will need to sign up for a new account through using the same email address, Google account, or Github account.

Step 4: Create a Team

If the property being migrated belongs to a team space, then you will need to recreate that team within
  1. From the Edgio Console, click on the
    icon next to your name and then click on Create a team.
    Space menu
  2. In the Team Name option, assign a name to your team (e.g., my-company) and then click Create a Team.
    Add a Team
  3. Invite the desired team members. Learn more.
If you are an enterprise customer, contact your account manager or our sales department at 1 (866) 200 - 5463 to upgrade your newly created team.

Step 5: Create a Property

You now need to create your property within the Edgio Console.
  1. From the Edgio Console, determine where you will create a property.
    • Private Space: By default, the Edgio Console loads your private space. Access to a property created in your private space is restricted to your account. Proceed to the next step.
    • Team Space: Load the desired team by clicking the
      icon that appears next to your name and then selecting the desired team.
      Team Selection
  2. Click + New Property.
  3. In the Property Name option, assign a unique name to this property.
  4. Add the hostname(s) (aka custom domains) through which your site will be delivered. These hostnames will be added to the production environment.
    1. From the Hostnames section, click + Add Hostname.
    2. Type the desired hostname (e.g.,
    3. Repeat steps 1 and 2 as needed.
  5. Delete the default origin configuration (aka backend) by clicking the
    icon that appears on the right-hand side of the Origin: web bar.
    Since you are taking advantage of CDN-as-code, you should define your origin configuration(s) within the edgio.config.js file instead of the Edgio Console. Information on how to define origin configurations is provided within the Update your CDN-as-code configuration step.
  6. Click Create Property.

Step 6: Define Environments

If the property being migrated uses multiple environments in version 6, then you should recreate those environments within your new property.
  1. Load the Environments page.
    1. From the Edgio Console, select the desired private or team space.
    2. Select the desired property.
    3. From the left-hand pane, click Environments.
  2. Click + New Environment.
  3. In the Name option, specify a name for this environment. This name may consist of lowercase characters, numbers, dashes (-), and underscores (_).
  4. Determine deployment permissions through the Allow all team members to deploy to this environment option.
    • Mark this option to allow all team members to deploy to this environment.
    • Clear this option to restrict deployment to admins and the deploy token.
    limit environment
  5. Click Create.

Step 7: Upgrade the Edgio CLI

Install the latest version of our CLI.
By default, Edgio CLI v5.1+ collects usage and error reporting information to help improve our products. However, it omits personally identifiable information. Learn how to opt-out.
1npm install -g @edgio/cli

Step 8: Upgrade Edgio Packages

Update all Edgio packages to version 7 using the CLI.
1edgio use ^7.0.0
If you are upgrading from version 4 and earlier, then you should have already upgraded to version 7. In which case, the above step will indicate that your packages are up to date.

Step 9: Update your CDN-as-Code Configuration

Updating your CDN-as-code configuration to be compatible with version 7 involves:

edgio.config.js Settings

Update each property’s edgio.config.js as indicated below.
  • backends: The backends property has been replaced with the origins property.
    For example, we will assume that your backends property is configured as follows:
    JavaScriptedgio.config.js version 6 and earlier
    1backends: {
    2 origin: {
    3 // The domain name or IP address of the origin server
    4 domainOrIp: "",
    6 // When provided, the following value will be sent as the host header when connecting to the origin.
    7 // If omitted, the host header from the browser will be forwarded to the origin.
    8 hostHeader: "",
    10 // Uncomment the following line if TLS is not set up properly on the origin domain and you want to ignore TLS errors
    11 // disableCheckCert: true,
    13 // Overrides the default ports (80 for http and 443 for https) and instead use a specific port
    14 // when connecting to the origin
    15 // port: 1337,
    16 },
    The equivalent configuration in version 7 is shown below.
    JavaScriptedgio.config.js version 7
    1origins: [
    2 {
    3 // the key in backends
    4 name: "origin",
    6 // from hostHeader
    7 override_host_header: "",
    9 // Version 7 introduces the ability to load balance across multiple origin hosts.
    10 // Previous versions only supported a single host per origin.
    11 hosts: [
    12 {
    13 scheme: "https",
    14 location: [
    15 {
    16 // from domainOrIp
    17 hostname: "",
    19 // from port
    20 port: 443,
    21 }
    22 ],
    23 },
    24 ],
    26 // In version 7, you may enable Server Name Indication (SNI) and define a SNI hint.
    27 // This configuration is essential when using multiple domains, since it allows us to
    28 // present to the browser a certificate with the correct name during the TLS handshake.
    30 tls_verify: {
    31 use_sni: true,
    32 sni_hint_and_strict_san_check: '',
    33 },
    35 // In version 7, the location of the shield (formerly referred to as the “global” PoP) is
    36 // configured in edgio.config.js instead of the Edgio Console
    37 // Previous versions only supported a single shield in a single region.
    39 // If your serverless region is US East, use:
    40 shields: { us_east: 'DCD' },
    42 // If your serverless region is US West, instead use:
    43 // shields: { us_west: 'SAC'},
    45 // Uncomment the following lines to define a configuration equivalent to disableCheckCert: true
    46 // tls_verify: {
    47 // allow_self_signed_certs: true,
    48 // },
    49 },
  • includeNodeModules: If you previously set includeNodeModules: true, then you should define it within a serverless property:
    JavaScriptedgio.config.js version 7
    1serverless: {
    2 includeNodeModules: true,
  • includeFiles: If you previously set includeFiles, then you should define it within a serverless property:
    JavaScriptedgio.config.js version 6 and earlier
    1includeFiles: {
    2 'lang/**/*': true,
    3public/**/*: true
    JavaScriptedgio.config.js version 7
    1serverless: {
    2 include: ["lang/**/*", "public/**/*"]
    Versions 6 and earlier supports mapping an input path to a different output path. Version 7 does not support this capability. For example, the following configuration is unsupported:
    JavaScriptedgio.config.js version 6 and earlier
    1includeFiles: {
    2 'lang/**/*': 'another/dir/in/layer0/lambda',


Edgio Applications version 7 introduces a new JSON syntax for defining the set of features that will be applied to a route.
For example, the following route sets a CDN caching policy:
JavaScriptedgio.config.js version 7
1new Router()
2 .get('/', {
3 caching: {
4 max_age: '1d' // cache for 1 day at the edge
5 }
6 })
The equivalent route in version 6 and earlier is:
JavaScriptedgio.config.js version 6 and earlier
1new Router()
2 .get('/', ({ cache }) => {
3 cache({ edge: { maxAgeSeconds: 60 * 60 * 24 }})
4 })
In order to ease the transition to version 7, we provide limited support for legacy syntax. However, the following syntax is unsupported:
  • fallback(): The fallback() method, which is unsupported in version 7, executes when no other route is matched. If you are trying to proxy a request to a legacy origin, then you may do so by mapping the desired hostname to an origin configuration from within the Edgio Console.
    Deploying to Edgio automatically generates origin configurations from those defined within the edgio.config.js file. For this reason, we recommend that you map your hostnames to origins once you have deployed your property to Edgio. Learn more.
    You may also manually assign an origin configuration within a route through set_origin. If you want this route to act as a catch-all, then we recommend that you position it above your other routes.
    1router.get('/', {
    2 origin: {
    3 set_origin: 'myorigin',
    4 }
    5 })
  • catch(): The catch() method, which is unsupported in version 7, allows the user to alter responses that have returned an error code.
  • destination(): The destination() method is unsupported in version 7 at this time. However, you may assign an origin to requests through set_origin and redirect requests through url_redirect. A future release will provide a streamlined version of traffic splitting through the Edgio Console.
  • ResponseWriter Methods: The following ResponseWriter methods are not fully supported in version 7:
    • updateResponseCookie
    • removeResponseCookie
    • addUpstreamResponseCookie
    • removeUpstreamResponseCookie
    • setUpstreamResponseHeader
    • updateUpstreamResponseHeader

Cache Key Customization

Customize the cache key through cache_key_rewrite instead of CustomCacheKey. Additionally, there are some subtle differences in our device classification implementation.
Method (Version 6 and Earlier)Variable (Version 7)
addIsBotUse %{wurfl_vcap_is_robot} instead. This variable returns true | false instead of 0 | 1.
addVendorUse %{wurfl_vcap_is_ios} and %{wurfl_vcap_is_android} instead. This variable returns true | false instead of apple | android | generic.
addBrowserUse %{wurfl_cap_mobile_browser} instead.
addDeviceUse %{wurfl_vcap_is_smartphone} and %{wurfl_cap_is_tablet} instead. These variables return true | false instead of 0 | 1.

Matching Behavior

Edgio Applications version 6 and earlier returns an immediate response upon encountering one of the following methods:
  • proxy
  • renderWithApp
  • serveStatic
  • dir
  • static
  • send
  • compute
  • redirect
  • appShell
  • serviceWorker
  • render
In version 7, all routes that match the request are executed. This may cause unexpected behavior when multiple routes provide conflicting instructions.
We will now examine how the following routes are handled by different versions of Edgio Applications.
1new Router()
2 .get(/, ({ proxy }) => proxy(‘web’))
3 .get(/:path*, ({ proxy }) => proxy(‘legacy’))
Version 6 and earlier will serve requests to / from the web origin. The second route will not take effect because the request satisfied the first proxy method. Version 7, on the other hand, matches both routes for requests to /. The first route sets the origin to web, while the second route immediately overrides the first route and sets the origin to legacy. As a result, all requests will be sent to the legacy origin.
Therefore, the origin in which routes are defined is important. We recommend placing routes with general criteria before routes with more detailed criteria.
For example, reversing the order of the routes ensures that requests to / are served from the web origin.
1new Router()
2 .get(/:path*, ({ proxy }) => proxy(‘legacy’))
3 .get(/, ({ proxy }) => proxy(‘web’))


Edgio Applications version 6 and earlier allows you to set redirects by uploading a CSV file within the Edgio Console. This capability is unsupported in version 7. However, you may define redirects within your routes through the url_redirect feature.
1new Router()
2 .get("/home", { // simple example with a static URL
3 url: {
4 url_redirect: {
5 destination: "/",
6 },
7 },
8 })
9 .get("/products/:id", { // example with a path variable
10 url: {
11 url_redirect: {
12 syntax: 'path-to-regexp',
13 source: "/products/:id",
14 destination: "/p/:id",
15 },
16 },
17 });


Edgio Applications version 6 and earlier adds the following geo-location request headers to all requests sent to the origin:
  • x-0-geo-city
  • x-0-geo-country-code
  • x-0-geo-latitude
  • x-0-geo-longitude
  • x-0-geo-postal-code
In version 7, geolocation headers are not included by default. However, you may define them through HTTP variables as demonstrated below.
1new Router().match("/:path", {
2 headers: {
3 set_request_headers: {
4 "x-0-geo-country": "%{geo_country}",
5 "x-0-geo-city": "%{geo_city}",
6 "x-0-geo-latitude": "%{geo_latitude}",
7 "x-0-geo-longitude": "%{geo_longitude}",
8 "x-0-geo-postal-code": "%{geo_postal_code}",
9 },
10 },

Device Classification

Edgio Applications version 6 and earlier adds the following device classification headers to all requests sent to the origin:
  • x-0-device
  • x-0-device-is-bot
  • x-0-vendor
  • x-0-browser
In version 7, device classification headers are not included by default. However, you may define them through HTTP variables as demonstrated below.
Header (Version 6 and Earlier)Variable (Version 7)
x-0-device-is-botUse %{wurfl_vcap_is_robot} instead. This variable returns true | false instead of 0 | 1.
x-0-vendorUse %{wurfl_vcap_is_ios} and %{wurfl_vcap_is_android} instead. These variables return true | false instead of apple | android | generic.
x-0-browserUse %{wurfl_cap_mobile_browser} instead.
x-0-deviceUse %{wurfl_vcap_is_smartphone} and %{wurfl_cap_is_tablet} instead. These variables return true | false instead of smartphone | tablet | mobile | desktop.
1new Router().match("/:path", {
2 headers: {
3 set_request_headers: {
4 "x-0-device-is-bot": "%{wurfl_vcap_is_robot}",
5 "x-0-geo-city": "%{geo_city}",
6 "x-0-geo-latitude": "%{geo_latitude}",
7 "x-0-geo-longitude": "%{geo_longitude}",
8 "x-0-geo-postal-code": "%{geo_postal_code}",
9 },
10 },

Response Headers

Edgio Applications version 6 and adds the following headers with each response:
Header (Version 6 and Earlier)Header (Version 7)
x-0-caching-statusView additional information about the cache policy applied to the requested content through debug cache response headers. Information on how to enable debug cache response headers is provided below.
x-0-componentsNo equivalent header.
x-0-statusNo equivalent header.
x-0-tNo equivalent header.
To enable debug cache response headers
  1. Add a route that enables debug cache response headers. A sample route is provided below.
    1new Router().match("/:path", {
    2 headers: {
    3 debug_header:true,
    4 },
  2. Send the following header with each request: x-ec-debug:x-ec-cache,x-ec-cache-remote,x-ec-check-cacheable,x-ec-cache-key,x-ec-cache-state
    Learn more.

Step 10: Real User Monitoring (RUM) Token

If you are tracking Core Web Vitals through RUM, then you will need to update the initEdgioRum script to use your version 7 token. Your version 7 token is provided on the Core Web Vitals page.
1<script defer>
2 function initEdgioRum() {
3 new Edgio.Metrics({
4 token: 'ab1234c5-d6ef-789a-12c0-bb48102c2023' //version 7 token
5 }).collect()
6 }
8<script src="" defer onload="initEdgioRum()"></script>

Step 11: Build your Edgio Properties

Build each of your Edgio properties by running the following command in its root directory:
1edgio build
If you encounter a build issue as a result of upgrading Node.js, then you should perform one or more of the following troubleshooting steps:
  1. Check whether you have defined a different Node.js or npm version in either a npm config file (.npmrc) or within package.json. If so, update it to the correct version and then run edgio build to rebuild your Edgio property.
    Run node --version to check the Node.js version that you are currently using. This command should return 16.x.x (e.g., 16.18.0). Use this version information when updating .npmrc or package.json.
  2. Clear node_modules and rebundle your project by running the following command:
    1npm ci
    Run edgio build to rebuild your Edgio property.
  3. Regenerate a new dependency tree by running the following command:
    1npm i --package-lock-only
    Run edgio build to rebuild your Edgio property.

Step 12: Deploy to Edgio

Once you have successfully built your property, run the following command to deploy your property to Edgio:
1edgio deploy --property=<PROPERTY> --team=<TEAM>
Key information:
  • Replace the following placeholders:
    • <PROPERTY>: Replace this placeholder with the name of the property created in step 5.
    • <TEAM>: Replace this placeholder with the name of the team created in step 4. If you are deploying to a property in a private space, then you should omit --team=<TEAM> from this command.
  • Upon running the above command:
    1. The Edgio CLI will require that you log in to the Edgio if it does not detect an active Edgio session.
    2. You will then need to authorize the CLI by granting it a token through which it may deploy your property to Edgio.
    3. The CLI will warn that you are overwriting a configuration defined within the Edgio Console. This is the expected behavior and you should press y to continue.
      Deploying a CDN-as-code configuration overwrites rules and origin configurations defined within the Edgio Console. In this case, the CLI detected changes that are not present in your edgio.config.js. Specifically, it detected new hostnames (aka custom domains). In the near future, you will be allowed to define those hostnames within your edgio.config.js. In the meantime, this error will only occur whenever the CLI detects new changes performed within the Edgio Console. Future deployments should not trigger this warning unless you make additional configuration changes within the Edgio Console.
  • The above syntax is only required for your first deployment. After which, you may deploy by running: edgio deploy

Step 13: Configure your Firewall

Edgio Applications version 7 uses a different set of IP blocks than previous versions. This means that you need to update your firewall to allow:
  • API Domain: You must allow traffic from the following domain: If you plan on deploying to a development or CI/CD environment, then you will also need to allow this domain for the firewall for those environments.
  • IP Blocks: You must allow traffic from Edgio IP blocks if you plan on using origin configuration(s) (aka backends).
View our IP blocks by clicking Instructions from the Origins page.
Learn more.

Step 14: Update your DNS

If you are an enterprise customer and have not already reached out to your account manager to upgrade your team, please do so before serving traffic through Edgio Applications version 7. You may contact our sales department at 1 (866) 200 - 5463.
Once you are ready to serve traffic through Edgio, you will need to update the DNS for each of your hostname(s). Specifically, version 7 requires a CNAME record that points to a service domain that is either specific to your property’s:
Although version 6 supports both A and CNAME records, version 7 only supports CNAME records.

Migration Complete

Congratulations on successfully migrating Edgio to version 7!

Additional Considerations

Review the following changes and revise your configuration as needed:

Cache-manifest.js File

Version 7 no longer generates or uses the cache-manifest.js file. If you detect 404 Not Found requests for cache-manifest.js after upgrading to version 7, verify that:
  • You have upgraded the @edgio/prefetch library to version 7.
  • Your application no longer references the @layer0/prefetch library.

JWT Access Control End-of-Life

Edgio Applications version 6 does not support JWT access control. Previous versions allowed you to configure on a per route basis whether requests would be allowed or denied according to a JWT token.

Permalink Indexing

Edgio Applications version 5.1+ automatically adds the x-robots-tag: noindex, nofollow header all responses being served from edge links and permalinks. This prevents search engines from indexing those links. By default, this header will not be added to any responses served from a custom domain. Prior to version 5.1, the .noIndexPermalink() function was an opt-in solution to achieve the same effect.
As a result, the .noIndexPermalink() router function is now deprecated and serves no purpose. We recommend that you remove this function from your routes.[js|ts] file.
However, if you want to override this default behavior and allow search engines to index all permalinks, you can pass the option indexPermalink set to true to the Router constructor:
1new Router({ indexPermalink: true })

GraphQL Caching End-of-Life

Edgio ended support for caching of GraphQL operations. If your Edgio router (routes.[js|ts]) contains usage of .graphqlOperation(...), you should remove it. Otherwise, your application will fail to build.

Duplicate Query String Parameters

Edgio Applications will no longer modify the request’s query string when it detects a duplicate query string parameter.
For example, we will examine how both versions of Edgio handle the following request:
Edgio Applications version 4 will modify the duplicate query string parameters as shown below.
Edgio Applications version 7, on the other hand, will not modify the query string as shown below.
Review your code to see whether it generates duplicate query string parameters. If it does, update it to handle multiple query string parameters with the same name.