The @edgio/core package provides a JavaScript API for controlling routing and caching from your code base rather than a CDN web portal. Using this EdgeJS approach allows this vital routing logic to be properly tested, reviewed, and version controlled, just like the rest of your application code.
Using the Router, you can:
Proxy requests to upstream sites
Send redirects from the network edge
Render responses on the server using Next.js, Nuxt.js, Angular, or any other framework that supports server side rendering.
Define routes within the routes.[js|ts] file. This file should export an instance of @edgio/core/router/Router:
JavaScript./routes.js
1const{Router}=require('@edgio/core/router')
2
3module.exports=newRouter()
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.
When Edgio receives a request, it executes each route that matches the request in the order in which they are declared until one sends a response. The following methods return a response:
Multiple routes can therefore be executed for a given request. A common pattern is to add caching with one route and render the response with a later one using middleware. In the following example we cache then render a response with Next.js:
JavaScript
1const{Router}=require('@edgio/core/router')
2const{ nextRoutes }=require('@edgio/next')
3
4// In this example a request to /products/1 will be cached by the first route, then served by the `nextRoutes` middleware
You can inject values from the request or response into headers or cookies as template literals using the ${value} format. For example: setResponseHeader('original-request-path', '${path}') would add an original-request-path response header whose value is the request path.
Value
Embedded value
Description
HTTP method
${method}
The value of the HTTP method used for the request (e.g. GET)
URL
${url}
The complete URL path including any query strings (e.g. /search?query=docs). Protocol, hostname, and port are not included.
Path
${path}
The URL path excluding any query strings (e.g. /search)
Query string
${query:<name>}
The value of the <name> query string or empty if not available.
Request header
${req:<name>}
The value of the <name> request header or empty if not available.
Request cookie
${req:cookie:<name>}
The value of the <name> cookie in cookie request header or empty if not available.
Request named parameter
${req:param:<name>}
The value of the <name> param defined in the route or empty if not available.
Response header
${res:<name>}
The value of the <name> response header or empty if not available.
It is possible to write an unnamed parameter that only consists of a regexp. It works the same the named parameter, except it will be numerically indexed:
If you need to block all search engine bot traffic to specific environments (such as your default or staging environment), the easiest way is to include the x-robots-tag header with the same directives you would otherwise set in a meta tag.
The search engine traffic is automatically blocked on Edgio edge links and permalinks as of Edgio v6.
If you would like to enable indexing on those links, you need to pass { indexPermalink: true } into the Router constructor in routes.js file:
JavaScript
1newRouter({indexPermalink:true})
Otherwise, Edgio will match requests with the host header matching /layer0.link|layer0-perma.link/ and set a response header of x-robots-tag: noindex.
Additionally, you can customize this to block traffic to development or staging websites based on the host header of the request:
This example shows typical usage of @edgio/core, including serving a service worker, next.js routes (vanity and conventional routes), and falling back to a legacy backend.
JavaScript./routes.js
1const{Router}=require('@edgio/core/router')
2
3module.exports=newRouter()
4.get('/service-worker.js',({ serviceWorker })=>{
5// serve the service worker built by webpack
6serviceWorker('dist/service-worker.js')
7})
8.get('/p/:productId',({ cache })=>{
9// cache products for one hour at edge and using the service worker
10cache({
11edge:{
12maxAgeSeconds:60*60,
13staleWhileRevalidateSeconds:60*60,
14},
15browser:{
16maxAgeSeconds:0,
17serviceWorkerSeconds:60*60,
18},
19})
20proxy('origin')
21})
22.fallback(({ proxy })=>{
23// serve all unmatched URLs from the origin backend configured in edgio.config.js
You can use the router’s catch method to return specific content when the request results in an error status (For example, a status code of 537). Using catch, you can also alter the statusCode and response on the edge before issuing a response to the user.
The .catch method allows the edge router to render a response based on the result preceeding routes. So in the example above whenever we receive a 5xx, we respond with customized-error-page.html from the application’s root directory, and change the status code to 502.
Your catch callback is provided a ResponseWriter instance. You can use any ResponseWriter method except proxy inside .catch.
We highly recommend keeping catch routes simple. Serve responses using serveStatic instead of send to minimize the size of the edge bundle.
In addition to sending redirects at the edge within the router configuration, this can also be configured at the environment level within the Edgio Developer console.
Under <Your Environment> → Configuration, click Edit to draft a new configuration. Scroll down to the Redirects section:
Click Add A Redirect to configure the path or host you wish to redirect to:
Note: you will need to activate and redeploy your site for this change to take effect.