multer-s3

library3.0.1jsnpmunverified

Streaming multer storage engine for AWS S3. Current stable version is 3.0.1, which uses AWS SDK v3 (specifically @aws-sdk/client-s3 and @aws-sdk/lib-storage). The 2.x line used AWS SDK v2 and the s3.upload method. This package integrates Multer's storage engine with S3 for streaming file uploads, avoiding buffering to the filesystem. It supports configurable bucket, key generation, ACL, metadata, and exposes rich file info (size, location, etag, etc.). Release cadence is intermittent; maintenance is community-driven.

storage

npm install multer-s3

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MULTER-S3

multer-s3

storagejavascriptv3.0.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

multerS3

✓ import multerS3 from 'multer-s3'

✗ const multerS3 = require('multer-s3')

Default import is common; require works in CJS environments but TypeScript may require esModuleInterop.

S3Client

✓ import { S3Client } from '@aws-sdk/client-s3'

✗ const S3Client = require('@aws-sdk/client-s3').S3Client

Use named import for the client class. CJS require is also valid but less idiomatic.

Multer

✓ import multer from 'multer'

✗ const multer = require('multer')

Multer is a default export; CJS require works in Node but may cause type issues.

Set up an Express server with Multer and multer-s3 to upload a single file to S3, returning the file URL.

import express from 'express'; import multer from 'multer'; import multerS3 from 'multer-s3'; import { S3Client } from '@aws-sdk/client-s3'; const app = express(); const s3 = new S3Client({ region: 'us-east-1', credentials: { accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '', secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? '' } }); const upload = multer({ storage: multerS3({ s3: s3, bucket: process.env.S3_BUCKET ?? 'my-bucket', acl: 'public-read', key: (req, file, cb) => cb(null, Date.now().toString()) }) }); app.post('/upload', upload.single('file'), (req, res) => { res.json({ url: req.file.location }); }); app.listen(3000, () => console.log('Server on port 3000'));

Debug

Known issues

breakingv3 requires AWS SDK v3 (@aws-sdk/client-s3) instead of v2 (aws-sdk). The s3 option must be an S3Client instance, not an S3 object.

fix

Update your AWS SDK to v3 and pass an S3Client (from @aws-sdk/client-s3) to the multerS3 constructor.

affects: >=3.0.0

gotchaThe `key` function must call the callback; otherwise files will not be uploaded and no error is thrown.

fix

Always ensure you call `cb(null, key)` inside the key function. For async, use async/await and then call cb.

affects: *

gotchaFile metadata (like `location`, `etag`) is only available after the upload completes; accessing `req.file` before the upload hook may give undefined.

fix

Use multer's middleware (e.g., `upload.single('file')`) and access `req.file` in the next handler.

affects: *

deprecatedThe 2.x stream configuration options (e.g., partSize, queueSize) are not supported in v3; v3 uses @aws-sdk/lib-storage's Upload which may behave differently.

fix

Remove stream options if upgrading from v2; the new SDK manages concurrency internally.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'path')

The `file.path` property does not exist when using multer-s3; files are not stored on disk.

fix

Use `file.location` for the S3 URL, `file.key` for the object key, and other multer-s3 specific fields.

Error: The provided `s3` option is not a valid S3Client.

You passed an AWS SDK v2 S3 object to the `s3` option in v3 of multer-s3.

fix

Use `import { S3Client } from '@aws-sdk/client-s3'` and instantiate a new S3Client.

TypeError: multerS3 is not a function

CommonJS require with 'require("multer-s3")' may return an object with a default property.

fix

Use `const multerS3 = require('multer-s3').default;` or use ES module import.

Upgrade

Version history

3.0.1latest on npm

Audit

Dependencies

@aws-sdk/client-s3requiredPeer dependency for S3 client instantiation

@aws-sdk/lib-storagerequiredUsed internally for upload functionality

Agent activity

29 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/badunk/multer-s3 ↗

packagemulter-s3 ↗

homepagehttps://github.com/badunk/multer-s3#readme ↗