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
muslnode 18–226 runs
build_error
glibcnode 18–226 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.fixFor 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.fixConfigure 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.fixEnsure 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`.fixAdd 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.fixInitialize 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.
fixFor 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.
fixEnsure 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.
fixAdd 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.
fixRun 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.
Audit
Dependencies
No dependency data recorded yet.