React Setup

InstallCopy Anchor Link

npm i @dimah-s3/react@beta @dimah-s3/core@beta @fuma-translate/react

@dimah-s3/react needs React 19.2. @dimah-s3/core holds APIError and the protocol helpers, and @fuma-translate/react powers the translated strings.

"use client";

import { createS3Client } from "@dimah-s3/react";

export const s3Client = createS3Client();
export const S3Provider = s3Client.Provider;

export const s3Client = createS3Client({
  basePath: "/api/s3", 
  credentials: "include", 
  headers: async () => ({
    Authorization: `Bearer ${await getAuthToken()}`, 
  }), 
});

import { S3Provider } from "@/lib/s3-client"; 

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <S3Provider>{children}</S3Provider>
      </body>
    </html>
  );
}

"use client";

import { useUpload } from "@dimah-s3/react";

export function FileUploader() {
  const upload = useUpload({ route: "avatar" });

  return (
    <div
      {...upload.getRootProps({
        className: "cursor-pointer rounded border p-4 text-center",
      })}
    >
      <input {...upload.getInputProps()} />
      {upload.isPending
        ? `Uploading: ${upload.progress.percent}%`
        : "Click or drop a file here"}
    </div>
  );
}

Shared and server modulesCopy Anchor Link

The root entry is a client module. Plain functions that do not need React, such as defineApi, memoryObjectSource, and createLocalStorageStore, ship from @dimah-s3/react/engine, which has no "use client" directive:

import { defineApi } from "@dimah-s3/react/engine";

See Engine for the full list.

TypeScript route inferenceCopy Anchor Link

Type route names across hooks and components:

import type { InferS3Routes } from "@dimah-s3/core";
import type { s3 } from "@/lib/s3";

declare module "@dimah-s3/core" {
  interface DimahS3Routes extends Record<InferS3Routes<typeof s3>, true> {} 
}

Type referenceCopy Anchor Link

import type { CreateS3ClientOptions } from "@dimah-s3/core";

CreateS3ClientOptionsCopy Anchor Link

Frequently asked questionsCopy Anchor Link

export const s3Client = createS3Client({
  credentials: "include", 
  headers: async () => ({
    Authorization: `Bearer ${getStoredToken()}`, 
  }), 
});