Remix

This guide shows you how to deploy a Remix application to Edgio.

Prerequisites

Before proceeding, you will need an Edgio property. Create one now if you do not already have one.

Learn how to create a property.

System Requirements

Install Node.js 16.x

Deploying requires an account on Edgio. Sign up here for free.

Install the Edgio CLI

If you have not already done so, install the Edgio CLI.

Bash
npm i -g @edgio/cli@latest

Create a New Remix App

If you don’t already have a Remix app, create one by running the following:

1npx create-remix@latest

To ensure your Remix app works with Edgio, make the following selections when prompted:

plaintext
? What type of app do you want to create? (Use arrow keys)
❯ Just the basics
  A pre-configured stack ready for production
...
? Where do you want to deploy? Choose Remix App Server if you're unsure; it's easy to change deployment targets.
  Remix App Server
❯ Express Server
  Architect
  Fly.io
  Netlify
  Vercel
  Cloudflare Pages

You can verify your app works by running it locally with:

1npm run dev

Configuring Your Remix App for Edgio

Update the type Property in package.json

In most cases, a Remix app will have "type": "module" in the package.json file. This property should be removed as Edgio does not support it at this time.

JavaScriptpackage.json
{
  "name": "remix-app",
  "version": "0.0.0",
  "description": "A Remix app",
  "main": "index.js",
  "type": "module",
  "scripts": {
    "dev": "remix dev",
    "build": "remix build",
    "start": "remix run"
  },
  ...
}

Initialize Your Project

In the root directory of your project run edgio init:

1edgio init --edgioVersion latest --connector @edgio/express

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/express package - Allows you to run your application using the configured Express server
edgio.config.js - A configuration file for Edgio
routes.js - A default routes file that sends all requests to Remix.

Modify Remix’s Server Configuration

Edgio requires a few changes to your configuration to correctly bundle your app.

If you created a Remix application by following the above steps, you will have already selected the Express server as your deployment target. If you are using an existing Remix application, you will need to update your server.js file with a compatible Express server.

For either scenario, we’ve provided a sample Express server below that you can use to replace the default server.js file in your project.

JavaScriptserver.js
 import * as fs from "node:fs";
 const fs = require("node:fs");

 import { createRequestHandler } from "@remix-run/express";
 const { createRequestHandler } = require("@remix-run/express");
 import { broadcastDevReady, installGlobals } from "@remix-run/node";
 const { broadcastDevReady, installGlobals } = require("@remix-run/node");
 import chokidar from "chokidar";
 const chokidar = require("chokidar");
 import compression from "compression";
 const compression = require("compression");
 import express from "express";
 const express = require("express");
 import morgan from "morgan";
 const morgan = require("morgan");

installGlobals();

const BUILD_PATH = "./build/index.js";
/**
 * @type { import('@remix-run/node').ServerBuild | Promise<import('@remix-run/node').ServerBuild> }
 */
 let build = await import(BUILD_PATH);
 let build = require(BUILD_PATH);

const app = express();

app.use(compression());

// http://expressjs.com/en/advanced/best-practice-security.html#at-a-minimum-disable-x-powered-by-header
app.disable("x-powered-by");

// Remix fingerprints its assets so we can cache forever.
app.use(
  "/build",
  express.static("public/build", { immutable: true, maxAge: "1y" })
);

// Everything else (like favicon.ico) is cached for an hour. You may want to be
// more aggressive with this caching.
app.use(express.static("public", { maxAge: "1h" }));

app.use(morgan("tiny"));

app.all(
  "*",
  process.env.NODE_ENV === "development"
    ? createDevRequestHandler()
    : createRequestHandler({
        build,
        mode: process.env.NODE_ENV,
      })
);

const port = process.env.PORT || 3000;
app.listen(port, async () => {
  console.log(`Express server listening on port ${port}`);

  if (process.env.NODE_ENV === "development") {
    broadcastDevReady(build);
  }
});

function createDevRequestHandler() {
  const watcher = chokidar.watch(BUILD_PATH, { ignoreInitial: true });

  watcher.on("all", async () => {
    // 1. purge require cache && load updated server build
    const stat = fs.statSync(BUILD_PATH);
    build = import(BUILD_PATH + "?t=" + stat.mtimeMs);
    // 2. tell dev server that this app server is now ready
    broadcastDevReady(await build);
  });

  return async (req, res, next) => {
    try {
      //
      return createRequestHandler({
        build: await build,
        mode: "development",
      })(req, res, next);
    } catch (error) {
      next(error);
    }
  };
}

Note that the server.js file is using CommonJS require instead of ES import. This is required for Edgio to correctly bundle your app.

Update the servermoduleformat Property in remix.config.js

Use the CommonJS module format by setting the serverModuleFormat property in the remix.config.js file to cjs.

JavaScriptremix.config.js
/** @type {import('@remix-run/dev').AppConfig} */
 export default {
 module.exports = {
  ignoredRouteFiles: ["**/.*"],
  // appDirectory: "app",
  // assetsBuildDirectory: "public/build",
  // serverBuildPath: "build/index.js",
  // publicPath: "/build/",
  serverModuleFormat: "esm",
  serverModuleFormat: "cjs",
  future: {
    v2_dev: true,
    v2_errorBoundary: true,
    v2_headers: true,
    v2_meta: true,
    v2_normalizeFormMethod: true,
    v2_routeConvention: true,
  },
};

With various changes made to the Remix app configuration, it’s important to ensure that the app still works as expected. Build the app locally using npm run build to verify there are no errors.

Update Edgio Configuration File

Update edgio.config.js serverless property to include the public and build directories:

JavaScriptedgio.config.js
// This file was automatically added by edgio init.
// You should commit this file to source control.
// Learn more about this file at https://docs.edg.io/guides/edgio_config
module.exports = {
  connector: '@edgio/express',

  /* ... */

  // Options for hosting Cloud Functions on Edgio
  serverless: {
    // Set to true to include all packages listed in the dependencies property of package.json when deploying to Edgio.
    // This option generally isn't needed as Edgio automatically includes all modules imported by your code in the bundle that
    // is uploaded during deployment
    // includeNodeModules: false,
  
    // Include additional paths that are dynamically loaded by your app at runtime here when building the serverless bundle.
    include: ['public/**/*', 'build/**/*'],
  },

  /* ... */
}

Configure the Caching Policy

Update the routes.[js|ts] to add a caching policy for your app’s SSR pages and static assets:

JavaScriptroutes.js
/// This file was automatically added by edgio init.
// You should commit this file to source control.
import { Router } from '@edgio/core'

export default new Router()
  .match('/:path*', {
    caching: {
      max_age: '1d',
      stale_while_revalidate: '1d',
      service_worker_max_age: '1h',
    },

    origin: {
      set_origin: 'edgio_serverless',
    },
  })
  .static('public')

Refer to the CDN-as-code guide for the full syntax of the routes.js file and how to configure it for your use case.

Run the Remix App Locally on Edgio

Create a development build of your app by running the following in your project’s root directory:

Bash
# start the Edgio dev server
edgio dev

Load the site http://127.0.0.1:3000

Deploying

Create a production build of your app by running the following in your project’s root directory:

Bash
# build your app for production
npm run build

Deploy your app to the Sites by running the following command in your project’s root directory:

Bash
# deploy the Edgio production bundle
edgio 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.

Refer to the Deployments guide for more information on the deploy command and its options.