Registry / aws / s3rver

s3rver

JSON →
library3.7.1jsnpmunverified

S3rver is a lightweight, in-memory or file-system-backed server that emulates a significant subset of the Amazon S3 API, designed primarily for local development and testing environments. It allows developers to test S3 interactions without incurring costs or relying on external network requests. The current stable version is `3.7.1`, with development being active and releases addressing bug fixes, performance improvements, and expanding S3 API compatibility. Key differentiators include its focus on being a development-only tool, minimal runtime dependencies, support for programmatic integration into test suites, and simulation of S3's static website hosting capabilities, including website routing rules. It supports common S3 operations like bucket creation/deletion, object CRUD, object tagging, and basic object lifecycle features.

npm install s3rver
INSTALL
IMPORT
SIG · S3RVER
S
s3rver
awsjavascriptv3.7.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

S3rver
import S3rver from 's3rver';
import { S3rver } from 's3rver';
The S3rver class is typically exposed as the default export for ESM.
S3rver (CommonJS)
const S3rver = require('s3rver');
For CommonJS environments, the S3rver class is directly exported as the module.

This quickstart demonstrates how to programmatically start and stop an S3rver instance, create a temporary directory for storage, and interact with it using the AWS SDK for JavaScript v3 to create a bucket, upload an object, and retrieve it.

