s3mini: a small TypeScript client for S3-compatible storage

s3mini's place in S3-compatible applications

s3mini addresses the need for direct object-storage access without adopting a broad AWS SDK. It is aimed at developers building TypeScript services on Node.js or Bun, as well as code deployed to Cloudflare Workers and other edge platforms. Its stated use is communicating with S3-compatible services, including Cloudflare R2, Backblaze B2, DigitalOcean Spaces, Ceph, Oracle Object Storage, Garage, MinIO, and Scaleway.

The repository description says the project moved to Code.NOLOG at `https://code.nolog.cz/thinking.tools/s3mini`. This matters when locating current source, issues, contribution material, or release information. The old `good-lly/s3mini` GitHub location should not be assumed to remain the canonical development repository.

The package concentrates on object operations. The README names listing, putting, getting, deleting, copying and moving, multipart uploads, conditional requests, pre-signed URLs, and SSE-C headers. It also supports AWS SigV4 request signing. That makes the library relevant when an application has a bounded storage requirement and does not need the wider collection of AWS service clients found in a general SDK.

Browser support is explicitly excluded. The README attributes this to use of Node.js APIs and polyfills, so bundling `s3mini` into a browser application is outside its documented target. Tree-shakeable ES module output and TypeScript definitions are useful for server-side TypeScript projects, but they do not change that runtime boundary.

Configuration, signing, and s3mini request flow

An application creates an `S3mini` instance with an access key, secret key, endpoint, and region. The Quick Start passes a buffer and an object key to `putAnyObject`, retrieves the stored value with `getObject`, and calls `listObjects` with a prefix. Based on the documented method name and feature list, `putAnyObject` selects between a single PUT and multipart upload according to object size.

The client provides a direct interface to S3-compatible APIs. AWS SigV4 support covers signed requests, while pre-signed URL support places signed request information in a URL. The release history identifies pre-signed URL support in `v0.9.2`, although the repository listing does not include complete release notes for later versions.

Object storage configuration is provider-specific. The Quick Start uses a Cloudflare R2 endpoint and the region value `auto`, while other supported services can require different endpoint formats or region values. Copying that example without changing the endpoint or credentials would not connect an application to its own bucket.

Conditional requests and SSE-C headers extend the basic request model, but they require attention to provider support and matching request headers. The README says SSE-C was tested on Cloudflare. It does not claim identical SSE-C behavior for every listed provider, so that feature should be verified against the chosen storage service.

Installing s3mini and making a first upload

The README lists npm, Yarn, and pnpm installation commands. The package metadata identifies `s3mini` as an ES module and lists `https://registry.npmjs.org/` as its publish registry. For an npm-based project, install it as follows. After the command completes, the project should have `s3mini` listed as a dependency in its package metadata.

npm install s3mini

The documentation also provides Yarn and pnpm equivalents. Choose the command that matches the package manager already used by the application.

yarn add s3mini

pnpm add s3mini

The README asks users to configure credentials and the endpoint through environment variables. It directs developers to copy `example.env` into `.env`, then provides a client configuration and two object operations. Replace the shown endpoint with the endpoint for your bucket and set credentials through the environment rather than embedding them in source.

import { S3mini } from 's3mini';

const s3 = new S3mini({
  accessKeyId: process.env.S3_ACCESS_KEY,
  secretAccessKey: process.env.S3_SECRET_KEY,
  endpoint: 'https://bucket.region.r2.cloudflarestorage.com',
  region: 'auto',
});

await s3.putAnyObject('photos/vacation.jpg', fileBuffer, 'image/jpeg');
const data = await s3.getObject('photos/vacation.jpg');

A successful first use depends on three details: the credential environment variables must be available to the process, the endpoint must address the intended bucket, and `fileBuffer` must already be available in the example's scope. The cleaned README truncates the listing example, so `examples/index.js` or `USAGE.md` is the place to confirm the complete return shape and listing syntax.

Multipart uploads and provider validation

Multipart uploads are the main handling feature beyond simple object PUTs. They matter when an application needs to transfer larger objects through multiple requests instead of relying on one request body. The README explicitly includes multipart uploads and states that `putAnyObject` chooses between a single PUT and multipart handling based on size.

