# Setup (https://s3.dimah.dev/docs/react/setup)
## Install [#install]
npm
pnpm
yarn
bun
```bash
npm i @dimah-s3/react
```
```bash
pnpm add @dimah-s3/react
```
```bash
yarn add @dimah-s3/react
```
```bash
bun add @dimah-s3/react
```
## Create client & provider [#1-create-client--provider]
Create the typed client instance using `createS3Client`.
```ts title="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:
```ts
export const s3Client = createS3Client({
basePath: "/api/s3",
credentials: "include",
headers: async () => ({
Authorization: `Bearer ${await getAuthToken()}`,
}),
});
```
If you are using a custom backend API instead of `@dimah-s3/server`, implement `S3Api` using `defineApi`:
```tsx title="components/s3-provider.tsx"
"use client";
import { S3Provider } from "@dimah-s3/react";
import { api } from "@/lib/s3-api";
export function AppS3Provider({ children }: { children: React.ReactNode }) {
return {children};
}
```
See [Custom Backend](https://s3.dimah.dev/docs/react/custom-backend) for protocol specifications.
## Mount S3Provider [#2-mount-s3provider]
Mount `` near your application root:
```tsx title="app/layout.tsx"
import { S3Provider } from "@/lib/s3-client";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
{children}
);
}
```
```tsx title="src/main.tsx"
import React from "react";
import ReactDOM from "react-dom/client";
import { S3Provider } from "./lib/s3-client";
import { App } from "./app";
ReactDOM.createRoot(document.getElementById("root")!).render(
,
);
```
## Call your first hook [#3-call-your-first-hook]
Use `useUpload` with a route name matching your server config:
```tsx title="app/avatar-uploader.tsx"
"use client";
import { useUpload } from "@dimah-s3/react";
export function AvatarUploader() {
const upload = useUpload({
route: "avatar",
});
return (
{upload.isUploading
? `Uploading: ${upload.progress.percent}%`
: "Click or drop avatar here"}
);
}
```
***
## TypeScript route inference [#typescript-route-inference]
Enable autocompletion and type checking for route names across hooks and components:
```ts title="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, true> {}
}
```
***
## Type reference [#type-reference]
```ts
import type {
CreateS3ClientOptions,
CreateS3ClientResult,
ReactS3Client,
} from "@dimah-s3/react";
```
### CreateS3ClientOptions [#creates3clientoptions]
## Frequently asked questions [#frequently-asked-questions]
By default, hooks fetch constraints (`fileTypes`, `maxFileSize`) automatically from `GET /routes` (`api.catalog()`). You can omit `accept` and `maxFileSize` on `useUpload` so the server remains the single source of truth.
Pass an async `headers` function or `credentials: "include"` in `createS3Client`:
```ts
export const s3Client = createS3Client({
credentials: "include",
headers: async () => ({
Authorization: `Bearer ${getStoredToken()}`,
}),
});
```