Install

npm i @dimah-s3/react

Create client & provider

Create the typed client instance using createS3Client.

lib/s3-client.ts

"use client";

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

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

To configure custom base paths, headers, or credentials:

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

Mount S3Provider

Mount <S3Provider> near your application root:

app/layout.tsx

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

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

Call your first hook

Use useUpload with a route name matching your server config:

app/avatar-uploader.tsx

"use client";

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

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

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

TypeScript route inference

Enable autocompletion and type checking for route names across hooks and components:

lib/s3-routes.ts

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 reference

import type {
  CreateS3ClientOptions,
  CreateS3ClientResult,
  ReactS3Client,
} from "@dimah-s3/react";

CreateS3ClientOptions

Prop

Type

Frequently asked questions

Pass an async headers function or credentials: "include" in createS3Client:

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

Setup