Getting Started with CDN-As-Code

Our CDN-as-code approach to configuration allows you to configure CDN behavior using EdgeJS within a file (routes.[js|ts]) stored alongside your code. This allows you to leverage the power of source control for collaboration and to link your CDN configurations with specific versions of your web application.

Quick Start

Get started with CDN-as-code by:

Creating and deploying a property to Edgio.

Learn more.

Alternatively, you may experiment with our sample websites by deploying them to Edgio.
Use the Edgio CLI to initialize your property.

This step requires Node.js v16.x.

Install the Edgio CLI, initialize your property, and then deploy it by running the following command from the root directory of your web application or website:
Bash
1npx @edgio/cli@latest init \
2--name <PROPERTY> \
3--deploy
Define routes that determine how Edgio will handle that traffic.
Test your changes locally.
Deploy your property to the Edgio network.

Routes.js|ts File

The routes.[js|ts] file defines a set of routes. A route:

Identifies a set of requests by HTTP method, URL path, query string parameters, cookies, and request headers.
Determines how our CDN will handle the above requests. For example, you may configure those requests to be cached, prefetched, passed through without modification, or served as static content.

By default, our CLI automatically creates routes.js and edgio.config.js upon initializing a property (edgio init). If your web application supports TypeScript and it uses a framework for which we have a TypeScript implementation, then our CLI will create routes.ts instead of routes.js.

Default Route Configuration

By default, your routes.[js|ts] contains the following configuration:

JavaScript./routes.js
import {Router} from '@edgio/core/router';

// const ONE_HOUR = 60 * 60
// const ONE_DAY = 24 * ONE_HOUR

export default new Router()

  // Here is an example where we cache api/* at the edge but prevent caching in the browser
  // .match('/api/:path*', ({ proxy, cache }) => {
  //   cache({
  //     edge: {
  //       maxAgeSeconds: ONE_DAY,
  //       staleWhileRevalidateSeconds: ONE_HOUR,
  //     },
  //     browser: {
  //       maxAgeSeconds: 0,
  //       serviceWorkerSeconds: ONE_DAY,
  //     },
  //   })
  //   proxy('origin')
  // })

  // send any unmatched request to origin
  .fallback(({proxy}) => proxy('origin'));

The above configuration proxies all requests that do not match a route to the origin backend. Additionally, it does not define a route, since the only match() method has been commented-out. This means that all requests will be proxied to the origin backend.

A backend identifies a domain or IP address to which Edgio may proxy requests. In this case, the origin backend was defined when you initialized this property using the edgio init command.

Add, modify, and remove backends by editing the edgio.config.js file.

Routes

A route identifies a set of requests through any combination of URL path, HTTP method, cookies, request headers, and query string parameters. The following routes show various ways for identifying requests.

Match all requests:

JavaScript
.match('/:path*', () => {
  // route handler goes here
})

Match all GET requests whose URL path starts with /marketing/images/:
JavaScript
1.get('/marketing/images/:path*', () => {
2 // route handler goes here
3})

Match all GET and POST requests whose URL path starts with /marketing/images/ and contain the sport request header set to basketball:

JavaScript
.match(
  {
    path: '/marketing/images/:path*',
    method: /GET|POST/i, // regular expression
    headers: { 'sport': /^basketball$/i }, // keys are header names; values are regular expressions
  },
  () => {
  // route handler goes here
})

Once you have identified a set of requests, you need to define how Edgio will handle those requests. The following routes show various ways in which requests can be processed.

Apply a caching policy to all requests and proxy cache misses to the origin backend:

JavaScript
.match('/:path*', ({ proxy, cache }) => {
  cache({
    edge: {
      maxAgeSeconds: 3600
    }
  })
  proxy('origin')
})

Set the images response header and proxy cache misses to the origin backend for all GET requests whose URL path starts with /marketing/images/:
JavaScript
1.get('/marketing/images/:path*', ({ setResponseHeader, proxy }) => {
2 setResponseHeader('images', 'true')
3 proxy('origin')
4})

View additional examples.

Defining Routes

We will now define a route by uncommenting the constants and the match() method in your routes.[js|ts] file. It should now look similar to the following configuration:

JavaScript./routes.js
import {Router} from '@edgio/core/router';

const ONE_HOUR = 60 * 60;
const ONE_DAY = 24 * ONE_HOUR;

export default new Router()

  // Here is an example where we cache api/* at the edge but prevent caching in the browser
  .match('/api/:path*', ({proxy, cache}) => {
    cache({
      edge: {
        maxAgeSeconds: ONE_DAY,
        staleWhileRevalidateSeconds: ONE_HOUR,
      },
      browser: {
        maxAgeSeconds: 0,
        serviceWorkerSeconds: ONE_DAY,
      },
    });
    proxy('origin');
  })

  // send any unmatched request to origin
  .fallback(({proxy}) => proxy('origin'));

The above route matches all requests that start with /api/ and instructs Edgio to:

