# Introduction (https://v2.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 a database plugin for object tracking when your application needs it.

<Callout title="2.0 beta">
  This site documents the 2.0 beta. Install with the `beta` dist-tag. A new beta
  ships every few days and can include breaking changes until 2.0.0. Stable 1.x
  stays at [s3.dimah.dev](https://s3.dimah.dev/docs). Moving a 1.7 app: [Upgrade
  to 2.0 beta](https://v2.s3.dimah.dev/docs/migration-2-0).
</Callout>

## 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://v2.s3.dimah.dev/llms.txt) · [llms-full.txt](https://v2.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://v2.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. Uploads use presigned
PUT by default, which R2 supports; MinIO commonly needs `forcePathStyle: true`.
See the [provider guides](https://v2.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 with
a signed [upload ticket](https://v2.s3.dimah.dev/docs/server/upload-tickets). Confirm accepts only
uploads the server started, and credentials never leave the server.

</Accordion>

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

Yes. The server picks the part layout, and the client uploads parts in
parallel with retries, cancellation, and per-part SHA-256 checks when the
route asks for them. Add a persistent `UploadStore`; after a reload, the user
reselects the same local file and the client resumes. See
[Upload Store](https://v2.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="Composable shadcn controls for upload, download, and delete."
  />
  <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."
  />
  <Card
    title="Upgrade to 2.0 beta"
    href="/docs/migration-2-0"
    description="Move a 1.7 app onto the 2.0 beta. Betas can break until 2.0.0."
  />
</Cards>