DEV Community: Yvan Guekeng Tindo

BentoS3: a lightweight S3-compatible server for local development and tests

Yvan Guekeng Tindo — Fri, 15 May 2026 11:32:13 +0000

I recently published the first stable version of BentoS3, a lightweight S3-compatible server for local development, automated tests, and CI environments.

The project came from a practical need. In our local environment, we were using MinIO as an S3 replacement. It worked, but we were still pinned to an old version, before the project direction changed and several features were removed from the free version UI and now the project is no longer maintained. That made the local setup feel more fragile than it needed to be.

At the same time, our integration tests depended on containers just to exercise code paths that talked to S3. That added setup cost, made the test environment heavier, and slowed down feedback loops. For the kind of S3 usage we had, we did not need a full object storage server. We needed something small, embeddable, and predictable.

That is the goal of BentoS3: provide a practical subset of the S3 API that is easy to run locally and easy to embed in tests.

It is not production object storage. It does not try to implement every S3 feature. The supported APIs are mostly based on the usage I had with S3, but I am open to improving compatibility over time based on real use cases.

What BentoS3 Provides

BentoS3 can be used in two main ways:

As a standalone S3-compatible server started from the CLI.
As an embeddable Node.js library for Vitest, Jest, or framework-based integration tests.

It works with the official AWS SDK for JavaScript v3 using path-style addressing, and stores data on the local filesystem by default.

The main use cases are:

Local development when your application expects an S3 endpoint.
Integration tests that need bucket and object operations.
CI jobs where you want to avoid Docker or external services.
Framework apps that need a local S3-compatible route during development or testing.

Installation

Install it from npm:

npm install bento-s3

BentoS3 requires Node.js 20 or newer.

Running BentoS3 Locally

The fastest way to start a local S3-compatible server is with the CLI:

npx bentos3 serve

By default, the server listens on 127.0.0.1:9000 and stores its data in ./.bentos3.

You can also configure the host, port, and storage directory explicitly:

npx bentos3 serve --host 127.0.0.1 --port 9000 --root-dir ./.bentos3

On first start, BentoS3 bootstraps a default access key and prints the credentials. It also includes a small server-rendered dashboard.

You can create a dashboard user with:

npx bentos3 user create admin

Then open the dashboard at:

http://127.0.0.1:9000/ui

The dashboard lets you browse buckets, upload and download objects, and manage access keys.

Connecting With The AWS SDK

BentoS3 targets the official AWS SDK for JavaScript v3. The important part is to configure a custom endpoint and enable path-style addressing.

import { CreateBucketCommand, PutObjectCommand, S3Client } from "@aws-sdk/client-s3";

const client = new S3Client({
  region: "us-east-1",
  endpoint: "http://127.0.0.1:9000",
  forcePathStyle: true,
  credentials: {
    accessKeyId: "bentos3",
    secretAccessKey: process.env.BENTOS3_SECRET_ACCESS_KEY ?? "replace-me",
  },
});

await client.send(new CreateBucketCommand({ Bucket: "example-bucket" }));

await client.send(
  new PutObjectCommand({
    Bucket: "example-bucket"Proceed,
    Key: "hello.txt",
    Body: "Hello BentoS3",
  }),
);

If your application already uses the AWS SDK, this usually means the only test/local-specific configuration you need is the endpoint, credentials, and forcePathStyle: true.

Using BentoS3 In Integration Tests

The most useful part for me is the managed test server. Instead of starting a container before the test suite, you can start BentoS3 directly from Node.js.

Here is a minimal Vitest-style setup:

