Upgrading to Edgio Applications Version 7

• 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.

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 #

• Version 5.x: Proceed to the Upgrade to Node.js 16.x step.
• Version 6.x: Proceed to the Create an Edgio account step.

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

     Copy

     1...
     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",
     9...

     You should update all of these references as shown below.
     JSONpackage.json version 7

     Copy

     1...  
     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",
     9...

   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

     Copy

     1import {isProductionBuild} from '@layer0/core/environment';
     2import {Router} from '@layer0/core/router';
     3import {nextRoutes} from '@layer0/next';
     4...

     You should update all of these import statements as shown below.
     JavaScriptroutes.ts version 7

     Copy

     1import {isProductionBuild} from '@edgio/core/environment';
     2import {Router} from '@edgio/core/router';
     3import {nextRoutes} from '@edgio/next';
     4...

   • 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

     Copy

     1const { withServiceWorker } = require('@layer0/next/sw')
     2const withLayer0 = require('@layer0/next/withLayer0')
     3module.exports = withLayer0(
     4...

     You should update all of these references as shown below.
     JavaScriptnext.config.js version 7

     Copy

     1const withEdgio = require('@edgio/next/withEdgio')
     2module.exports = withEdgio(
     3...

     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.
   Bash

   Copy

   npmYarn 1 (Classic)

   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:
   Bash.gitignore

   Copy

   1...
   2# Edgio generated build directory
   3.edgio

Step 2: Upgrade to Node.js 16.x #

Step 3: Create an Edgio Account #

Step 4: Create a Team #

1. From the Edgio Console, click on the

   

   icon next to your name and then click on Create a team.

   

2. In the Team Name option, assign a name to your team (e.g., my-company) and then click Create a Team.

   

3. Invite the desired team members. Learn more.

Step 5: Create a Property #

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.

     

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., www.example.com).
   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 #

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.

   

5. Click Create.

Step 7: Upgrade the Edgio CLI #

1npm install -g @edgio/cli

Step 8: Upgrade Edgio Packages #

1edgio use ^7.0.0

Step 9: Update your CDN-as-Code Configuration #

• edgio.config.js settings
• Routes
• Cache key customization
• Matching behavior
• Redirects
• Geolocation
• Device classification
• Response headers

edgio.config.js Settings #

• 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

  Copy

  1backends: {
  2  origin: {
  3    // The domain name or IP address of the origin server
  4    domainOrIp: "origin.mysite.com",
  5
  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: "www.mysite.com",
  9
  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,
  12
  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  },
  17}

  The equivalent configuration in version 7 is shown below.
  JavaScriptedgio.config.js version 7

  Copy

  1origins: [
  2  {
  3    // the key in backends
  4    name: "origin",
  5
  6    // from hostHeader
  7    override_host_header: "www.mysite.com",
  8
  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: "origin.mysite.com",
  18
  19            // from port
  20            port: 443,
  21          }
  22        ],
  23      },
  24    ],
  25
  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.
  29
  30    tls_verify: {
  31      use_sni: true,
  32      sni_hint_and_strict_san_check: 'www.mysite.com',
  33    },
  34
  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.
  38
  39    // If your serverless region is US East, use:
  40    shields: { us_east: 'DCD' },
  41
  42    // If your serverless region is US West, instead use:
  43    // shields: { us_west: 'SAC'},
  44
  45    // Uncomment the following lines to define a configuration equivalent to disableCheckCert: true 
  46    // tls_verify: {
  47    //   allow_self_signed_certs: true,
  48    // },
  49  },
  50]

• includeNodeModules: If you previously set includeNodeModules: true, then you should define it within a serverless property:
  JavaScriptedgio.config.js version 7

  Copy

  1serverless: {
  2  includeNodeModules: true,
  3},

• includeFiles: If you previously set includeFiles, then you should define it within a serverless property:
  JavaScriptedgio.config.js version 6 and earlier

  Copy

  1includeFiles: {
  2  'lang/**/*': true,  
  3  ‘public/**/*’: true
  4}

  JavaScriptedgio.config.js version 7

  Copy

  1serverless: {
  2  include: ["lang/**/*", "public/**/*"]
  3}

  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

  Copy

  1includeFiles: {
  2  'lang/**/*': 'another/dir/in/layer0/lambda',
  3},

Routes #

1new Router()
2  .get('/', {
3    caching: {
4      max_age: '1d' // cache for 1 day at the edge
5    }
6  })

1new Router()
2  .get('/', ({ cache }) => {
3    cache({ edge: { maxAgeSeconds: 60 * 60 * 24 }})
4  })

• 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.
  JavaScript

  Copy

  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 #

Matching Behavior #

• proxy
• renderWithApp
• serveStatic
• dir
• static
• send
• compute
• redirect
• appShell
• serviceWorker
• render

1new Router()
2  .get(‘/’, ({ proxy }) => proxy(‘web’))
3  .get(‘/:path*’, ({ proxy }) => proxy(‘legacy’))

1new Router()
2  .get(‘/:path*’, ({ proxy }) => proxy(‘legacy’))
3  .get(‘/’, ({ proxy }) => proxy(‘web’))

Redirects #

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  });

Geolocation #

• x-0-geo-city
• x-0-geo-country-code
• x-0-geo-latitude
• x-0-geo-longitude
• x-0-geo-postal-code

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  },
11});

Device Classification #

• x-0-device
• x-0-device-is-bot
• x-0-vendor
• x-0-browser

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  },
11});

Response Headers #

1. Add a route that enables debug cache response headers. A sample route is provided below.
   JavaScriptroutes.js

   Copy

   1new Router().match("/:path", {
   2  headers: {
   3    debug_header:true,
   4  },
   5});

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 #

1<script defer>
2  function initEdgioRum() {
3    new Edgio.Metrics({
4      token: 'ab1234c5-d6ef-789a-12c0-bb48102c2023' //version 7 token
5    }).collect()
6  }
7</script>
8<script src="https://rum.edgio.net/latest.js" defer onload="initEdgioRum()"></script>

Step 11: Build your Edgio Properties #

1edgio build

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:
   Bash

   Copy

   1npm ci

   Run edgio build to rebuild your Edgio property.
3. Regenerate a new dependency tree by running the following command:
   Bash

   Copy

   1npm i --package-lock-only

   Run edgio build to rebuild your Edgio property.

Step 12: Deploy to Edgio #

1edgio deploy --property=<PROPERTY> --team=<TEAM>

• 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 #

• API Domain: You must allow traffic from the following domain: api.edgio.app. 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).

Step 14: Update your DNS #

• Environment
• Team Space.

Migration Complete #

Additional Considerations #

• Cache-manifest.js File
• JWT Access Control End-of-Life
• Permalink Indexing
• GraphQL Caching End-of-Life
• Duplicate Query String Parameters

Cache-manifest.js File #

• 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 #

Permalink Indexing #

1new Router({ indexPermalink: true })

GraphQL Caching End-of-Life #

Duplicate Query String Parameters #