A node utility for serving files from S3. Compatible with Express, Fastify, NestJs, and more.

Small & flexible. You decide what and how to send and receive.

npm install s3-serve --save

This library has a peer dependency on @aws-sdk/client-s3, if not already installed, use the following:

npm install @aws-sdk/client-s3 --save

Minimal express example:

import express from 'express';
import { S3Client } from '@aws-sdk/client-s3';
import { s3Get } from 's3-serve';

const client = new S3Client(...);
const app = express();

app.get('/:file', async (req, res) => {
  const { headers, body } = await s3Get(client, {
    Bucket: 'my-bucket',
    Key: req.params.file
  });
  res.set(headers);
  body.pipe(res);
})

More elaborate example at the end!

This library aims to be flexible by giving the developer full control over the inputs and outputs of each request, while also reducing the amount of boilerplate required when working with @aws-sdk/s3-client.

s3Get(client: S3 Client, options: GetObjectCommandInput): Promise<S3Response>

Executes a GetObjectCommand using the given client. Returns an S3Response which contains all information needed to serve the file.

Note: s3Get does neither cache nor store anything in memory, the requested file in S3Response.body is a Readable stream that can be piped as a response.

extractGetArgs(headers: object): object

Extracts and converts relevant headers from a request, so they can be fed into s3Get's GetObjectCommandInput.

Implement express.static but from s3 and with custom cache headers:

import { s3Get, extractGetArgs } from 's3-serve';

app.get('/:key(*)', async (req, res) => {
  const response = await s3Get(client, {
    Bucket,
    Key: req.params.key || 'index.html',
    ...extractGetArgs(req.headers),
  });

  if (response.error) {
    const { error, metadata, statusCode, statusMessage } = response;
    console.error(`Error ${statusCode} getting ${Key}`, error, metadata);
    res.status(statusCode).send(statusMessage);
    return;
  }
  const { statusCode, headers, body } = response;
  res.status(statusCode).set(headers);

  if (/\.(jpg|png|gif)$/.test(Key)) {
    res.set('cache-control', 'max-age=3600');
  }

  body.pipe(res);
});