Remix AWS

AWS adapters for Remix

🚀 support

• API gateway v1
• API gateway v2
• Application load balancer

Getting started

npm install --save remix-aws

// server.js
import * as build from '@remix-run/dev/server-build'
import {AWSProxy, createRequestHandler} from 'remix-aws'

// Required in Remix v2
import { installGlobals } from '@remix-run/node'
installGlobals()

export const handler = createRequestHandler({
    build,
    mode: process.env.NODE_ENV,
    awsProxy: AWSProxy.APIGatewayV2
})

awsProxy

By default the awsProxy is set to AWSProxy.APIGatewayV2.

Options

• AWSProxy.APIGatewayV1
• AWSProxy.APIGatewayV2
• AWSProxy.ALB
• AWSProxy.FunctionURL

Vite preset

If you use Vite, then the awsPreset preset is an easy way to configure aws support. It will do a post remix build and create a handler function for use in aws lambda.

There is no need for a separate server.js file. The preset will take care of that. However, if you want to manage your own server.js file, you can pas a custom entryPoint to your own server.js.

⚠️ By default Remix will set serverModuleFormat to esm. The Vite preset will automatically align the serverModuleFormat with the esbuild configuration used by the preset. However, to ensure that AWS lambda correctly interprets the output file as an ES module, you need to take additional steps.

There are two primary methods to achieve this:

• Specify the module type in package.json: Add "type": "module" to your package.json file and ensure that this file is included in the deployment package sent to AWS Lambda.

• Use the .mjs extension: Alternatively, you can change the file extension to .mjs. For example, you can configure the Remix serverBuildFile setting to output index.mjs.

more info: AWS docs on ES module support in AWS lambdas

import type { PluginOption } from 'vite'
import type { Preset } from '@remix-run/dev'

import { vitePlugin as remix } from '@remix-run/dev'
import { awsPreset, AWSProxy } from 'remix-aws'
import { defineConfig } from 'vite'

export default defineConfig(
  {
    ...
      plugins: [
  remix({
    // serverBuildFile: 'index.mjs', // set the extension to .mjs or ship you package.json along with the build package
    presets: [
      awsPreset({
        awsProxy: AWSProxy.APIGatewayV2,

        // additional esbuild configuration
        build: {
          minify: true,
          treeShaking: true,
          ...
        }
      }) as Preset
    ]
  }) as PluginOption,
]
}
)

Example server.js

import { AWSProxy, createRequestHandler } from 'remix-aws'

let build = require('./build/server/index.js')

export const handler = createRequestHandler({
  build,
  mode: process.env.NODE_ENV,
  awsProxy: AWSProxy.APIGatewayV1
})

configuration

awsProxy is optional and defaults to AWSProxy.APIGatewayV2

build is for additional esbuild configuration for the post remix build

// default esbuild configuration
{
  logLevel: 'info',
  entryPoints: [
    'build/server.js'
  ],
  bundle: true,
  sourcemap: false,
  platform: 'node',
  outfile: 'build/server/index.js', // will replace remix server build file
  allowOverwrite: true,
  write: true,
}

check esbuild options for more information

Notes

split from @remix/architect

As mentioned in #3173 the goal would be to provide an AWS adapter for the community by the community. In doing so the focus will be on AWS integrations and less on Architect. I do think it's added value to provide examples for Architect, AWS SAM, AWS CDK, Serverless,...

info: ALB types vs API gateway v1 types