import { CreateBucketCommand, PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
import { afterAll, beforeAll, expect, test } from "vitest";
import { BentoS3, MemoryAuthStore } from "bento-s3";

let server: BentoS3;
let client: S3Client;

beforeAll(async () => {
  const authStore = new MemoryAuthStore();

  await authStore.createCredential({
    accessKeyId: "test",
    secretAccessKey: "test-secret",
  });

  server = new BentoS3({
    port: 0,
    authStore,
    dashboard: { enabled: false },
  });

  await server.start();

  client = new S3Client({
    region: "us-east-1",
    endpoint: server.endpoint,
    forcePathStyle: true,
    credentials: {
      accessKeyId: "test",
      secretAccessKey: "test-secret",
    },
  });
});

afterAll(async () => {
  await server.stop();
});

test("uploads an object", async () => {
  await client.send(new CreateBucketCommand({ Bucket: "photos" }));

  await client.send(
    new PutObjectCommand({
      Bucket: "photos",
      Key: "cat.jpg",
      Body: Buffer.from("image-bytes"),
    }),
  );

  expect(true).toBe(true);
});

Using port: 0 asks Node.js to allocate an available port. BentoS3 exposes the final URL through server.endpoint, so tests can run without hard-coded ports and without conflicts between parallel jobs.

For tests, MemoryAuthStore keeps credentials in memory. For local development, BentoS3 also provides a JSON-backed auth store that persists credentials on disk.

Embedding BentoS3 In A Framework

BentoS3 is built around a framework-neutral core. Adapters translate framework requests into BentoS3's internal request format.

For example, with Express:

import express from "express";
import { MemoryAuthStore } from "bento-s3";
import { BentoS3Core } from "bento-s3/core";
import { expressAdapter } from "bento-s3/adapters/express";

const app = express();
const authStore = new MemoryAuthStore();

await authStore.createCredential({
  accessKeyId: "test",
  secretAccessKey: "test-secret",
});

const bento = new BentoS3Core({ authStore });

app.use("/s3", expressAdapter(bento));

When mounted under /s3, the AWS SDK endpoint should include that path:

const client = new S3Client({
  endpoint: "http://127.0.0.1:3000/s3",
  forcePathStyle: true,
  region: "us-east-1",
  credentials: {
    accessKeyId: "test",
    secretAccessKey: "test-secret",
  },
});

There are also adapters for Koa, Fastify, Node HTTP, and Fetch-style handlers. One important detail when embedding BentoS3 in a framework is body parsing: BentoS3 must receive the raw request stream, so mount the S3 route before JSON/body parsers for that route.

Supported S3 Operations

BentoS3 1.0 supports the operations I needed most often in local development and integration tests:

ListBuckets
CreateBucket
DeleteBucket
HeadBucket
ListObjectsV2
PutObject
GetObject
HeadObject
DeleteObject
DeleteObjects
CopyObject

This is enough for a lot of common application-level S3 usage: create a bucket, upload files, read them back, list objects, copy objects, and clean up after tests.

Current Limitations

BentoS3 intentionally starts with a practical subset instead of trying to clone all of S3.

The main limitations today are:

Requests must use path-style addressing.
SigV4 header authentication is supported, but presigned URL query authentication is not supported yet.
ListObjectsV2 supports prefix filtering, but not delimiter grouping, continuation tokens, StartAfter, or custom MaxKeys pagination.
Multipart upload, range requests, ACLs, bucket policies, object tagging, lifecycle policies, replication, and object lock are not supported.
Bucket names are restricted to filesystem-safe path segments.

If you need one of these features for a real local development or testing use case, opening an issue is useful. I would rather improve parity based on concrete usage than implement a large surface area blindly.

Conclusion

BentoS3 is a small tool for a specific job: make S3-dependent local development and integration tests easier to run.

For our use case, replacing a heavier local object storage setup and removing containers from the test path made the environment simpler and faster. Version 1.0.0 is the first stable release of that idea.

You can find the package, full README, examples, and compatibility notes on GitHub:

https://github.com/gtindo/BentoS3

How to Build a Simple Web Component from Scratch

Yvan Guekeng Tindo — Wed, 22 Jan 2025 15:27:35 +0000

Web components are a set of powerful tools that allow you to create your own custom HTML elements. These elements can be used just like any other HTML tag (e.g., <div>, <span>) but with your own special behavior and design.

The core technologies behind web components are:

Custom Elements: Allows you to define new HTML tags.
Shadow DOM: Keeps your element’s structure and styles isolated from the rest of the page.
HTML Templates: Lets you define reusable HTML that isn’t rendered until you use it.

In this guide, we'll build a simple counter component from scratch. This counter will have buttons to increase and decrease a number.

The component will look like this:

Here is the link for final version with all the source code.

Prerequisites

Before we begin, here’s what you need to know:

Basic JavaScript.
A simple understanding of how the DOM (Document Object Model) works (don’t worry if you’re not an expert — we’ll cover what you need).

Setting Up the Project

First, let’s set up a simple project with two files:

counter.html: The HTML file that will hold the page structure.
counter.js: The JavaScript file where we define our custom counter element.

`counter.html`

This file contains the basic HTML structure of your page:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width" />
    <title>Counter Component</title>
    <script src="./counter.js"></script>
  </head>
  <body>
    <!-- The counter component will be inserted here -->
  </body>
</html>

Creating the Template

A template is just a way to define the structure of our custom element (like what it looks like). Let’s create one for our counter:

`counter.html` (Add the Template)

<body>
  <template id="x-counter">
    <div>
      <button id="min-btn">-</button>
      <span id="counter-display">0</span>
      <button id="plus-btn">+</button>
    </div>
  </template>
</body>

Here’s what each part of this template does:

<button id="min-btn">-</button>: A button to decrease the counter.
<span id="counter-display">0</span>: A place to show the current counter value.
<button id="plus-btn">+</button>: A button to increase the counter.

This template will not show up on the page directly. We will use it later to create our custom element.

Defining the Custom Counter Element

Now, we’ll write the JavaScript to define how our counter works. We’ll create a class that extends the basic HTMLElement, which is what all HTML elements are built on.

`counter.js`

class XCounter extends HTMLElement {
  constructor() {
    super();
    this.counter = 0; // Start the counter at 0
    this.elements = {}; // To store references to our buttons and display
  }

  connectedCallback() {
    // This runs when the element is added to the page
    const template = document.getElementById("x-counter");
    this.attachShadow({ mode: "open" });

    // Clone the template and add it to our custom element's shadow DOM
    this.shadowRoot.appendChild(template.content.cloneNode(true));

    // Get references to the buttons and display
    this.elements = {
      plusBtn: this.shadowRoot.querySelector("#plus-btn"),
      minBtn: this.shadowRoot.querySelector("#min-btn"),
      counterDisplay: this.shadowRoot.querySelector("#counter-display")
    };

    // Show the initial counter value
    this.displayCount();

    // Add event listeners for the buttons
    this.elements.plusBtn.onclick = () => this.increment();
    this.elements.minBtn.onclick = () => this.decrement();
  }

  increment() {
    this.counter += 1;
    this.displayCount();
  }

  decrement() {
    this.counter -= 1;
    this.displayCount();
  }

  displayCount() {
    this.elements.counterDisplay.textContent = this.counter;
  }
}

// Register the custom element so we can use it in HTML
customElements.define("x-counter", XCounter);

Breaking it Down:

The constructor: This is where we set up initial values for our counter and store references to the elements inside the counter.
connectedCallback: This function runs when the custom element is added to the page. Here, we:
- Attach a shadow DOM to keep our element’s structure and styles separate from the rest of the page.
- Clone the template we created earlier and add it to the shadow DOM.
- Set up references to the plus and minus buttons and the display where the counter is shown.
increment and decrement: These functions change the value of the counter by 1 and update the display.
displayCount: This function updates the text inside the <span> to show the current counter value.
Register the element: Finally, we tell the browser to recognize <x-counter> as a custom element that uses the XCounter class.

Using the Counter Component

Now that our counter is defined, we can use it just like any other HTML element. Here’s how to add it to the page:

`counter.html` (Add the Custom Element)

<body>
  <x-counter></x-counter>

  <template id="x-counter">
   ...
  </template>
</body>

This will create a counter on the page with two buttons — one to increase and one to decrease the number. The counter will start at 0, and you can interact with it by clicking the buttons.

Style the element

Styling can be done in a few ways, but when using the Shadow DOM, we can encapsulate the styles to ensure they don’t interfere with other parts of the page. In this section, we will style our counter element using adopteStyleSheet.

counter.js with Styling

...
    connectedCallback() {
        ...
         this.attachShadow({ mode: 'open' });

         // Add styles to the component
         const sheet = new CSSStyleSheet();
         sheet.replaceSync(this.styles());
         this.shadowRoot.adoptedStyleSheets = [sheet];

         // Clone the template and add it to our custom element's shadow DOM
       this.shadowRoot.appendChild(template.content.cloneNode(true));
        ...
    }
    ...
    styles() {
      return `
         :host {
          display: block;
          border: dotted 3px #333;
          width: fit-content;
          height: fit-content;
          padding: 15px;
        }

        button {
          border: solid 1px #333;
          padding: 10px;
          min-width: 35px;
          background: #333;
          color: #fff;
          cursor: pointer;
        }

        button:hover {
          background: #222;
        }

        span {
          display: inline-block;
          padding: 10px;
          width: 50px;
          text-align: center;
        }
      `
    }
    ...
...

Conclusion

In this tutorial, we learned how to create a simple web component:

We used an HTML template to define the structure of our custom element.
We added shadow DOM to isolate the styles and behavior of our component.
We wrote JavaScript to control the logic of the counter (increment, decrement, and display the count).

Web components are a great way to make your web applications more modular and reusable.

DEV Community: Yvan Guekeng Tindo

BentoS3: a lightweight S3-compatible server for local development and tests

What BentoS3 Provides

Installation

Running BentoS3 Locally

Connecting With The AWS SDK

Using BentoS3 In Integration Tests

Embedding BentoS3 In A Framework

Supported S3 Operations

Current Limitations

Conclusion

How to Build a Simple Web Component from Scratch

Prerequisites

Setting Up the Project

counter.html

Creating the Template

counter.html (Add the Template)

Defining the Custom Counter Element

counter.js

Breaking it Down:

Using the Counter Component

counter.html (Add the Custom Element)

Style the element

counter.js with Styling

Conclusion

`counter.html`

`counter.html` (Add the Template)

`counter.js`

`counter.html` (Add the Custom Element)