Backpack

Appearance

API reference / @backpack/vite-plugin-lambda

@backpack/vite-plugin-lambda️ 🚀 ​

Inspired by Vite Plugin Node, this package contains a plugin for Vite that enables you to run your lambdas locally in a dev server.

Features ​

  • Runs on Vite, so all the good stuff like Hot Module Replacement (HMR), programmatic API and tons of configuration options, is automatically available.
  • Emulates the AWS API Gateway proxy integration locally:
    • converts every HTTP request into a APIGatewayProxyEvent to invoke your lambda;
    • converts the APIGatewayProxyResult returned by your lambda back into an HTTP response;
  • Easily extendable with custom Express handlers, like serving a Swagger UI based on your OpenAPI spec
  • Allows easy debugging of your REST lambdas

Getting started ​

First, ensure you have set up Nexus as private registry needed to use Backpack.

Then, install the package using npm:

bash
npm install -D @backpack/vite-plugin-lambda

You also need to install vite itself, as well as express as web framework for Node.js:

bash
npm install -D vite express @types/express

Next, set up your vite.config.ts in the root of your project:

typescript
import { defineConfig } from "vite";
import { VitePluginLambda } from "@backpack/vite-plugin-lambda";

export default defineConfig({
  server: {
    // vite server config, for details see https://vitejs.dev/config/#server-host
    port: 3000,
  },
  plugins: [
    VitePluginLambda({
      appPath: "./server.ts",
      /* other options are optional: */
      // exportName: 'app',
      // appName: 'My awesome app',
    }),
  ],
});

Now create a server.ts, and register your lambda handler function(s) using the lambdaHandlers helper function:

typescript
import express from "express";
import { lambdaHandlers } from "@backpack/vite-plugin-lambda";

export const app = express();

app.use(
  lambdaHandlers({
    handlers: {
      // example:
      "/api/v1/persons": {
        get: {
          handler: import("./app/lambdas/get-persons.handler").then(
            (it) => it.handler,
          ),
        },
        post: {
          handler: import("./app/lambdas/add-person.lambda").then(
            (it) => it.handler,
          ),
        },
      },
    },
  }),
);

Run it! 🚀 Just run npx vite to start Vite. You may want to add this as an npm script in your package.json:

json
{
  "scripts": {
    "dev": "vite"
  }
}

Now you can just run npm run dev.

Tip: Vite supports tons of options. For example, to automatically open your browser, you can specify the script as vite --open.

Rendering Swagger UI ​

You can include a Swagger UI based on your OpenAPI specs. You can easily achieve this with swagger-ui-express:

bash
npm install -D swagger-ui-express @types/swagger-ui-express yaml

In server.ts, add the following code:

typescript
import { readFile } from "node:fs/promises";

import swaggerUi from "swagger-ui-express";
import YAML from "yaml";

const swaggerDocument = YAML.parse(file);
const file = await readFile("./path/to/openapi.yaml", "utf8");

export const app = express()
  .get("/", (_, res) => res.redirect("/swagger-ui"))
  .use("/swagger-ui", swaggerUi.serve, swaggerUi.setup(swaggerDocument))
  .use(
    lambdaHandlers({
      /* ... */
    }),
  );

Make sure that ./path/to/openapi.yaml points to your OpenAPI YAML specs.

Loading environment variables ​

You can use @dotenvx/dotenvx to load dotenv files for your environment variables.

This allows you even to load different variables, for example using the Vite mode:

ts
import { config } from "@dotenvx/dotenvx";

// load environment variables
const VITE_MODE = import.meta.env.MODE;

config({
  quiet: true,
  path: [`.env.${VITE_MODE}.local`, `.env.${VITE_MODE}`, ".env.local", ".env"],
  ignore: ["MISSING_ENV_FILE"],
});

Limitations ​

Interfaces ​

Functions ​

AWS utilities ​