@20minutes/serverless-s3-local

Forked version to use our own fork of s3rver (and removed Docker).

For the official readme, check the official project.

Requirements

• Node.js >= 24
• Serverless Framework v3 or osls v3
• serverless-offline when using S3 events with offline lambdas

Installation

yarn add -D @20minutes/serverless-s3-local serverless-offline

Configuration

service: my-service

provider:
  name: aws
  runtime: nodejs24.x

plugins:
  - '@20minutes/serverless-s3-local'
  - serverless-offline

custom:
  s3:
    host: localhost
    port: 8000
    directory: ./.s3-local

resources:
  Resources:
    LocalBucket:
      Type: AWS::S3::Bucket
      Properties:
        BucketName: local-bucket

functions:
  onUpload:
    handler: handler.onUpload
    events:
      - s3:
          bucket: local-bucket
          event: s3:ObjectCreated:Put
          rules:
            - prefix: incoming/
            - suffix: .txt

Commands

serverless s3 start
serverless s3 create
serverless s3 remove
serverless offline start

Options

Common custom.s3 options:

| Option | Description | Default | | --- | --- | --- | | host | S3 endpoint host used by SDK clients | localhost | | address | Bind address used by S3rver | localhost | | port | S3 endpoint port | 4569 | | directory | Local object storage directory | ./buckets | | buckets | Extra buckets to create | none | | noStart | Create/remove buckets against already running local S3 | false | | accessKeyId | Local credentials access key | S3RVER | | secretAccessKey | Local credentials secret key | S3RVER | | region | SDK region | us-east-1 | | cors | Path to CORS XML config | none | | website | Path to website XML config | none | | allowMismatchedSignatures | Pass-through S3rver option | false | | serviceEndpoint | Pass-through S3rver option | none | | httpsProtocol | Directory containing cert.pem and key.pem | none | | vhostBuckets | Pass-through S3rver option | true |

SDK Client

const { S3Client } = require('@aws-sdk/client-s3')

const s3 = new S3Client({
  forcePathStyle: true,
  endpoint: 'http://localhost:8000',
  region: 'us-east-1',
  credentials: {
    accessKeyId: 'S3RVER',
    secretAccessKey: 'S3RVER',
  },
})

Development

yarn install
yarn lint
yarn test

Examples

Two examples are kept as runnable documentation:

• examples/simple-put
• examples/s3-event-prefix-suffix