{"id":11974,"library":"s3rver","title":"S3rver: Local S3 Mock Server","description":"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.","status":"active","version":"3.7.1","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/jamhall/s3rver","tags":["javascript","fake","s3","server","mock","false","amazon"],"install":[{"cmd":"npm install s3rver","lang":"bash","label":"npm"},{"cmd":"yarn add s3rver","lang":"bash","label":"yarn"},{"cmd":"pnpm add s3rver","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The S3rver class is typically exposed as the default export for ESM.","wrong":"import { S3rver } from 's3rver';","symbol":"S3rver","correct":"import S3rver from 's3rver';"},{"note":"For CommonJS environments, the S3rver class is directly exported as the module.","symbol":"S3rver (CommonJS)","correct":"const S3rver = require('s3rver');"}],"quickstart":{"code":"import S3rver from 's3rver';\nimport { S3Client, CreateBucketCommand, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, DeleteBucketCommand } from '@aws-sdk/client-s3';\nimport { mkdtemp, rm } from 'node:fs/promises';\nimport { tmpdir } from 'node:os';\nimport { join } from 'node:path';\n\nasync function runS3rverExample() {\n  const port = 4569;\n  const tempDir = await mkdtemp(join(tmpdir(), 's3rver-example-'));\n  const bucketName = 'my-test-bucket';\n  const objectKey = 'hello.txt';\n  const content = 'Hello from S3rver!';\n\n  console.log(`Using temporary directory: ${tempDir}`);\n\n  // Initialize S3rver instance\n  const s3rver = new S3rver({\n    port: port,\n    directory: tempDir,\n    silent: true, // Suppress S3rver logs for cleaner output\n  });\n\n  // Start the S3rver\n  await s3rver.run();\n  console.log(`S3rver running on http://localhost:${port}`);\n\n  // Configure AWS SDK client to connect to S3rver\n  const client = new S3Client({\n    region: 'us-east-1', // S3rver does not enforce specific regions\n    endpoint: `http://localhost:${port}`,\n    credentials: {\n      accessKeyId: 'S3RVER', // S3rver's default credentials\n      secretAccessKey: 'S3RVER' // S3rver's default credentials\n    },\n    forcePathStyle: true // Required for S3rver\n  });\n\n  try {\n    // 1. Create a bucket\n    await client.send(new CreateBucketCommand({ Bucket: bucketName }));\n    console.log(`Bucket \"${bucketName}\" created.`);\n\n    // 2. Upload an object\n    await client.send(new PutObjectCommand({\n      Bucket: bucketName,\n      Key: objectKey,\n      Body: content,\n      ContentType: 'text/plain'\n    }));\n    console.log(`Object \"${objectKey}\" uploaded.`);\n\n    // 3. Download the object\n    const { Body } = await client.send(new GetObjectCommand({\n      Bucket: bucketName,\n      Key: objectKey\n    }));\n    const downloadedContent = await Body?.transformToString();\n    console.log(`Downloaded object content: \"${downloadedContent}\"`);\n\n    // Verify content\n    if (downloadedContent === content) {\n      console.log('Content verification successful.');\n    } else {\n      console.warn('Downloaded content mismatch!');\n    }\n\n  } catch (error) {\n    console.error('S3 operation failed:', error);\n  } finally {\n    // Clean up: Delete object and bucket\n    try {\n        await client.send(new DeleteObjectCommand({ Bucket: bucketName, Key: objectKey }));\n        await client.send(new DeleteBucketCommand({ Bucket: bucketName }));\n        console.log('Cleaned up bucket and object.');\n    } catch (cleanupError) {\n        console.warn('Error during cleanup:', cleanupError);\n    }\n\n    // Stop the server\n    await s3rver.close();\n    console.log('S3rver stopped.');\n\n    // Remove temporary directory\n    await rm(tempDir, { recursive: true, force: true });\n    console.log(`Removed temporary directory: ${tempDir}`);\n  }\n}\n\nrunS3rverExample().catch(console.error);\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Configure your AWS client with `accessKeyId: \"S3RVER\"` and `secretAccessKey: \"S3RVER\"`.","message":"Clients making signed S3 requests (e.g., AWS SDK clients, `aws cli`) must be configured with S3rver's specific dummy credentials for successful authentication.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"S3rver 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.","severity":"breaking","affected_versions":"<3.6.0 || >=16.0.0"},{"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.","message":"If 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`.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Initialize S3rver with the `allowMismatchedSignatures: true` option to bypass signature validation. Example: `new S3rver({ ..., allowMismatchedSignatures: true })`.","message":"S3rver 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.","severity":"gotcha","affected_versions":">=3.2.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For Node.js AWS SDK clients, configure the client with `httpOptions: { agent: new https.Agent({ rejectUnauthorized: false }) }`.","cause":"Attempting to connect to S3rver over HTTPS with a self-signed certificate without configuring the client to trust it.","error":"Error: self-signed certificate in certificate chain"},{"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.","cause":"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.","error":"SignatureDoesNotMatch"},{"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`.","cause":"Attempting to access a bucket using vhost-style addressing (e.g., `my-test-bucket.localhost:4568`) without the hostname being resolved locally.","error":"getaddrinfo ENOTFOUND my-test-bucket.localhost"},{"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.","cause":"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.","error":"Error: ERR_OSSL_EVP_UNSUPPORTED"}],"ecosystem":"npm"}