import S3rver from 's3rver'; import { S3Client, CreateBucketCommand, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, DeleteBucketCommand } from '@aws-sdk/client-s3'; import { mkdtemp, rm } from 'node:fs/promises'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; async function runS3rverExample() { const port = 4569; const tempDir = await mkdtemp(join(tmpdir(), 's3rver-example-')); const bucketName = 'my-test-bucket'; const objectKey = 'hello.txt'; const content = 'Hello from S3rver!'; console.log(`Using temporary directory: ${tempDir}`); // Initialize S3rver instance const s3rver = new S3rver({ port: port, directory: tempDir, silent: true, // Suppress S3rver logs for cleaner output }); // Start the S3rver await s3rver.run(); console.log(`S3rver running on http://localhost:${port}`); // Configure AWS SDK client to connect to S3rver const client = new S3Client({ region: 'us-east-1', // S3rver does not enforce specific regions endpoint: `http://localhost:${port}`, credentials: { accessKeyId: 'S3RVER', // S3rver's default credentials secretAccessKey: 'S3RVER' // S3rver's default credentials }, forcePathStyle: true // Required for S3rver }); try { // 1. Create a bucket await client.send(new CreateBucketCommand({ Bucket: bucketName })); console.log(`Bucket "${bucketName}" created.`); // 2. Upload an object await client.send(new PutObjectCommand({ Bucket: bucketName, Key: objectKey, Body: content, ContentType: 'text/plain' })); console.log(`Object "${objectKey}" uploaded.`); // 3. Download the object const { Body } = await client.send(new GetObjectCommand({ Bucket: bucketName, Key: objectKey })); const downloadedContent = await Body?.transformToString(); console.log(`Downloaded object content: "${downloadedContent}"`); // Verify content if (downloadedContent === content) { console.log('Content verification successful.'); } else { console.warn('Downloaded content mismatch!'); } } catch (error) { console.error('S3 operation failed:', error); } finally { // Clean up: Delete object and bucket try { await client.send(new DeleteObjectCommand({ Bucket: bucketName, Key: objectKey })); await client.send(new DeleteBucketCommand({ Bucket: bucketName })); console.log('Cleaned up bucket and object.'); } catch (cleanupError) { console.warn('Error during cleanup:', cleanupError); } // Stop the server await s3rver.close(); console.log('S3rver stopped.'); // Remove temporary directory await rm(tempDir, { recursive: true, force: true }); console.log(`Removed temporary directory: ${tempDir}`); } } runS3rverExample().catch(console.error);
s3rver --version
Debug
Known issues
gotchaWhen using S3rver with HTTPS and a self-signed certificate, Node.js clients (like the AWS SDK) will reject the unauthorized certificate by default. You must configure the client to explicitly allow unauthorized certificates.
fix
For AWS SDK v3, use `httpOptions: { agent: new https.Agent({ rejectUnauthorized: false }) }` in your client configuration. For older SDKs, a similar `rejectUnauthorized` option is usually available.
affects: >=3.0.0
gotchaClients making signed S3 requests (e.g., AWS SDK clients, `aws cli`) must be configured with S3rver's specific dummy credentials for successful authentication.
fix
Configure your AWS client with `accessKeyId: "S3RVER"` and `secretAccessKey: "S3RVER"`.
affects: >=3.0.0
breakingS3rver officially supports Node.js 12 and 14 since v3.6.0. While it might run on other versions, older Node.js versions may not be fully compatible or officially tested, and newer Node.js versions (e.g., Node.js 17+) might require specific workarounds for crypto modules or have other incompatibilities.
fix
Ensure you are running S3rver on a officially supported Node.js LTS version (currently Node.js 12, 14, 16, 18, 20 are generally safe with latest S3rver versions) or test thoroughly on other versions. For Node.js 17+, you might need to set `NODE_OPTIONS=--openssl-legacy-provider` for some dependent modules, though this is a workaround and not recommended for production.
affects: <3.6.0 || >=16.0.0
gotchaIf using S3rver's static website hosting with vhost-style bucket access (e.g., `mysite.local:4568`), you need to configure your operating system's hosts file to resolve the custom domain to `127.0.0.1`.
fix
Add an entry like `127.0.0.1 mysite.local` to your `/etc/hosts` (Linux/macOS) or `C:\Windows\System32\drivers\etc\hosts` (Windows) file.
affects: >=3.0.0
gotchaS3rver performs strict signature verification by default. If your client is generating signatures in a non-standard way or you encounter `SignatureDoesNotMatch` errors frequently, you may need to disable signature matching for testing purposes.
fix
Initialize S3rver with the `allowMismatchedSignatures: true` option to bypass signature validation. Example: `new S3rver({ ..., allowMismatchedSignatures: true })`.
affects: >=3.2.0
Errors
Common errors & fixes
Error: self-signed certificate in certificate chain
Attempting to connect to S3rver over HTTPS with a self-signed certificate without configuring the client to trust it.
fix
For Node.js AWS SDK clients, configure the client with `httpOptions: { agent: new https.Agent({ rejectUnauthorized: false }) }`.
SignatureDoesNotMatch
The AWS SDK client is attempting to sign requests with default or incorrect AWS credentials that do not match S3rver's expected credentials, or signature validation is failing for other reasons.
fix
Ensure the AWS SDK client is configured with `accessKeyId: "S3RVER"` and `secretAccessKey: "S3RVER"`. If problems persist, consider `allowMismatchedSignatures: true` in S3rver configuration for testing.
getaddrinfo ENOTFOUND my-test-bucket.localhost
Attempting to access a bucket using vhost-style addressing (e.g., `my-test-bucket.localhost:4568`) without the hostname being resolved locally.
fix
Add an entry like `127.0.0.1 my-test-bucket.localhost` to your operating system's hosts file (`/etc/hosts` or `C:\Windows\System32\drivers\etc\hosts`). Alternatively, configure the AWS SDK client to use path-style addressing with `forcePathStyle: true`.
Error: ERR_OSSL_EVP_UNSUPPORTED
Running S3rver (or its dependencies) on Node.js 17+ with OpenSSL 3.0, which has deprecated older hashing algorithms that some internal dependencies might use.
fix
Run Node.js with `NODE_OPTIONS=--openssl-legacy-provider`. This is a temporary workaround. For long-term, ensure all dependencies are compatible with OpenSSL 3.0 or use a Node.js LTS version prior to Node.js 17.
Upgrade
Version history
3.7.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
18 hits · last 30 days
node
14
Amazon
1
OpenAI (training)
1
Resources
s3rver — npm install s3rver · libregistry