Edgio
Edgio

Edgio Version 5 Migration Guide

If you are using Edgio version 3.x or earlier, you should review the v4 Migration Guide before migrating to version 5.

In the near future, we will release Edgio version 6 that introduces support for running your app in the cloud using Node.js version 16. Edgio version 6 requires:

  • Edgio version 5
  • Node.js version 16
  • npm version 8
  • Updating your application(s) to be compatible with Node.js version 16 and npm version 8.

In order to simplify this migration, we have split Node.js version 16 support from the branding changes introduced by Edgio version 5. We recommend that you perform the seamless Edgio version 5 migration now and prepare for the changes that will be required by Edgio version 6.

Edgio version 5 updates our CLI, packages, and a configuration file with Edgio branding. Additionally, our service will no longer modify duplicate query string parameters.

Migrate from version 4.x to 5 through the following steps:

  1. Upgrade the Edgio CLI.
  2. Upgrade the Edgio RUM package.
  3. Rename layer0.config.js.
  4. Rename Edgio packages.
  5. Install dependencies.
  6. Run edgio init.
  7. Update scripts that reference the Edgio CLI.
  8. Optional: Review your code for duplicate query string parameters.

Step 1: Upgrade the Edgio CLI

We have renamed the Edgio CLI from 0 | layer0 to edg | edgio. Install the latest version of our CLI.

npm:

Bash
1npm install -g @edgio/cli

yarn:

Bash
1yarn global add @edgio/cli

Step 2: Upgrade the Edgio Real User Monitoring (RUM) Package

We have renamed the Edgio RUM package from @layer0/rum to @edgio/rum. For each site, uninstall the old version and then install the latest version.

npm:

Bash
1npm uninstall @layer0/rum
2npm install @edgio/rum

yarn:

Bash
1yarn remove @layer0/rum
2yarn add @edgio/rum

Step 3: Rename layer0.config.js

For each site, rename layer0.config.js to edgio.config.js.

Edgio version 5.x ignores the layer0.config.js configuration file.

Step 4: Rename Edgio Packages

The dependency for the Edgio RUM package (@edgio/rum) was updated in step 2 and therefore does not require any additional changes.

For each site, rename remaining references to Edgio packages from @layer0 to @edgio.

  • package.json: In addition to renaming the remaining Edgio packages, you should also set their version to ^5.0.0.

    For example, the following excerpt from a package.json file references several @layer0 packages:

    1...
    2 "devDependencies": {
    3 "@layer0/cli": "4.18.1",
    4 "@layer0/core": "4.18.1",
    5 "@layer0/devtools": "4.18.1",
    6...

    You should update all of these references as shown below.

    1...
    2 "devDependencies": {
    3 "@edgio/cli": "^5.0.0",
    4 "@edgio/core": "^5.0.0",
    5 "@edgio/devtools": "^5.0.0",
    6...
  • 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:

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

    You should update all of these import statements as shown below.

    1import {isProductionBuild} from '@edgio/core/environment';
    2import {Router, CustomCacheKey} from '@edgio/core/router';
    3import {nextRoutes} from '@edgio/next';
    4...
  • 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:

    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.

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

Step 5: Install Dependencies

Install the dependencies defined in the previous step.

npm:

Bash
1npm install

yarn:

Bash
1yarn install

Step 6: Run edgio init

For each site, run the following command:

Bash
1edgio init

Proceed to the next step if this command is successful.

Step 7: Update Scripts that Reference the Edgio CLI

Update all references to the Edgio CLI within your scripts from 0 | layer0 to either edg or edgio.

Optional: Review Your Code for Duplicate Query String Parameters

Edgio version 5 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:

https://sports.example.com/index.html?id=123&type=Sports&type=Basketball

Edgio version 4 will modify the duplicate query string parameters as shown below.

https://sports.example.com/index.html?id=123&type=Sports%5B0%5D&type%5B1%5D=Basketball

Edgio version 5, on the other hand, will not modify the query string as shown below.

https://sports.example.com/index.html?id=123&type=Sports&type=Basketball

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.

Migration Complete

Congratulations on successfully migrating Edgio to version 5!