JavaScript / Node.js

Use the AWS SDK v3 or the MinIO SDK to interact with Hippius S3 from Node.js or the browser.

Pick the closest region for best performance

Hippius S3 is served through regional caches. For lower latency, point your client at the endpoint closest to you:

• Europe: https://eu-central-1.hippius.com (the default https://s3.hippius.com also resolves here)
• US: https://us-east-1.hippius.com

All regions serve the same data — just swap the endpoint / endPoint in the snippets below.

AWS SDK v3

Install

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

Connect

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

const s3 = new S3Client({
  endpoint: "https://s3.hippius.com",
  region: "decentralized",
  credentials: {
    accessKeyId: "YOUR_ACCESS_KEY",
    secretAccessKey: "YOUR_SECRET_KEY",
  },
  forcePathStyle: true,
});

Create a bucket

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

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

Upload a file

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

// From disk (Node.js)
await s3.send(new PutObjectCommand({
  Bucket: "my-bucket",
  Key: "file.txt",
  Body: readFileSync("./file.txt"),
}));

// From string/buffer
await s3.send(new PutObjectCommand({
  Bucket: "my-bucket",
  Key: "hello.txt",
  Body: "Hello from Hippius!",
  ContentType: "text/plain",
}));

Download a file

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

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

// Read the stream
const text = await response.Body.transformToString();
console.log(text);

List objects

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

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

for (const obj of response.Contents ?? []) {
  console.log(obj.Key, obj.Size);
}

Presigned URL

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

const url = await getSignedUrl(
  s3,
  new GetObjectCommand({ Bucket: "my-bucket", Key: "hello.txt" }),
  { expiresIn: 3600 }, // 1 hour
);
console.log(url);

---

MinIO SDK (Node.js)

Install

npm install minio

Connect

import { Client } from "minio";

const client = new Client({
  endPoint: "s3.hippius.com",
  port: 443,
  useSSL: true,
  accessKey: "YOUR_ACCESS_KEY",
  secretKey: "YOUR_SECRET_KEY",
  region: "decentralized",
});

Create a bucket

await client.makeBucket("my-bucket", "decentralized");

Upload a file

// From disk
await client.fPutObject("my-bucket", "file.txt", "./file.txt");

// From buffer
import { Readable } from "stream";

const buffer = Buffer.from("Hello from Hippius!");
await client.putObject(
  "my-bucket", "hello.txt",
  Readable.from(buffer), buffer.length,
  { "Content-Type": "text/plain" }
);

Download a file

// To disk
await client.fGetObject("my-bucket", "file.txt", "./downloaded.txt");

Presigned URL

const url = await client.presignedGetObject("my-bucket", "hello.txt", 3600);
console.log(url);

---

Browser uploads with presigned URLs

For browser-side uploads, generate a presigned PUT URL on your server and use it client-side — no credentials needed in the browser:

Server (Node.js):

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

const uploadUrl = await getSignedUrl(
  s3,
  new PutObjectCommand({ Bucket: "my-bucket", Key: "user-upload.jpg" }),
  { expiresIn: 300 }, // 5 minutes
);
// Send uploadUrl to the browser

Browser:

await fetch(uploadUrl, {
  method: "PUT",
  body: file, // File object from <input type="file">
  headers: { "Content-Type": file.type },
});

---

Complete Working Example (Node.js + AWS SDK v3)

Save this script as hippius-s3.mjs and run it with your credentials:

import {
  S3Client,
  CreateBucketCommand,
  PutObjectCommand,
  ListObjectsV2Command,
  GetObjectCommand
} from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

// 1. Connect to Hippius S3
const s3 = new S3Client({
  endpoint: "https://s3.hippius.com",
  region: "decentralized",
  credentials: {
    accessKeyId: "YOUR_ACCESS_KEY",
    secretAccessKey: "YOUR_SECRET_KEY",
  },
  forcePathStyle: true,
});

const bucketName = "hippius-demo-bucket";
const fileKey = "greeting.txt";

async function main() {
  // 2. Create bucket
  console.log(`Creating bucket: ${bucketName}`);
  try {
    await s3.send(new CreateBucketCommand({ Bucket: bucketName }));
  } catch (err) {
    if (err.name === 'BucketAlreadyOwnedByYou' || err.name === 'BucketAlreadyExists') {
      console.log("Bucket already exists.");
    } else {
      throw err;
    }
  }

  // 3. Upload string
  console.log(`Uploading file: ${fileKey}`);
  await s3.send(new PutObjectCommand({
    Bucket: bucketName,
    Key: fileKey,
    Body: "Welcome to Hippius S3 Storage!",
    ContentType: "text/plain",
  }));

  // 4. List objects
  console.log("Listing objects:");
  const listRes = await s3.send(new ListObjectsV2Command({ Bucket: bucketName }));
  for (const obj of listRes.Contents || []) {
    console.log(` - ${obj.Key} (${obj.Size} bytes)`);
  }

  // 5. Download file
  console.log("Downloading file:");
  const getRes = await s3.send(new GetObjectCommand({ Bucket: bucketName, Key: fileKey }));
  const content = await getRes.Body.transformToString();
  console.log(` File content: ${content}`);

  // 6. Generate presigned URL
  console.log("Generating presigned URL:");
  const url = await getSignedUrl(
    s3,
    new GetObjectCommand({ Bucket: bucketName, Key: fileKey }),
    { expiresIn: 3600 }
  );
  console.log(` URL: ${url}`);
}

main().catch(console.error);