That convenience does not remove provider-specific concerns. S3-compatible services can differ in accepted headers, multipart completion behavior, endpoint configuration, and support for optional request features. Although the README names a broad set of services, its statement that the project has been tested on them is not a complete behavioral contract for every configuration.

The package contains separate unit, public, provider, and end-to-end test commands in `package.json`. It also defines Bun variants for several of those suites. These scripts show that provider checks form part of the repository's development setup, but this review has not executed them. The scripts reveal which boundaries maintainers consider testable, including anonymous access, pre-signed URLs, bucket-name extraction, custom `fetch`, native Bun behavior, and named providers.

The public test command runs with `--verbose`, while the provider suite uses `--bail`. The end-to-end command composes the public and provider suites. Running the appropriate suite still requires access to the relevant provider or test setup. The README excerpt does not document every credential or service configuration needed by these commands, so `example.env` and the test files must be inspected before attempting provider validation.

npm run test:public

npm run test:providers

Where s3mini is the wrong client choice

The clearest exclusion is browser use. Both the README and repository description state that browser environments are unsupported. An application that needs S3 requests from client-side JavaScript must choose a browser-compatible approach rather than relying on bundling `s3mini`.

A second boundary is API breadth. The README describes an intentionally small set of essential S3 APIs. A project needing a particular AWS service client, advanced S3 feature, or exhaustive compatibility surface may find that feature absent. The available methods should be compared with `USAGE.md` and the TypeScript definitions before adoption, rather than assuming that support for basic objects extends to every S3 operation.

Pre-signed URLs and SSE-C also require careful review. A pre-signed URL depends on valid signing parameters and a provider-specific endpoint. SSE-C requires customer-provided key material to be managed consistently. The README does not document a browser-safe credential model or a universal SSE-C configuration across providers.

For applications needing a broader service client or a larger API surface, a full SDK may be an alternative. `s3mini` instead offers a small direct client with no runtime dependencies, but leaves the application responsible for selecting the exact operations and runtime configuration required by an S3-compatible service.

Maintenance, upgrades, licensing, and source location

The repository is not archived. Its last push was on 2026-10-15. The package metadata in `package.json` records version `1.0.3`, while the repository release list includes versions through `v0.9.4`. That difference may reflect different publication histories or metadata states, so version selection should be based on the actual npm package rather than reconciling the two records from memory.

Release dates include `v0.9.4` on 2026-04-08, `v0.9.3` on 2026-04-07, and `v0.9.2` on 2026-03-23. The `v0.9.2` release is labeled as adding pre-signed URL support. The repository also contains `BREAKING.md`, `CHANGELOG.md`, `SECURITY.md`, and `USAGE.md`, but their contents are not included in the available documentation, so specific upgrade procedures cannot be confirmed.

The package has zero runtime dependencies according to the README. This reduces transitive dependency management for consumers. Upgrades still require checking changes in supported operations, runtime behavior, and provider compatibility. The MIT license permits use, modification, distribution, and sublicensing under its conditions. This is a license summary rather than legal advice, so organizations with their own compliance requirements should review the actual `LICENSE` file.

Because the project moved to Code.NOLOG, upgrade research should start with that repository's `CHANGELOG.md`, `BREAKING.md`, and npm package entry. The older GitHub repository is a location marker, not the best source for current upgrade instructions.

Editorial conclusion

s3mini is suitable for TypeScript developers who need a compact client for basic S3-compatible object operations in server-side, Bun, or edge applications. It is unsuitable for browser execution and for projects that need the broader API surface of a full AWS SDK. Before adoption, verify the required operations against `USAGE.md`, test multipart behavior against the selected provider, and confirm that credential delivery and endpoint configuration fit the deployment runtime. For code already using this package, the first maintenance check should be whether its usage matches the current Code.NOLOG repository and the `1.0.3` version recorded in `package.json`.

Frequently asked questions

Official sources

1. good-lly/s3mini on GitHub
2. License: MIT
3. Project website
4. README
5. Releases