React Setup
Initialize @dimah-s3/react, configure S3Provider, and call your first hook.
Install
npm i @dimah-s3/reactCreate the React client and provider
Create the typed React client with createS3Client.
"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:
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:
"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.isUploading
? `Uploading: ${upload.progress.percent}%`
: "Click or drop files here"}
</div>
);
}TypeScript route inference
Enable autocompletion and type checking for 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 reference
import type { CreateS3ClientOptions } from "@dimah-s3/react";CreateS3ClientOptions
Prop
Type
Frequently asked questions
Omit accept and maxFileSize from useUpload. By default, the React client
fetches fileTypes and maxFileSize from GET /routes (api.catalog()), so
the server remains the source of truth.
Pass an async headers function or credentials: "include" in createS3Client:
export const s3Client = createS3Client({
credentials: "include",
headers: async () => ({
Authorization: `Bearer ${getStoredToken()}`,
}),
});