Server Adapters

Official Adapters

Idiomatic Remix apps can generally be deployed anywhere because Remix adapts the server’s request/response to the Web Fetch API. It does this through adapters. We maintain a few adapters:

  • @remix-run/architect
  • @remix-run/cloudflare-pages
  • @remix-run/cloudflare-workers
  • @remix-run/express
  • @remix-run/netlify
  • @remix-run/vercel

These adapters are imported into your server’s entry and are not used inside of your Remix app itself.

If you initialized your app with npx create-remix@latest with something other than the built-in Remix App Server, you will note a server/index.js file that imports and uses one of these adapters.

If you’re using the built-in Remix App Server, you don’t interact with this API

Each adapter has the same API. In the future we may have helpers specific to the platform you’re deploying to.

Community Adapters

Creating an Adapter

createRequestHandler

Creates a request handler for your server to serve the app. This is the ultimate entry point of your Remix application.

  1. const {
  2.   createRequestHandler,
  3. } = require("@remix-run/{adapter}");
  4. createRequestHandler({ build, getLoadContext });

Here’s a full example with express:

  1. const {
  2.   createRequestHandler,
  3. } = require("@remix-run/express");
  4. const express = require("express");
  6. const app = express();
  8. // needs to handle all verbs (GET, POST, etc.)
  9. app.all(
  10.   "*",
  11.   createRequestHandler({
  12.     // `remix build` and `remix dev` output files to a build directory, you need
  13.     // to pass that build to the request handler
  14.     build: require("./build"),
  16.     // return anything you want here to be available as `context` in your
  17.     // loaders and actions. This is where you can bridge the gap between Remix
  18.     // and your server
  19.     getLoadContext(req, res) {
  20.       return {};
  21.     },
  22.   })
  23. );

Here’s an example with Architect (AWS):

  1. const {
  2.   createRequestHandler,
  3. } = require("@remix-run/architect");
  4. exports.handler = createRequestHandler({
  5.   build: require("./build"),
  6. });

Here’s an example with Vercel:

  1. const {
  2.   createRequestHandler,
  3. } = require("@remix-run/vercel");
  4. module.exports = createRequestHandler({
  5.   build: require("./build"),
  6. });

Here’s an example with Netlify:

  1. const path = require("path");
  3. const {
  4.   createRequestHandler,
  5. } = require("@remix-run/netlify");
  7. const BUILD_DIR = path.join(process.cwd(), "netlify");
  9. function purgeRequireCache() {
  10.   // purge require cache on requests for "server side HMR" this won't let
  11.   // you have in-memory objects between requests in development,
  12.   // netlify typically does this for you, but we've found it to be hit or
  13.   // miss and some times requires you to refresh the page after it auto reloads
  14.   // or even have to restart your server
  15.   for (const key in require.cache) {
  16.     if (key.startsWith(BUILD_DIR)) {
  17.       delete require.cache[key];
  18.     }
  19.   }
  20. }
  22. exports.handler =
  23.   process.env.NODE_ENV === "production"
  24.     ? createRequestHandler({ build: require("./build") })
  25.     : (event, context) => {
  26.         purgeRequireCache();
  27.         return createRequestHandler({
  28.           build: require("./build"),
  29.         })(event, context);
  30.       };

Here’s an example with the simplified Cloudflare Workers API:

  1. import { createEventHandler } from "@remix-run/cloudflare-workers";
  3. import * as build from "../build";
  5. addEventListener("fetch", createEventHandler({ build }));

Here’s an example with the lower-level Cloudflare Workers API:

  1. import {
  2.   createRequestHandler,
  3.   handleAsset,
  4. } from "@remix-run/cloudflare-workers";
  6. import * as build from "../build";
  8. const handleRequest = createRequestHandler({ build });
  10. const handleEvent = async (event: FetchEvent) => {
  11.   let response = await handleAsset(event, build);
  13.   if (!response) {
  14.     response = await handleRequest(event);
  15.   }
  17.   return response;
  18. };
  20. addEventListener("fetch", (event) => {
  21.   try {
  22.     event.respondWith(handleEvent(event));
  23.   } catch (e: any) {
  24.     if (process.env.NODE_ENV === "development") {
  25.       event.respondWith(
  26.         new Response(e.message || e.toString(), {
  27.           status: 500,
  28.         })
  29.       );
  30.     }
  32.     event.respondWith(
  33.       new Response("Internal Error", { status: 500 })
  34.     );
  35.   }
  36. });