# remix-aws

> AWS adapter for Remix

Latest version **1.2.2** (published 2024-10-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install remix-aws
pnpm add remix-aws
yarn add remix-aws
bun add remix-aws
```

## Health

**Score 35/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.2 |
| Published | 2024-10-10 |
| First published | 2022-07-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 1 |
| Unpacked size | 83.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 26 |
| Maintainers | wingleung |

## Links

- npm: https://www.npmjs.com/package/remix-aws
- Repository: https://github.com/wingleung/remix-aws
- Homepage: https://github.com/wingleung/remix-aws#readme
- Issues: https://github.com/wingleung/remix-aws/issues
- npm.io page: https://npm.io/package/remix-aws

## Dependencies (1)

- [@types/aws-lambda](https://npm.io/package/@types/aws-lambda.md) ^8.10.125

## Recent versions

- 1.2.2 (latest) — 2024-10-10
- 1.3.0-beta.1 (beta) — 2024-10-15
- 1.0.0-0 (rc) — 2023-10-27
- 1.2.0-beta.4 — 2024-10-10
- 1.2.0-beta.3 — 2024-10-09
- 1.2.0-beta.2 — 2024-10-05
- 1.1.0 — 2024-04-20
- 1.0.0 — 2023-10-27
- 0.0.3 — 2023-10-24
- 0.0.2-rc.2 — 2022-07-26
- 0.0.2-rc.1 — 2022-07-16
- 0.0.2-rc.0 — 2022-07-16

## README

<div align="center">
  <h1>Remix AWS</h1>
  <p align="left">
    <a href="https://www.npmjs.com/package/remix-aws?activeTab=versions">
      <img src="https://badge.fury.io/js/remix-aws.svg" alt="npm version" style="max-width:100%;">
    </a>
    <a href="https://packagephobia.com/result?p=remix-aws">
      <img src="https://packagephobia.com/badge?p=remix-aws" alt="npm install size" style="max-width:100%;">
    </a>
    <a href="https://snyk.io/test/github/wingleung/remix-aws">
      <img src="https://snyk.io/test/github/wingleung/remix-aws/badge.svg" alt="Known Vulnerabilities" data-canonical-src="https://snyk.io/test/github/wingleung/remix-aws" style="max-width:100%;">
    </a>
  </p>
  <img alt="Remix logo" src="https://raw.githubusercontent.com/wingleung/remix-aws/main/docs/img/remix-logo.png"/>
  <p><strong>AWS adapters for Remix</strong></p>
</div>

## 🚀 support

- API gateway v1
- API gateway v2
- Application load balancer

## Getting started

```shell
npm install --save remix-aws
```

```javascript
// 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](https://docs.aws.amazon.com/lambda/latest/dg/lambda-nodejs.html#designate-es-module)

```typescript
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](./templates/server.js)**

```typescript
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

```json
// 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](https://esbuild.github.io/api/#build-options) for more information

## Notes

### split from @remix/architect

As mentioned in [#3173](https://github.com/remix-run/remix/pull/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](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/aws-lambda/trigger/alb.d.ts#L29-L48)
vs [API gateway v1 types](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/aws-lambda/trigger/api-gateway-proxy.d.ts#L116-L145)

---
_Source: https://npm.io/package/remix-aws · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._