A server-side S3 API for the regular user. lean-s3 tries to provide the 80% of S3 that most people use. It is heavily inspired by Bun's S3 API. Requires a supported Node.js version.
import { S3Client } from "lean-s3";
const client = new S3Client({
// All of these are _required_
// lean-s3 doesn't guess any of these. See below for common values for most providers
endpoint: env.S3_ENDPOINT,
accessKeyId: env.S3_ACCESS_KEY,
secretAccessKey: env.S3_SECRET_KEY,
region: "auto",
bucket: env.S3_BUCKET, // required here, but you can specify a different bucket later
});
const test = client.file("/test.json");
const exists = await test.exists();
console.log("Does it exist?", exists);
if (exists) {
console.log("Seems so. How big is it?");
const stat = await test.stat();
console.log("Object size in bytes:", stat.size);
console.log("Its contents:");
console.log(await test.text()); // If it's JSON: `await test.json()`
// Delete the object:
// await test.delete();
// copy object to a different bucket in a different region
const otherFile = client.file("/new-file.json", {
bucket: "foo-bucket",
region: "bar-region",
});
await otherFile.write(test);
const firstBytesFile = test.slice(0, 100); // lazy-evaluated slicing
const firstBytes = await firstBytesFile.bytes(); // evaluated using HTTP range requests
console.log("First 100 bytes:", firstBytes);
}
console.log("Pre-signing URL for clients:");
const url = test.presign({ method: "PUT" }); // synchronous, no await needed
console.log(url);# choose your PM
npm install lean-s3
yarn add lean-s3
pnpm add lean-s3@aws-sdk/client-s3 is cumbersome to use and doesn't align well with the current web standards. It is focused on providing a great experience when used in conjunction with other AWS services. This comes at the cost of performance and package size:
$ npm i @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
$ du -sh node_modules
21M node_modules
# vs
$ npm i lean-s3
$ du -sh node_modules
1,8M node_moduleslean-s3 is so lean that it is ~1.8MB just to do a couple of HTTP requests 
Due to the scalability, portability and AWS integrations of @aws-sdk/client-s3, pre-signing URLs is async and performs poorly in high-performance scenarios. By taking different trade-offs, lean-s3 can presign URLs much faster. I promise! This is the reason you cannot use lean-s3 in the browser.
lean-s3 is currently about 30x faster than AWS SDK when it comes to pre-signing URLs:
benchmark avg (min … max) p75 / p99
-------------------------------------------- ---------
@aws-sdk/s3-request-presigner 130.73 µs/iter 128.99 µs
(102.27 µs … 938.72 µs) 325.96 µs
(712.00 b … 5.85 mb) 228.48 kb
lean-s3 4.22 µs/iter 4.20 µs
(4.02 µs … 5.96 µs) 4.52 µs
( 3.54 kb … 3.54 kb) 3.54 kb
aws4fetch 52.41 µs/iter 50.71 µs
(36.06 µs … 1.79 ms) 173.15 µs
( 24.00 b … 1.66 mb) 51.60 kb
minio client 16.21 µs/iter 15.13 µs
(13.14 µs … 1.25 ms) 27.08 µs
(192.00 b … 1.43 mb) 16.02 kb
summary
lean-s3
3.84x faster than minio client
12.42x faster than aws4fetch
30.99x faster than @aws-sdk/s3-request-presigner
Don't trust this benchmark and run it yourself. I am just some random internet guy trying to tell you how much better this s3 client is. For PUT operations, it is ~1.5x faster than @aws-sdk/client-s3. We still work on improving these numbers.
See BENCHMARKS.md for more numbers and how to run it yourself. PRs for improving the benchmarks are welcome!
Don't use lean-s3 if you
- need a broader set of S3 operations.
- need a tight integration into the AWS ecosystem.
- need browser support.
- are already using
@aws-sdk/client-s3and don't have any issues with it. - are using Bun. Bun ships with a great built-in S3 API.
We try to keep this library small. If you happen to need something that is not supported, maybe using the AWS SDK is an option for you. If you think that it is something that >80% of users of this library will need at some point, feel free to open an issue.
See DESIGN_DECISIONS.md to read about why this library is the way it is.
- ✅
CreateBucketvia.createBucket - ✅
DeleteBucketvia.deleteBucket - ✅
HeadBucketvia.bucketExists
- ✅
ListObjectsV2via.list/.listIterating - ✅
DeleteObjectsvia.deleteObjects - ✅
DeleteObjectviaS3File.delete - ✅
PutObjectviaS3File.write - ✅
HeadObjectviaS3File.exists/S3File.stat - ✅
ListMultipartUploadsvia.listMultipartUploads - ✅
ListPartsvia.listParts - ✅
UploadPartvia.uploadPart - ✅
CompleteMultipartUploadvia.completeMultipartUpload - ✅
AbortMultipartUploadvia.abortMultipartUpload
const client = new S3Client({
endpoint: "https://fsn1.your-objectstorage.com", // "fsn1" may be different depending on your selected data center
region: "auto",
bucket: "<your-bucket-name>",
accessKeyId: process.env.S3_ACCESS_KEY_ID, // <your-access-key-id>,
secretAccessKey: process.env.S3_SECRET_KEY, // <your-secret-key>,
});const client = new S3Client({
endpoint: "https://<account-id>.r2.cloudflarestorage.com",
region: "auto",
bucket: "<your-bucket-name>",
accessKeyId: process.env.S3_ACCESS_KEY_ID, // <your-access-key-id>,
secretAccessKey: process.env.S3_SECRET_KEY, // <your-secret-key>,
});const client = new S3Client({
// keep {bucket} and {region} placeholders (they are used internally).
endpoint: "https://{bucket}.s3.{region}.amazonaws.com",
region: "<your-region>",
bucket: "<your-bucket-name>",
accessKeyId: process.env.S3_ACCESS_KEY_ID, // <your-access-key-id>,
secretAccessKey: process.env.S3_SECRET_KEY, // <your-secret-key>,
});Popular S3 provider missing? Open an issue or file a PR!