# Introduction (https://v1.s3.dimah.dev/docs)

dimah-s3 is a modular, full-stack S3 toolkit for React and Node.js runtimes.
It provides typed server handlers, headless React hooks, optional shadcn UI components,
and database plugin for object tracking when your application needs it.

## Architecture flow [#architecture-flow]

<Flow
  label="Presign-first architecture"
  steps={[
    { name: "Browser", kind: "client", note: "requests signed URL" },
    { name: "Server", kind: "server", note: "executes guards and signs URL" },
    { name: "S3 Bucket", kind: "s3", note: "receives the upload" },
  ]}
/>

The backend signs a short-lived URL, the browser talks to your bucket, and
AWS credentials never leave the server. Downloads can also pass through
your server as a proxy.

**For coding agents** — [llms.txt](https://v1.s3.dimah.dev/llms.txt) · [llms-full.txt](https://v1.s3.dimah.dev/llms-full.txt).

---

## What you get [#what-you-get]

- **Fast setup** — a working upload in minutes
- **Full stack** — server, client, and optional shadcn UI
- **Full lifecycle** — upload, download, and delete, including multipart
- **Server hooks** — auth, quotas, confirm, and cleanup on the server ([Better Auth](https://www.better-auth.com)-like)
- **Optional database** — ownership and listings when you need them

It is not an S3 SDK wrapper. List, copy, tagging, and other operations stay
in your own code with the
[AWS SDK](https://www.npmjs.com/package/@aws-sdk/client-s3).

## Frequently asked questions [#frequently-asked-questions]

<Accordions>

<Accordion title="When should I choose dimah-s3?">

When you own the S3-compatible bucket and need more than an upload picker:
server-owned keys, verified confirmation, private downloads, guarded
deletion, multipart resume, or optional database tracking.

If you are choosing between managed storage, an upload-focused toolkit, or a
client uploader, use the [comparison guide](https://v1.s3.dimah.dev/docs/comparison).

</Accordion>

<Accordion title="Does dimah-s3 replace the AWS SDK?">

No. dimah-s3 covers presign upload, download, and delete. Use the AWS SDK
for everything else — list, copy, retention, tagging, and similar work.

</Accordion>

<Accordion title="Can I use dimah-s3 with Cloudflare R2 or MinIO?">

Yes. Configure an AWS SDK `S3Client` for the provider. Cloudflare R2 upload
routes use `method: "PUT"`; MinIO commonly needs `forcePathStyle: true`.
See the [provider guides](https://v1.s3.dimah.dev/docs/providers) for endpoints and CORS.

</Accordion>

<Accordion title="How does dimah-s3 keep S3 credentials secure?">

The browser sends a route name. The server runs guards, chooses a key
inside that route's namespace, and returns a short-lived signed request.
Credentials never leave the server.

</Accordion>

<Accordion title="Does dimah-s3 support resumable multipart uploads?">

Yes. Multipart uploads support chunking, retries, cancellation, and part
reconciliation. Add a persistent `UploadStore`; after a reload, the user
reselects the same local file and the client resumes. See
[Upload Store](https://v1.s3.dimah.dev/docs/react/upload-store).

</Accordion>

</Accordions>

---

## Explore documentation [#explore-documentation]

<Cards>
  <Card
    title="Quickstart"
    href="/docs/quickstart"
    description="Get a working upload running in a few minutes."
  />
  <Card
    title="Server Guide"
    href="/docs/server"
    description="Configure routes, lifecycle hooks, guards, and runtimes."
  />
  <Card
    title="React Client"
    href="/docs/react"
    description="Headless hooks for upload, download, and delete."
  />
  <Card
    title="UI Components"
    href="/docs/react/ui"
    description="Prebuilt shadcn buttons, dropzones, and status."
  />
  <Card
    title="Providers"
    href="/docs/providers"
    description="Setup guides for AWS S3, Cloudflare R2, and MinIO."
  />
  <Card
    title="Database Plugin"
    href="/docs/db"
    description="Track files, ownership, and listings."
  />
  <Card
    title="Comparison"
    href="/docs/comparison"
    description="Compare dimah-s3 with Better Upload, UploadThing, and Uppy."
  />
</Cards>