Edgio Applications Version 5 Migration Guide

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

Consider upgrading to Edgio Applications version 6. It introduces support for running your app in the cloud using Node.js version 16. Edgio Applications version 6 requires:

Edgio Applications version 5
Node.js version 16
Updating your application(s) to be compatible with Node.js version 16.

We recommend that you perform the seamless Edgio Applications version 5 migration now. Once you are ready to update your application to be compatible with Node.js version 16, you should migrate to version 6.

Edgio Applications version 5.1+ .noIndexPermalink() is now deprecated, since we now instruct search engines to not index pages on edge links and permalinks by default.

Edgio Applications 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:

Upgrade the Edgio CLI.
Rename layer0.config.js.
Rename Edgio packages.
Install dependencies.
Update scripts that reference the Edgio CLI.
Ignore Edgio Build Artifacts (#optional-review-your-code-for-duplicate-query-string-parameters)
GraphQL Caching End-of-Life
Optional: Review your code for duplicate query string parameters.
Optional: Permalink Indexing

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.

By default, Edgio CLI v5.1.0+ collects usage and error reporting information to help improve our products. However, it omits personally identifiable information. Learn how to opt-out.

npm:

Bash
npm install -g @edgio/cli@^5.0.0

yarn:

Bash
yarn global add @edgio/cli@^5.0.0

Step 2: Rename layer0.config.js

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

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

Step 3: Rename Edgio Packages

For each site, 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 ^5.0.0.

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

...
  "dependencies": {
    "@layer0/rum": "4.18.1",
  },
  "devDependencies": {
    "@layer0/cli": "4.18.1",
    "@layer0/core": "4.18.1",
    "@layer0/devtools": "4.18.1",
...

You should update all of these references as shown below.

...
  "dependencies": {
    "@edgio/rum": "^5.0.0",
  },
  "devDependencies": {
    "@edgio/cli": "^5.0.0",
    "@edgio/core": "^5.0.0",
    "@edgio/devtools": "^5.0.0",
...

There may be additional @layer0/* dependencies listed in your site’s package.json file that are not listed above. They too should be updated to @edgio/*. 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:
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:

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

You should update all of these references as shown below.

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

Step 4: Install Dependencies

Install the dependencies defined in the previous step.

npm:

Bash
npm install

yarn:

Bash
yarn install

This should generate an updated dependency tree in your package-lock.json or yarn.lock file. Be sure to commit these changes.

Step 5: Update Scripts that Reference the Edgio CLI

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

Step 6: Ignore Edgio Build Artifacts

To exclude build artifacts from being tracked in version control, update your .gitignore file with the following:

Bash.gitignore
...
# Edgio generated build directory
.edgio

Step 7: GraphQL Caching End-of-Life

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

Step 8 (Optional): Review Your Code for Duplicate Query String Parameters

Edgio Applications 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 Applications 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 Applications 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.

Step 9: (Optional) Permalink Indexing

For Edgio Applications version 5.1 and above, the x-robots-tag: noindex header is automatically added to all responses being served from edge links and permalinks to prevent 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:

JavaScript
new Router({indexPermalink: true});

Migration Complete

Congratulations on successfully migrating Edgio to version 5! Once you are ready to make your application compatible with Node.js version 16, you should migrate to Edgio Applications version 6.