Edgio
Edgio Console

Express

Express is a fast, unopinionated, minimalist web framework for Node.js. The Edgio Sites’s cloud environment makes it easy to run apps without managing Node.js servers.

Prerequisites

Setup requires:

Install the Edgio CLI

If you have not already done so, install the Edgio CLI.
Bash
1npm i -g @edgio/cli@latest

Initialize your project

In the root directory of your project run edgio init:
Bash
1edgio init --edgioVersion latest
This will automatically update your package.json and add all of the required Edgio dependencies and files to your project. These include:
  • The @edgio/core package - Allows you to declare routes and deploy your application on Edgio
  • The @edgio/prefetch package - Allows you to configure a service worker to prefetch and cache pages to improve browsing speed
  • The @edgio/connectors package
  • edgio.config.js - A configuration file for Edgio
  • routes.js - A default routes file that sends all requests to Ember.js.

Configure the routes

The default routes.js file created by edgio init sends all requests to Express server via a fallback route.
JavaScript
1// This file was added by edgio init.
2// You should commit this file to source control.
3import { Router, edgioRoutes } from '@edgio/core'
4

5export default new Router()
6  .use(edgioRoutes)

Running your app locally

Test your app with the Sites on your local machine by running the following command in your project’s root directory:
Bash
1edgio dev
Edgio CLI does not support running Express servers written in TypeScript in development mode. Instead, perform a production build and test your app locally by running the production server.
To run your app in production mode locally, build your app and run the server:
Bash
1edgio build
2edgio run --production

Deploying

Deploy your app to the Sites by running the following command in your project’s root directory:
Bash
1edgio deploy
Your initial CDN-as-code deployment will generate system-defined origin configurations along with those defined within your edgio.config.js. Learn more about system-defined origins.

Overriding the default app location

When you deploy your Express app to the Sites, the Edgio CLI bundles your app as a single javascript file so that it can be run as a Cloud Function. By default, Edgio looks for your app in the following common locations:
  • src/server.ts
  • src/server.js
  • src/app.ts
  • src/app.js
  • src/index.ts
  • src/index.js
  • server.js
  • app.js
  • index.js
If it cannot find one of these files, you can specify the path to the app in edgio.config.js:
JavaScriptedgio.config.js
1const {join} = require('path');
2

3module.exports = {
4  connector: '@edgio/express',
5  express: {
6    appPath: join(process.cwd(), 'path', 'to', 'app.js'),
7  },
8};
The file you specify in appPath should export an instance of an express app using export default or module.exports.

Serving Static Assets

If your express app serves any static assets, you’ll need to add routes to your Edgio router configuration to serve them from the edge. For example, to serve all paths under /assets from dist/client/assets:
JavaScriptroutes.js
1import { Router, edgioRoutes } from '@edgio/core'
2

3export default new Router()
4  // serve all unmatched URLs from express
5  .use(edgioRoutes)
6  // Create serveStatic route for each file in the folder build
7  // dist/client/assets with a cache-control header of 's-maxage=315360000'
8  // and serve them under the /assets route
9  .match('/assets/:path*', ({ cache, serveStatic }) => {
10    serveStatic('dist/client/assets/:path*');
11  })

Adding Additional Files Needed during SSR

If your express app expects to be able to read files from the filesystem at runtime, for example an index.html template, you can ensure they are included in the app bundle that is deployed to Sites’s cloud workers by adding the following to edgio.config.js
JavaScriptedgio.config.js
1module.exports = {
2  connector: '@edgio/express',
3  // Rest of the config
4  // Include index.html in the cloud bundle
5  serverless: {
6    include: ['dist/client/index.html'],
7  },
8};

Transpiling and TypeScript support

Edgio will automatically transpile JavaScript and TypeScript source code for running on Node.js version 14. If you want to control how source files are compiled, you can transpile your app on your own and point your appPath config to the transpiled version of your app’s main entry point.

Bundling Options

By default, Edgio uses ESBuild to transpile and bundle your application code. If you’re having difficulty fitting your app within the limit for cloud bundles, you can try bundling with ncc, which should produce smaller bundles, by adding the following to edgio.config.js:
JavaScriptedgio.config.js
1module.exports = {
2  express: {
3    bundler: '@vercel/ncc',
4  },
5};
Then add ncc to your app’s build dependencies:
Bash
1npm i -D @vercel/ncc@^0.34.0
Or, using yarn:
Bash
1yarn add --dev @vercel/ncc@^0.34.0
NCC produces a tree-shaken, bundle which includes your application code and all of its dependencies in a single file (written to .edgio/lambda/backends/index.js). NFT is also supported:
JavaScriptedgio.config.js
1module.exports = {
2  express: {
3    bundler: '@vercel/nft',
4  },
5};
Then add nft to your app’s build dependencies:
Bash
1npm i -D @vercel/nft@^0.21.0
Or, using yarn:
Bash
1yarn add --dev @vercel/nft@^0.21.0
NFT is similar to NCC, but it produces an exploded directory tree instead of including all of your code in a single file. We recommend trying ncc first.