{"id":48620,"library":"multer-s3","title":"Multer S3","description":"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.","status":"active","version":"3.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/badunk/multer-s3","tags":["javascript","multer","s3","amazon","aws"],"install":[{"cmd":"npm install multer-s3","lang":"bash","label":"npm"},{"cmd":"yarn add multer-s3","lang":"bash","label":"yarn"},{"cmd":"pnpm add multer-s3","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for S3 client instantiation","package":"@aws-sdk/client-s3","optional":false},{"reason":"Used internally for upload functionality","package":"@aws-sdk/lib-storage","optional":false}],"imports":[{"note":"Default import is common; require works in CJS environments but TypeScript may require esModuleInterop.","wrong":"const multerS3 = require('multer-s3')","symbol":"multerS3","correct":"import multerS3 from 'multer-s3'"},{"note":"Use named import for the client class. CJS require is also valid but less idiomatic.","wrong":"const S3Client = require('@aws-sdk/client-s3').S3Client","symbol":"S3Client","correct":"import { S3Client } from '@aws-sdk/client-s3'"},{"note":"Multer is a default export; CJS require works in Node but may cause type issues.","wrong":"const multer = require('multer')","symbol":"Multer","correct":"import multer from 'multer'"}],"quickstart":{"code":"import express from 'express';\nimport multer from 'multer';\nimport multerS3 from 'multer-s3';\nimport { S3Client } from '@aws-sdk/client-s3';\n\nconst app = express();\nconst s3 = new S3Client({ region: 'us-east-1', credentials: { accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '', secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? '' } });\n\nconst upload = multer({\n  storage: multerS3({\n    s3: s3,\n    bucket: process.env.S3_BUCKET ?? 'my-bucket',\n    acl: 'public-read',\n    key: (req, file, cb) => cb(null, Date.now().toString())\n  })\n});\n\napp.post('/upload', upload.single('file'), (req, res) => {\n  res.json({ url: req.file.location });\n});\n\napp.listen(3000, () => console.log('Server on port 3000'));","lang":"javascript","description":"Set up an Express server with Multer and multer-s3 to upload a single file to S3, returning the file URL."},"warnings":[{"fix":"Update your AWS SDK to v3 and pass an S3Client (from @aws-sdk/client-s3) to the multerS3 constructor.","message":"v3 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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Always ensure you call `cb(null, key)` inside the key function. For async, use async/await and then call cb.","message":"The `key` function must call the callback; otherwise files will not be uploaded and no error is thrown.","severity":"gotcha","affected_versions":"*"},{"fix":"Use multer's middleware (e.g., `upload.single('file')`) and access `req.file` in the next handler.","message":"File metadata (like `location`, `etag`) is only available after the upload completes; accessing `req.file` before the upload hook may give undefined.","severity":"gotcha","affected_versions":"*"},{"fix":"Remove stream options if upgrading from v2; the new SDK manages concurrency internally.","message":"The 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.","severity":"deprecated","affected_versions":">=3.0.0"}],"env_vars":null,"search_vec":"'/client-s3':24 '/lib-storage':29 '2':31 '3.0.1':14 'acl':66 'amazon':89 'avoid':55 'aw':8,17,22,27,35,90 'aws-sdk':21,26 'bucket':63 'buffer':56 'cadenc':78 'communiti':84 'community-driven':83 'configur':62 'current':10 'driven':85 'engin':6,48 'etag':75 'etc':76 'expos':69 'file':53,71 'filesystem':59 'generat':65 'info':72 'integr':44 'intermitt':80 'javascript':86 'key':64 'line':33 'locat':74 'mainten':81 'metadata':67 'method':41 'multer':1,4,45,87 'packag':43 'releas':77 'rich':70 's3':2,9,50,88 's3.upload':40 'sdk':18,23,28,36 'size':73 'specif':20 'stabl':11 'storag':5,47 'stream':3,52 'support':61 'upload':54 'use':16,34 'v2':37 'v3':19 'version':12 'x':32","created_at":"2026-06-07T16:57:34.510732+00:00","updated_at":"2026-06-07T16:57:34.510732+00:00","problems":[{"fix":"Use `file.location` for the S3 URL, `file.key` for the object key, and other multer-s3 specific fields.","cause":"The `file.path` property does not exist when using multer-s3; files are not stored on disk.","error":"TypeError: Cannot read properties of undefined (reading 'path')"},{"fix":"Use `import { S3Client } from '@aws-sdk/client-s3'` and instantiate a new S3Client.","cause":"You passed an AWS SDK v2 S3 object to the `s3` option in v3 of multer-s3.","error":"Error: The provided `s3` option is not a valid S3Client."},{"fix":"Use `const multerS3 = require('multer-s3').default;` or use ES module import.","cause":"CommonJS require with 'require(\"multer-s3\")' may return an object with a default property.","error":"TypeError: multerS3 is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/badunk/multer-s3#readme","github":"https://github.com/badunk/multer-s3","docs":null,"changelog":null,"pypi":null,"npm":"multer-s3","openapi_spec":null,"status_page":null,"smithery":null,"categories":["storage"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}