JavaScript SDK Guide

Overview

RustFS ships no first-party JavaScript SDK — it is S3-compatible, so you use the official AWS SDK for JavaScript (v3) configured to point at your RustFS server. This guide shows how to connect to RustFS and perform common object storage operations.

Prerequisites

Node.js 18 or later
A running RustFS instance (see the Installation Guide) — the S3 API listens on port 9000, the Console on port 9001
Access keys, set at install time via the RUSTFS_ACCESS_KEY / RUSTFS_SECRET_KEY environment variables (see Access Key Management)

Local test

If you did not set credentials at install time, the server defaults to rustfsadmin / rustfsadmin — fine for a throwaway local trial, never for anything reachable by others.

2.1 Install the SDK

Install the required AWS SDK v3 modules with npm:

npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner

The examples below use ES modules (import). Set "type": "module" in your package.json, or save the files with the .mjs extension.

Initialize the client

The following is a complete, runnable script. Replace localhost with your server's IP address if RustFS runs on another machine, and fill in your own access keys:

main.mjs

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

const s3 = new S3Client({
  endpoint: "http://localhost:9000", // RustFS S3 API address
  region: "us-east-1", // RustFS default region
  credentials: {
    accessKeyId: "<your-access-key>",
    secretAccessKey: "<your-secret-key>",
  },
  // RustFS uses path-style URLs by default; virtual-host style requires RUSTFS_SERVER_DOMAINS
  forcePathStyle: true,
});

const { Buckets } = await s3.send(new ListBucketsCommand({}));
console.log(Buckets?.map((b) => b.Name) ?? []);

Run it:

node main.mjs

[ 'my-bucket' ]

All snippets below reuse this s3 client.

Basic operations

4.1 Create a bucket

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

await s3.send(new CreateBucketCommand({ Bucket: "my-bucket" }));
console.log("Bucket created");

Bucket created

4.2 Upload an object

import { PutObjectCommand } from "@aws-sdk/client-s3";
import { readFileSync } from "fs";

const data = readFileSync("/path/to/hello.txt");

await s3.send(
  new PutObjectCommand({
    Bucket: "my-bucket",
    Key: "hello.txt",
    Body: data,
  })
);

console.log("File uploaded");

File uploaded

4.3 Download an object

import { GetObjectCommand } from "@aws-sdk/client-s3";
import { writeFile } from "fs/promises";

const response = await s3.send(
  new GetObjectCommand({ Bucket: "my-bucket", Key: "hello.txt" })
);

const streamToBuffer = async (stream) => {
  const chunks = [];
  for await (const chunk of stream) chunks.push(chunk);
  return Buffer.concat(chunks);
};

const buffer = await streamToBuffer(response.Body);
await writeFile("downloaded.txt", buffer);

console.log("File downloaded");

File downloaded

4.4 List objects

import { ListObjectsV2Command } from "@aws-sdk/client-s3";

const res = await s3.send(new ListObjectsV2Command({ Bucket: "my-bucket" }));
res.Contents?.forEach((obj) => console.log(`${obj.Key} (${obj.Size} bytes)`));

hello.txt (12 bytes)

4.5 Delete an object

import { DeleteObjectCommand } from "@aws-sdk/client-s3";

await s3.send(new DeleteObjectCommand({ Bucket: "my-bucket", Key: "hello.txt" }));
console.log("File deleted");

File deleted

import { GetObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

const url = await getSignedUrl(
  s3,
  new GetObjectCommand({ Bucket: "my-bucket", Key: "hello.txt" }),
  { expiresIn: 600 }
);

console.log("Presigned GET URL:", url);

Presigned GET URL: http://localhost:9000/my-bucket/hello.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&...

Upload (PUT)

import { PutObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

const url = await getSignedUrl(
  s3,
  new PutObjectCommand({ Bucket: "my-bucket", Key: "upload.txt" }),
  { expiresIn: 600 }
);

console.log("Presigned PUT URL:", url);

5.2 Multipart upload

import {
  CreateMultipartUploadCommand,
  UploadPartCommand,
  CompleteMultipartUploadCommand,
  AbortMultipartUploadCommand,
} from "@aws-sdk/client-s3";
import { statSync, openSync, readSync, closeSync } from "fs";

const bucket = "my-bucket";
const key = "large-file.zip";
const filePath = "./large-file.zip";
const partSize = 5 * 1024 * 1024; // 5 MB

// 1. Create upload task
const createRes = await s3.send(
  new CreateMultipartUploadCommand({ Bucket: bucket, Key: key })
);
const uploadId = createRes.UploadId;

// 2. Segmented upload
const fileSize = statSync(filePath).size;
const fd = openSync(filePath, "r");
const parts = [];

for (let partNumber = 1, offset = 0; offset < fileSize; partNumber++) {
  const buffer = Buffer.alloc(Math.min(partSize, fileSize - offset));
  readSync(fd, buffer, 0, buffer.length, offset);

  const uploadPartRes = await s3.send(
    new UploadPartCommand({
      Bucket: bucket,
      Key: key,
      UploadId: uploadId,
      PartNumber: partNumber,
      Body: buffer,
    })
  );

  parts.push({ ETag: uploadPartRes.ETag, PartNumber: partNumber });
  offset += partSize;
}

closeSync(fd);

// 3. Complete upload
await s3.send(
  new CompleteMultipartUploadCommand({
    Bucket: bucket,
    Key: key,
    UploadId: uploadId,
    MultipartUpload: { Parts: parts },
  })
);

console.log("Multipart upload completed");

Multipart upload completed

Troubleshooting

Problem	Cause	Solution
SignatureDoesNotMatch	Signature mismatch	SDK v3 signs with SigV4 by default; check credentials, region, and endpoint
EndpointConnectionError	Endpoint address misconfigured or not started	Check if RustFS address is accessible
NoSuchKey	File does not exist	Check if `Key` is spelled correctly
InvalidAccessKeyId / Secret	Credentials misconfigured	Check `accessKeyId` / `secretAccessKey` configuration
Upload failure (path issue)	Path-style not enabled	Set `forcePathStyle: true`

Appendix: Browser uploads

With presigned URLs, browsers can upload objects directly without access to your credentials.

Frontend (HTML+JS) upload example:

<input type="file" id="fileInput" />
<script>
  document.getElementById("fileInput").addEventListener("change", async (e) => {
    const file = e.target.files[0];
    const url = await fetch("/api/presigned-put-url?key=" + file.name).then((r) =>
      r.text()
    );

    const res = await fetch(url, {
      method: "PUT",
      body: file,
    });

    if (res.ok) alert("Uploaded!");
  });
</script>

For other operations (object tagging, bucket policies, and more), see the AWS SDK for JavaScript v3 documentation — most S3 operations work the same way against RustFS; see S3 compatibility for exceptions.

JavaScript SDK Guide

Overview

Prerequisites

2.1 Install the SDK

Initialize the client

Basic operations

4.1 Create a bucket

4.2 Upload an object

4.3 Download an object

4.4 List objects

4.5 Delete an object

Advanced features

5.1 Generate presigned URLs

Download (GET)

Upload (PUT)

5.2 Multipart upload

Troubleshooting

Appendix: Browser uploads

On this page

JavaScript SDK Guide

OverviewCopy Anchor Link

PrerequisitesCopy Anchor Link

2.1 Install the SDKCopy Anchor Link

Initialize the clientCopy Anchor Link

Basic operationsCopy Anchor Link

4.1 Create a bucketCopy Anchor Link

4.2 Upload an objectCopy Anchor Link

4.3 Download an objectCopy Anchor Link

4.4 List objectsCopy Anchor Link

4.5 Delete an objectCopy Anchor Link

Advanced featuresCopy Anchor Link

5.1 Generate presigned URLsCopy Anchor Link

Download (GET)Copy Anchor Link

Upload (PUT)Copy Anchor Link

5.2 Multipart uploadCopy Anchor Link

TroubleshootingCopy Anchor Link

Appendix: Browser uploadsCopy Anchor Link

On this page

Overview

Prerequisites

2.1 Install the SDK

Initialize the client

Basic operations

4.1 Create a bucket

4.2 Upload an object

4.3 Download an object

4.4 List objects

4.5 Delete an object

Advanced features

5.1 Generate presigned URLs

Download (GET)

Upload (PUT)

5.2 Multipart upload

Troubleshooting

Appendix: Browser uploads