Cache those requests on our network for one day.
Allow us to serve stale content for one hour.
Instruct the browser to treat the response as immediately stale.
Allow prefetched requests to be served from cache for one day.
Proxy those requests to your origin backend when we cannot serve them from cache.

You can use constants to apply this same caching policy to various routes. Define a CACHE_ASSETS constant and set it to the cache object defined in the above route.

JavaScript./routes.js
import { Router } from '@edgio/core/router'

 const ONE_HOUR = 60 * 60
 const ONE_DAY = 24 * ONE_HOUR
 const CACHE_ASSETS = {
   edge: {
     maxAgeSeconds: ONE_DAY,
     staleWhileRevalidateSeconds: ONE_HOUR,
   },
   browser: {
     maxAgeSeconds: 0,
     serviceWorkerSeconds: ONE_DAY,
   },
 }
...

Update the /api/ route to use the CACHE_ASSETS constant.

JavaScript./routes.js
...
   .match('/api/:path*', ({ proxy, cache }) => {
     cache(CACHE_ASSETS)
     proxy('origin')
   })
...

We will now add a route that applies the same caching policy to all JavaScript (i.e., .js and .mjs) and CSS files.

JavaScript./routes.js
...
  // Cache stylesheets and scripts, but prevent browser caching
  .match(
    '/:path*/:file.:ext(js|mjs|css)',
    ({ cache, removeUpstreamResponseHeader, proxy, setResponseHeader }) => {
      setResponseHeader('cache-control', 'public, max-age=86400')
      removeUpstreamResponseHeader('set-cookie')
      cache(CACHE_ASSETS)
      proxy('origin')
    }
  )
...

The above route instructs Edgio to perform the following actions for all requests whose file extension matches js, mjs, or css:

Set the cache-control response header to: cache-control: public, max-age=86400
Remove the set-cookie response header. Edgio will not cache a response when the set-cookie response header is present.
Apply the caching policy defined by the CACHE_ASSETS constant.
Proxy these requests to your origin backend when we cannot serve them from cache.

Your routes.[js|ts] should now look similar to the following:

JavaScript./routes.js
import {Router} from '@edgio/core/router';

const ONE_HOUR = 60 * 60;
const ONE_DAY = 24 * ONE_HOUR;
const CACHE_ASSETS = {
  edge: {
    maxAgeSeconds: ONE_DAY,
    staleWhileRevalidateSeconds: ONE_HOUR,
  },
  browser: {
    maxAgeSeconds: 0,
    serviceWorkerSeconds: ONE_DAY,
  },
};

export default new Router()

  // Here is an example where we cache api/* at the edge but prevent caching in the browser
  .match('/api/:path*', ({proxy, cache}) => {
    cache(CACHE_ASSETS);
    proxy('origin');
  })

  // Cache stylesheets and scripts, but prevent browser caching
  .match(
    '/:path*/:file.:ext(js|mjs|css)',
    ({cache, removeUpstreamResponseHeader, proxy, setResponseHeader}) => {
      setResponseHeader('cache-control', 'public, max-age=86400');
      removeUpstreamResponseHeader('set-cookie');
      cache(CACHE_ASSETS);
      proxy('origin');
    }
  )

  // send any unmatched request to origin
  .fallback(({proxy}) => proxy('origin'));

The final line in your routes.[js|ts] defines a fallback() method that proxies all requests that do not match a route to your origin backend.

Testing Locally

You may run Edgio in local development mode to preview your website on your local machine prior to deployment. Local development mode allows for rapid development by allowing you to quickly test changes prior to deployment.

From the command line or terminal, type edgio dev.
Preview your website by loading https://127.0.0.1:3000 from within your preferred web browser.

Deploying Your Property

Evaluate site performance and QA functionality by deploying your property to Edgio. Run the following command from your property’s root directory:

1edgio deploy

Assess performance and caching behavior from the Edgio Developer console. Fine-tune your configuration by adding routes and then redeploying your property. Once you are ready to serve production traffic through Edgio, update your site’s DNS to point to our service.

Learn more.

Examples

Use our sample websites to gain hands-on experience on how to set up Edgio Performance. Specifically, you can browse our sample websites, view their source code, and even experiment on them by deploying them to Edgio.

Simple Example

This example demonstrates a basic Edgio configuration for publicdomainreview.org. It contains two routes that cache content according to their file extension.

Try the Simple Site Example

View the Code

Full-Featured Example

This example demonstrates a full-featured Edgio configuration that showcases the following functionality:

Proxying requests to multiple origins
Increasing the cache buffer during revalidation through StaleWhileRevalidate
Prerendering pages and caching them to improve performance.
Instructing the browser to prefetch and deep fetch cached content to improve performance.

Prefetching only improves performance for cached content. Edgio returns 412 Precondition Failed when prefetching a cache miss. This status code means that the prefetching did not occur for that request.
Transforming and optimizing images
Transforming the response through Serverless Compute
Removing response headers
Normalizing the cache key
Generating performance insights through DevTools
Tracking Core Web Vitals through real user monitoring (RUM).

Try the Full-Featured Site Example

View the Code

Issues?

If you have any issues during this process, check our forums for assistance.