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:
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:
Rename layer0.config.js to edgio.config.js.
Edgio Applications version 5+ ignores the layer0.config.js configuration file.
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
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
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:
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.
Install the dependencies defined in the previous step.
Bash
1npm install
This should generate an updated dependency tree in your package-lock.json or yarn.lock file. Be sure to commit these changes.
Update all references to the Edgio CLI within your package.json scripts from 0 | layer0 to either edg or edgio.
Exclude build artifacts from being tracked in version control by updating your .gitignore file to:
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.
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.
Although you already have an existing account through app.layer0.co, you will need to sign up for a new account through edgio.app using the same email address, Google account, or Github account.
You now need to create your property within the Edgio Console.
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.
Click + New Property.
In the Property Name option, assign a unique name to this property.
Add the hostname(s) (aka custom domains) through which your site will be delivered. These hostnames will be added to the production environment.
From the Hostnames section, click + Add Hostname.
Type the desired hostname (e.g., www.example.com).
Repeat steps 1 and 2 as needed.
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.
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.
Update all Edgio packages to version 7 using the CLI.
Bash
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.
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:{
2origin:{
3// The domain name or IP address of the origin server
4domainOrIp:"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.
8hostHeader:"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
1origins:[
2{
3// the key in backends
4name:"origin",
5
6// from hostHeader
7override_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.
11hosts:[
12{
13scheme:"https",
14location:[
15{
16// from domainOrIp
17hostname:"origin.mysite.com",
18
19// from port
20port: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
30tls_verify:{
31use_sni:true,
32sni_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:
40shields:{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
1serverless:{
2includeNodeModules:true,
3},
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,
3 ‘public/**/*’:true
4}
JavaScriptedgio.config.js version 7
1serverless:{
2include:["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:
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
1newRouter()
2.get('/',{
3caching:{
4max_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
1newRouter()
2.get('/',({ cache })=>{
3cache({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.
JavaScript
1router.get('/',{
2origin:{
3set_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:
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)
addIsBot
Use %{wurfl_vcap_is_robot} instead. This variable returns true | false instead of 0 | 1.
addVendor
Use %{wurfl_vcap_is_ios} and %{wurfl_vcap_is_android} instead. This variable returns true | false instead of apple | android | generic.
addBrowser
Use %{wurfl_cap_mobile_browser} instead.
addDevice
Use %{wurfl_vcap_is_smartphone} and %{wurfl_cap_is_tablet} instead. These variables return true | false instead of 0 | 1.
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.
JavaScriptroutes.js
1newRouter()
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.
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.
JavaScriptroutes.js
1newRouter()
2.get("/home",{// simple example with a static URL
3url:{
4url_redirect:{
5destination:"/",
6},
7},
8})
9.get("/products/:id",{// example with a path variable
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-bot
Use %{wurfl_vcap_is_robot} instead. This variable returns true | false instead of 0 | 1.
x-0-vendor
Use %{wurfl_vcap_is_ios} and %{wurfl_vcap_is_android} instead. These variables return true | false instead of apple | android | generic.
x-0-browser
Use %{wurfl_cap_mobile_browser} instead.
x-0-device
Use %{wurfl_vcap_is_smartphone} and %{wurfl_cap_is_tablet} instead. These variables return true | false instead of smartphone | tablet | mobile | desktop.
Edgio Applications version 6 and adds the following headers with each response:
Header (Version 6 and Earlier)
Header (Version 7)
x-0-caching-status
View 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-components
No equivalent header.
x-0-status
No equivalent header.
x-0-t
No equivalent header.
x-0-version
x-edg-version
To enable debug cache response headers
Add a route that enables debug cache response headers. A sample route is provided below.
JavaScriptroutes.js
1newRouter().match("/:path",{
2headers:{
3debug_header:true,
4},
5});
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
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.
Build each of your Edgio properties by running the following command in its root directory:
Bash
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:
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.
Clear node_modules and rebundle your project by running the following command:
Bash
1npm ci
Run edgio build to rebuild your Edgio property.
Regenerate a new dependency tree by running the following command:
Once you have successfully built your property, run the following command to deploy your property to Edgio:
Bash
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:
The Edgio CLI will require that you log in to the Edgio if it does not detect an active Edgio session.
You will then need to authorize the CLI by granting it a token through which it may deploy your property to Edgio.
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
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: 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).
View our IP blocks by clicking Instructions from the Origins page.
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:
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.
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.
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:
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.
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.