# EdgeStore Docs: Agents
URL: https://edgestore.dev/docs/agents
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/(getting-started)/agents.mdx



## Give your agent the skill

<AgentPrompt>
  Read [https://edgestore.dev/SKILL.md](https://edgestore.dev/SKILL.md) and add file uploads to this application.
</AgentPrompt>

For ongoing use, install the plugin or use the CLI below.

## Use a plugin

The [repository plugin](https://github.com/edgestorejs/edgestore) bundles the skill and MCP connection for [Codex](https://developers.openai.com/plugins/build/plugins), [Claude Code](https://code.claude.com/docs/en/plugins), and [Cursor](https://cursor.com/docs/plugins). Follow your client's plugin installation instructions, then sign in through its MCP controls.

If you use the plugin, skip the CLI setup below. If you already configured MCP directly, disable one of the two connections in your client.

## Set up with the CLI

Install the CLI with Node.js 22.22.0 or later:

```sh
npm install --global @edgestore/cli@rc
```

Then run this in your application directory:

```sh
edgestore agent setup --client codex
```

Use `claude` for Claude Code or `cursor` for Cursor. This installs the setup skill and configures MCP for the project. Add `--skills-only` to skip MCP, or `--global` to install for all projects. Restart your client or open a new task to load the skill. Setup does not sign you in.

The skill reads API references bundled with your installed EdgeStore packages. After upgrading the CLI, update the skill with `edgestore agent update --client codex`. This leaves your application packages unchanged.

### MCP only

```sh
edgestore mcp setup --client codex
```

This configures account and project tools without installing the skill.

## Configure manually

Add EdgeStore to your client's project configuration. Merge the entry into an existing config rather than replacing other servers.

<Tabs items={['Codex', 'Claude Code', 'Cursor']}>
  <>
    <Tab value="Codex">
      ```toml  title=".codex/config.toml"
      [mcp_servers.edgestore]
      url = "https://api.edgestore.dev/mcp"
      ```
    </Tab>

    <Tab value="Claude Code">
      ```json  title=".mcp.json"
      {
        "mcpServers": {
          "edgestore": {
            "type": "http",
            "url": "https://api.edgestore.dev/mcp"
          }
        }
      }
      ```
    </Tab>

    <Tab value="Cursor">
      ```json  title=".cursor/mcp.json"
      {
        "mcpServers": {
          "edgestore": {
            "url": "https://api.edgestore.dev/mcp"
          }
        }
      }
      ```
    </Tab>
  </>
</Tabs>

### Sign in

Restart your client after saving the config, then connect EdgeStore:

* Codex requires project trust for `.codex/config.toml`. Run `codex mcp login edgestore`, then use `/mcp` to check the connection.
* In Claude Code, approve the project's MCP configuration, then use `/mcp` to select EdgeStore and sign in.
* In Cursor, open MCP settings and connect the EdgeStore server.

MCP sign-in is separate from `edgestore login`.

After signing in, ask your agent to list your EdgeStore projects to check tool access.

Client instructions: [Codex](https://learn.chatgpt.com/docs/extend/mcp), [Claude Code](https://code.claude.com/docs/en/mcp), and [Cursor](https://prod.cursor.com/help/customization/mcp).

## Give your agent the docs

Start with [Quick start](/docs/quick-start) or the adapter for
[Next.js App or Pages Router](/docs/adapters/next),
[TanStack Start](/docs/adapters/tanstack-start),
[Remix / React Router](/docs/adapters/remix), [Astro](/docs/adapters/astro),
[Hono](/docs/adapters/hono), [Express](/docs/adapters/express), or
[Fastify](/docs/adapters/fastify). React-only applications need a backend for the
server adapter.

* [llms.txt](/llms.txt) lists the docs.
* [llms-full.txt](/llms-full.txt) includes all pages in one Markdown response.
* Add `.md` to a page URL, such as [quick-start.md](/docs/quick-start.md), or use its Copy Markdown button.

Run `edgestore agent context --json` to find installed versions and their local `agent-docs/` references.


# EdgeStore Docs: Backend Client
URL: https://edgestore.dev/docs/backend-client
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/(getting-started)/backend-client.mdx



Sometimes you might want to use the EdgeStore functionality directly from your backend. Things like deleting, uploading or even listing files can be done with the use of the backend client.

## Setup

The router exposes a type-safe backend client through `router.client`. The HTTP
handler and backend client share the same provider. EdgeStore is the default;
chain `.provider(myProvider)` on the router to use a different provider.

Since Next.js doesn't allow exports in the api route, you will need to move your router to an external file.

```ts title="src/lib/edgestore-server.ts"
import { initEdgeStore } from '@edgestore/server';
import { createEdgeStoreNextHandler } from '@edgestore/server/adapters/next/app';

const es = initEdgeStore.create();

export const router = es.router({
  publicFiles: es.fileBucket(),
});

export const handler = createEdgeStoreNextHandler({
  router,
});

export const backendClient = router.client;
```

Then you will need to update your api route to use the exported handler.

```ts title="src/app/api/edgestore/[...edgestore]/route.ts"
import { handler } from '@/lib/edgestore-server';

export { handler as GET, handler as POST };
```

<Callout>
  You can find an example of the backend client usage in the
  [next-advanced](https://github.com/edgestorejs/edgestore/tree/main/examples/next-advanced)
  example.
</Callout>

<Callout type="warn">
  The backend client is privileged. It validates router input and applies file
  type, size, transform, path, and metadata rules, but it does not run
  `accessControl`, `beforeUpload`, or `beforeDelete`. Perform authorization in
  the server code that calls it.
</Callout>

The hosted `edgestore()` provider supports the complete backend client. S3 and
Azure Blob Storage support `upload`, `get`, `delete`, `deleteMany`, and
private-read `createSignedUrl` / `createSignedUrls`, accepting key or URL
references. Unsupported operations, such as listing and confirmation, remain
absent from each provider's client type.

## Backend Upload

You can use the `upload` function to upload files from your backend.

### Upload a text file

The simplest use case would be to just upload a `txt` file:

```ts
const res = await backendClient.publicFiles.upload({
  content: 'some text content',
});
```

### Upload a blob

You can also upload a more complex file using the Blob object. And there are also all the other options available in the normal upload.

```ts
const res = await backendClient.publicFiles.upload({
  content: {
    blob: new Blob(['col1,col2,col2'], { type: 'text/csv' }),
    extension: 'csv',
  },
  options: {
    temporary: true,
  },
  ctx: {
    userId: '123',
    userRole: 'admin',
  },
  input: {
    type: 'post',
  },
  signal,
  onProgress: ({ percentage, phase }) => {
    console.log(phase, `${percentage}%`);
  },
});

console.log(res.id, res.key, res.sizeBytes);
```

### Copy an existing file

You can use an existing file's URL to copy it into the EdgeStore bucket. This can be an external file (from outside of EdgeStore) or an existing EdgeStore file.

```ts
const res = await backendClient.publicFiles.upload({
  content: {
    url: 'https://some-url.com/file.txt',
    extension: 'txt',
  },
});
```

### Transform a file before upload

You can transform backend uploads before EdgeStore validates and uploads them.
The transform receives the resolved `Blob` and extension, and returns the new
`Blob` and extension.

For example, you can use `sharp` to convert an image to WebP before upload:

<CodeBlockTabs defaultValue="npm" groupId="package-manager" persist>
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install sharp
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add sharp
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add sharp
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add sharp
    ```
  </CodeBlockTab>
</CodeBlockTabs>

```ts
import sharp from 'sharp';

const res = await backendClient.publicImages.upload({
  content: {
    url: 'https://some-url.com/image.jpg',
    extension: 'jpg',
  },
  options: {
    transform: async ({ blob }) => {
      const input = Buffer.from(await blob.arrayBuffer());
      const output = await sharp(input).webp({ quality: 80 }).toBuffer();

      return {
        blob: new Blob([output], { type: 'image/webp' }),
        extension: 'webp',
      };
    },
  },
});
```

### Confirm a temporary file upload

Save the upload result's ID/key and URL in your database, then confirm the
temporary file. Hosted EdgeStore accepts confirmation during processing; a
preceding `get()` is unnecessary and can return 404 until processing finishes.
If saving fails, leave the file temporary.

```ts
const res = await backendClient.publicFiles.confirm({
  id: file.id,
});
```

File operations accept a stable file ID, storage key, or URL. Singular
operations throw `EdgeStoreFileMutationError` when that file fails. Use the
plural form when partial success should be preserved:

```ts
const result = await backendClient.publicFiles.confirmMany({
  refs: [{ id: first.id }, { key: second.key }],
});

for (const failure of result.failed) {
  console.error(failure.ref, failure.error.code);
}
```

## Backend Delete

You can use the `delete` function to delete files from your backend.

```ts
const res = await backendClient.publicFiles.delete({
  id: file.id,
});
```

`deleteMany`, `restore`, and `restoreMany` use the same singular and
partial-batch semantics.

## Backend List Files (search)

You can use the `list` function to list files from your backend. It's also possible to filter the results by path, metadata or upload timing.

```ts
// simple usage
// get the first 20 files in the bucket
const res = await backendClient.publicFiles.list();

// with filter and pagination
const res = await backendClient.publicFiles.list({
  filter: {
    metadata: {
      role: 'admin',
    },
    path: {
      type: 'post',
    },
    uploadedAt: {
      gt: new Date(Date.now() - 1000 * 60 * 60 * 24 * 7), // past 7 days
    },
  },
  cursor: 'cursor-from-previous-response',
  limit: 50, // default: 20 (max: 100)
});

for (const file of res.items) {
  console.log(file.id, file.url);
}

if (res.hasMore) {
  console.log('Next cursor:', res.nextCursor);
}
```

## Private read URLs

Providers with signed-read support expose `createSignedUrl` on protected
buckets:

```ts
const access = await backendClient.privateFiles.createSignedUrl({
  url: { id: file.id },
  expiresIn: 15 * 60,
});

console.log(access.signedUrl, access.expiresAt);
```

Use `createSignedUrls` to sign several references in one provider call.

## Reusing backend client types

Derive a single method's exact input or output directly from the configured
client:

```ts
type UploadInput = Parameters<
  typeof router.client.publicFiles.upload
>[0];

type UploadOutput = Awaited<
  ReturnType<typeof router.client.publicFiles.upload>
>;
```

This includes the router's context, input, path, and metadata configuration and
the provider's file and reference types.

Use `InferClientInputs` and `InferClientOutputs` when you need a reusable map of
every bucket and method:

```ts title="src/lib/edgestore-server.ts"
import type {
  InferClientInputs,
  InferClientOutputs,
} from '@edgestore/server';

export type BackendInputs = InferClientInputs<typeof router>;
export type BackendOutputs = InferClientOutputs<typeof router>;

type UploadInput = BackendInputs['publicFiles']['upload'];
type UploadOutput = BackendOutputs['publicFiles']['upload'];
```

The helpers infer capabilities and provider-specific types directly from the
router, including custom providers. Use `EdgeStoreClient<typeof router>` for
the complete backend client type.


# EdgeStore Docs: Configuration
URL: https://edgestore.dev/docs/configuration
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/(getting-started)/configuration.mdx



## Router and Provider

Import `initEdgeStore` from `@edgestore/server`. The router uses the hosted
EdgeStore provider by default and exposes its backend client as `router.client`:

```ts
const es = initEdgeStore.create();
const router = es.router({
  publicFiles: es.fileBucket(),
});

const handler = createEdgeStoreNextHandler({ router });
const backendClient = router.client;
```

Chain `.provider()` to use another provider or custom credentials:

```ts
import { s3 } from '@edgestore/server/providers/s3';

const router = es.router({
  publicFiles: es.fileBucket(),
}).provider(s3());
```

`.provider()` returns a new router. It preserves bucket definitions, while
leaving existing routers, clients, and handlers bound to their original
provider. The backend client exposes only methods supported by the
selected provider.

The default hosted provider is initialized when handling requests or when
`router.client` is first accessed. Defining a router or overriding its provider
does not require hosted EdgeStore credentials. Each router reuses its provider
and backend client after initialization.

Keep the router object on the server; import only its type into frontend code.

## Bucket Types

There are two types of file buckets: `IMAGE` and `FILE`. Both types of buckets work basically the same way, but the `IMAGE` bucket only accepts [certain mime types](#image-bucket-accepted-mime-types).

IMAGE buckets automatically generate a thumbnail version of the image file if the file is bigger than 200px in width or height. In case a thumbnail was generated, the url will be included in the response of the upload request.

```ts
const router = es.router({
  publicFiles: es.fileBucket(),
  publicImages: es.imageBucket(),
});
```

## Basic File Validation

You can set the maximum file size and the accepted mime types for every file bucket.

```ts
const router = es.router({
  publicFiles: es.fileBucket({
    maxSize: 1024 * 1024 * 10, // 10MB
    accept: ['image/jpeg', 'image/png'], // wildcard also works: ['image/*']
  }),
});
```

## Context

Many of the functions that you can use to configure your file buckets receive a `context` object as an argument. This object is generated by the `createContext` function that you pass to your router configuration.

```ts
import { initEdgeStore } from '@edgestore/server';
import {
  type CreateContextOptions,
  createEdgeStoreNextHandler,
} from '@edgestore/server/adapters/next/app';
import { z } from 'zod';

type Context = {
  userId: string;
  userRole: 'admin' | 'user';
};

async function createContext({ req }: CreateContextOptions): Promise<Context> {
  const { id, role } = await getUserSession(req); // replace with your own session logic

  return {
    userId: id,
    userRole: role,
  };
}

const es = initEdgeStore.context<Context>().create();

// ...

export default createEdgeStoreNextHandler({
  router,
  /**
   * The context is generated and saved to a cookie
   * in the first load of the page.
   */
  createContext,
});
```

You might need to refresh the context (e.g. when the user logs in or logs out). You can do this by calling the `reset` function from the `useEdgeStore` hook.

```tsx
const { edgestore, reset } = useEdgeStore();

async function runAfterAuthChange() {
  await reset(); // this will re-run the createContext function
}
```

## Metadata & File Path

Every uploaded file can hold two types of data: `metadata` and `path`. You can use this data for access control or for filtering files. The `metadata` and `path` can be generated from the context (`ctx`) or from the `input` of the upload request.

<Callout type="info">
  The `.input()` method accepts any object schema that implements [Standard
  Schema](https://standardschema.dev/), including schemas from Zod, Valibot,
  and ArkType.
</Callout>

```ts
import { initEdgeStore } from '@edgestore/server';
import {
  type CreateContextOptions,
  createEdgeStoreNextHandler,
} from '@edgestore/server/adapters/next/app';
import { z } from 'zod';

type Context = {
  userId: string;
  userRole: 'admin' | 'user';
};

async function createContext({ req }: CreateContextOptions): Promise<Context> {
  const { id, role } = await getUserSession(req); // replace with your own session logic

  return {
    userId: id,
    userRole: role,
  };
}

const es = initEdgeStore.context<Context>().create();

const router = es.router({
  publicFiles: es
    .fileBucket()
    // this input will be required for every upload request
    .input(
      z.object({
        category: z.string(),
      }),
    )
    // e.g. /publicFiles/{category}/{author}
    .path(({ ctx, input }) => [
      { category: input.category },
      { author: ctx.userId },
    ])
    // this metadata will be added to every file in this bucket
    .metadata(({ ctx, input }) => ({
      userRole: ctx.userRole,
    })),
});
```

## Lifecycle Hooks

You can use the `beforeUpload` and `beforeDelete` hooks to allow or deny file uploads and deletions. The `beforeDelete` hook must be defined if you want to delete files directly from the client.

```ts
import { initEdgeStore } from '@edgestore/server';
import {
  type CreateContextOptions,
  createEdgeStoreNextHandler,
} from '@edgestore/server/adapters/next/app';
import { z } from 'zod';

type Context = {
  userId: string;
  userRole: 'admin' | 'user';
};

async function createContext({ req }: CreateContextOptions): Promise<Context> {
  const { id, role } = await getUserSession(req); // replace with your own session logic

  return {
    userId: id,
    userRole: role,
  };
}

const es = initEdgeStore.context<Context>().create();

const router = es.router({
  publicFiles: es
    .fileBucket()
    /**
     * return `true` to allow upload
     * By default every upload from your app is allowed.
     */
    .beforeUpload(({ ctx, input, fileInfo }) => {
      console.log('beforeUpload', ctx, input, fileInfo);
      return true; // allow upload
    })
    /**
     * return `true` to allow delete
     * This function must be defined if you want to delete files directly from the client.
     */
    .beforeDelete(({ ctx, fileInfo }) => {
      console.log('beforeDelete', ctx, fileInfo);
      return true; // allow delete
    }),
});
```

## Access Control (Experimental)

You can use the `accessControl` function to add bucket level logic to allow or deny access to files. If you have ever used Prisma, you will probably notice that the structure of the `accessControl` function is similar to how you would write a Prisma query.

If you set the `accessControl` function, your bucket will automatically be configured as a **protected bucket**. You cannot change a protected bucket to a public bucket after it has been created. The opposite is also true, you cannot change a public bucket to a protected bucket.

To access files from a **protected bucket** the user will need a specific encrypted cookie generated in your server by the EdgeStore package. Which means that they will only be able to access the files from within your app. Sharing the url of a protected file will not work.

The access control check is performed on an edge function without running any database queries, so you won't need to worry about bad performance on your protected files.

```ts
const filesBucket = es
  .fileBucket()
  .path(({ ctx }) => [{ author: ctx.userId }])
  .accessControl({
    OR: [
      {
        // this will make sure that only the author of the file can access it
        userId: { path: 'author' },
      },
      {
        // or if the user is an admin
        userRole: {
          eq: 'admin',
        }, // same as { userRole: 'admin' }
      },
    ],
  });
```

Other available operators are: `eq`, `not`, `gt`, `gte`, `lt`, `lte`, `in`, `contains`

<Callout>
  The access control functionality uses a partitioned cookie that EdgeStore sets on the file origin when the provider initializes. Protected files load directly from that origin, including in local development.

  The `<Image />` component from `next/image` does not forward the cookies in the request, so protected images won't be displayed. You will need to use the `<img />` tag instead.
</Callout>

## Limit parallel uploads

When creating the provider, you can set the maximum number of concurrent uploads.
EdgeStore's context provider will take care of queuing the uploads and will automatically upload the next file when the previous one is finished.

```ts
const { EdgeStoreProvider, useEdgeStore } =
  createEdgeStoreProvider<EdgeStoreRouter>({
    maxConcurrentUploads: 5, // default is 5
  });
```

## Base Path

In case your app is not hosted at the root of your domain, you can specify the base path.
If you set this, make sure to set the full path to the EdgeStore API.
e.g. `/my-app/api/edgestore` or `https://example.com/my-app/api/edgestore`

```tsx
export default function App({ Component, pageProps }: AppProps) {
  return (
    <EdgeStoreProvider basePath="/my-app/api/edgestore">
      <Component {...pageProps} />
    </EdgeStoreProvider>
  );
}
```

## IMAGE bucket accepted mime types

| mime type     |
| ------------- |
| image/jpeg    |
| image/png     |
| image/gif     |
| image/webp    |
| image/svg+xml |
| image/tiff    |
| image/bmp     |
| image/x-icon  |


# EdgeStore Docs: Error Handling
URL: https://edgestore.dev/docs/error-handling
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/(getting-started)/error-handling.mdx



You might need to handle specific server errors in your application. Here is an example of how you can do that.

```tsx
import {
  EdgeStoreApiClientError,
  UploadAbortedError,
  UploadCanceledError,
  UploadProcessingTimeoutError,
} from '@edgestore/react/errors';

// ...

<button
  onClick={async () => {
    try {
      if (file) {
        const res = await edgestore.publicFiles.upload({
          file,
          options: { waitForProcessing: true },
        });
      }
    } catch (error) {
      // All errors are typed and you will get intellisense for them
      if (error instanceof EdgeStoreApiClientError) {
        // if it fails due to the `maxSize` set in the router config
        if (error.data.code === 'FILE_TOO_LARGE') {
          alert(
            `File too large. Max size is ${formatFileSize(
              error.data.details.maxFileSize,
            )}`,
          );
        }
        // if it fails due to the `accept` set in the router config
        if (error.data.code === 'MIME_TYPE_NOT_ALLOWED') {
          alert(
            `File type not allowed. Allowed types are ${error.data.details.allowedMimeTypes.join(
              ', ',
            )}`,
          );
        }
        // if it fails during the `beforeUpload` check
        if (error.data.code === 'UPLOAD_NOT_ALLOWED') {
          alert("You don't have permission to upload files here.");
        }
      } else if (error instanceof UploadAbortedError) {
        // if the upload was canceled from an AbortController's signal
        console.log('Upload aborted');
      } else if (error instanceof UploadCanceledError) {
        // if EdgeStore could not process the uploaded file
        alert('This file could not be processed.');
      } else if (error instanceof UploadProcessingTimeoutError) {
        // if processing outlasted `waitForProcessing.timeoutMs`;
        // the file may still finish processing
        console.log('Still processing', error.id);
      } else {
        // unknown error
        console.error(error);
      }
    }
  }}
  disabled={!file || !!uploadedUrl}
>
  Upload
</button>
```

## Error Codes

* `BAD_REQUEST`
* `FILE_TOO_LARGE`
* `MIME_TYPE_NOT_ALLOWED`
* `UNAUTHORIZED`
* `UPLOAD_NOT_ALLOWED`
* `DELETE_NOT_ALLOWED`
* `CREATE_CONTEXT_ERROR`
* `SERVER_ERROR`

## File mutation errors

`confirm` and `delete` throw `EdgeStoreFileMutationError` when the provider
rejects that file. It carries the provider error `code`, the `message`, and the
`fileRef` it applied to. `confirmMany` and `deleteMany` do not throw for
per-file failures; inspect the returned `failed` list instead.

```ts
import { EdgeStoreFileMutationError } from '@edgestore/react/errors';

try {
  await edgestore.publicFiles.delete({ url });
} catch (error) {
  if (error instanceof EdgeStoreFileMutationError) {
    console.error(error.code, error.fileRef.url);
  }
}
```

`EdgeStoreClientError` reports client-side failures, such as an EdgeStore API
route that does not return JSON.


# EdgeStore Docs: Logging
URL: https://edgestore.dev/docs/logging
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/(getting-started)/logging.mdx



The EdgeStore package outputs some logs on the server-side. You can configure the log level by passing the `logLevel` option when creating the api handler. You can set it to `debug` to see in more details what is happening in the server.

```ts
const handler = createEdgeStoreNextHandler({
  logLevel: 'debug', // optional. defaults to 'error' in production and 'info' in development
  router,
});
```

## Log Levels

* `debug`
* `info`
* `warn`
* `error`
* `none`


# EdgeStore Docs: Migrate to v1
URL: https://edgestore.dev/docs/migrate-to-v1
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/(getting-started)/migrate-to-v1.mdx



EdgeStore v1 is a deliberate major-version redesign. The browser router DX is
largely unchanged, while direct API and privileged backend code now use API v2
semantics without a runtime v1 fallback.

## Runtime and packages

* All packages are ESM-only and require Node.js 22.22.0 or newer.
* Zod is no longer a peer dependency. Bucket `input` accepts any
  [Standard Schema](https://standardschema.dev) library, including Zod,
  Valibot, and ArkType.
* `@edgestore/server/core` is removed. Import types such as
  `InferClientOutputs` from `@edgestore/server`.
* `@edgestore/react/shared` is removed. Import errors from
  `@edgestore/react/errors`.

## Configure EdgeStore once

The HTTP handler and backend client now share the router's provider. The hosted
provider is the default, so the basic handler setup stays the same. Replace
`initEdgeStoreClient({ router })` with `router.client`, and configure custom
providers by chaining `.provider(myProvider)` on `es.router(...)`.

```ts title="Before"
import { initEdgeStore } from '@edgestore/server';
import { createEdgeStoreNextHandler } from '@edgestore/server/adapters/next/app';
import { initEdgeStoreClient } from '@edgestore/server/core';

const es = initEdgeStore.create();
const router = es.router({
  documents: es.fileBucket(),
});

export const handler = createEdgeStoreNextHandler({
  router,
});

export const backendClient = initEdgeStoreClient({
  router,
});
```

```ts title="After"
import { initEdgeStore } from '@edgestore/server';
import { createEdgeStoreNextHandler } from '@edgestore/server/adapters/next/app';

const es = initEdgeStore.create();
const router = es.router({
  documents: es.fileBucket(),
});

export const handler = createEdgeStoreNextHandler({
  router,
});

export const backendClient = router.client;
```

## Breaking changes

| v0.8                                        | v1                                           | Required change                                             |
| ------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------- |
| Separate handler and client config          | `es.router(...).provider(...)`               | Configure the router and provider once.                     |
| `initEdgeStoreClient`                       | `router.client`                              | Read the client from the configured router.                 |
| `InferClientResponse`                       | `InferClientOutputs`                         | Rename the type helper.                                     |
| `EdgeStoreProvider()`                       | `edgestore()`                                | Import from `@edgestore/server/providers/edgestore`.        |
| `AWSProvider()` from `providers/aws`        | `s3()` from `providers/s3`                   | Update the import and pass it to `.provider(...)`.          |
| `AzureProvider()` from `providers/azure`    | `azureBlob()` from `providers/azure-blob`    | Update the import and pass it to `.provider(...)`.          |
| S3 `accessKeyId` / `secretAccessKey`        | S3 `credentials`                             | Pass credentials or keep `ES_AWS_*` variables.              |
| S3 `overwritePath`                          | S3 `path`                                    | Return a key relative to the router bucket.                 |
| URL-only identity                           | `{ id }`, `{ key }`, or `{ url }`            | Prefer stable IDs in new code.                              |
| Predicted upload result                     | Canonical processed file                     | Use `sizeBytes`, `id`, `key`, and the returned timestamps.  |
| `{ pagination: { currentPage, pageSize } }` | `{ cursor, limit }`                          | Replace page numbers with explicit cursor continuation.     |
| `result.data`                               | `result.items`                               | Read canonical file records from `items`.                   |
| `{ success: boolean }`                      | Singular result or partial batch             | Catch singular errors or inspect `failed`.                  |
| React `confirmUpload`                       | React `confirm`                              | Use the resource-scoped lifecycle name.                     |
| React upload `uploadedAt`                   | Removed                                      | Read timestamps from the backend client when needed.        |
| React `disableDevProxy`, `/proxy-file`      | Removed                                      | Protected files load from their file origin in development. |
| `cookieConfig.token`                        | Removed                                      | The `edgestore-token` cookie is no longer set.              |
| Backend `getFile`                           | Backend `get`                                | Use the bucket-scoped read name.                            |
| Backend `listFiles`                         | Backend `list`                               | Use the bucket-scoped list name.                            |
| Backend `confirmUpload`                     | Backend `confirm`                            | Use the singular lifecycle name.                            |
| Backend `confirmUploads`                    | Backend `confirmMany`                        | Use the `Many` suffix for batches.                          |
| Backend `deleteFile`                        | Backend `delete`                             | Use the singular lifecycle name.                            |
| Backend `deleteFiles`                       | Backend `deleteMany`                         | Use the `Many` suffix for batches.                          |
| Backend `restoreFile(s)`                    | Backend `restore` / `restoreMany`            | Use singular and `Many` lifecycle names.                    |
| Backend `getSignedUrl`                      | Backend `createSignedUrl`                    | Make signed-URL creation explicit.                          |
| Backend `getSignedUrls`                     | Backend `createSignedUrls`                   | Make batch signed-URL creation explicit.                    |
| Nullable metadata values                    | Nullish values omitted                       | Treat those inferred keys as optional strings.              |
| Handcrafted server raw client               | `@edgestore/sdk`                             | Migrate direct API consumers to the public SDK.             |
| `ES_AZURE_SAS_TOKEN` / `sasToken`           | `ES_AZURE_ACCOUNT_KEY` / `storageAccountKey` | Give Azure signing authority only to the server.            |
| Azure `customBaseUrl` / `ES_AZURE_BASE_URL` | `endpoint` / `ES_AZURE_ENDPOINT`             | Use `baseUrl` separately for file URLs, such as a CDN.      |

Pagination is no longer page-number based. Continue only when your application
intentionally needs another page:

```ts title="Before (v0.8)"
const page = await backendClient.documents.listFiles({
  pagination: {
    currentPage: 1,
    pageSize: 50,
  },
});
```

```ts title="After (v1)"
const firstPage = await backendClient.documents.list({ limit: 50 });

const secondPage = firstPage.hasMore
  ? await backendClient.documents.list({
      cursor: firstPage.nextCursor ?? undefined,
      limit: 50,
    })
  : undefined;
```

```ts
const page = await backendClient.documents.list({ limit: 50 });

const deleted = await backendClient.documents.deleteMany({
  refs: page.items.map((file) => ({ id: file.id })),
});

for (const failure of deleted.failed) {
  console.error(failure.ref, failure.error.code);
}
```

Frontend route bodies and bucket input are now validated before any router hook
or provider method runs. v0.8 did not validate upload input on the server, so
requests that passed before can now fail with `BAD_REQUEST`. Hooks, paths, and
metadata receive the schema's parsed output. The encrypted `edgestore-ctx`
payload is also namespaced in v1; there is no decoder fallback for a v0.8
context cookie, so clients must complete the normal `/init` request after
deployment.

Azure users must replace the reusable SAS token with the storage account key.
The provider now derives short-lived create/write upload URLs and independent
read-only URLs for private files. Canonical file URLs never include the
credential query string.

## Provider capabilities

Every provider is defined through the same resource-oriented contract. The
router backend client exposes exactly the methods present on that provider:

| Provider             | Router backend client                    | Adapter upload/delete | API v2 calls             |
| -------------------- | ---------------------------------------- | --------------------- | ------------------------ |
| Hosted `edgestore()` | Full support                             | Full support          | Through `@edgestore/sdk` |
| `s3()`               | Upload, get, delete, and signed reads    | Full support          | Never                    |
| `azureBlob()`        | Upload, get, delete, and signed reads    | Full support          | Never                    |
| Custom provider      | Inferred from its `defineProvider` shape | Provider-defined      | Provider-defined         |

Omitted capabilities are absent from TypeScript and are not replaced by a
runtime fallback to the hosted API.

## Staying on v0.8

v0.8 remains installable for applications that cannot migrate yet. Pin
`@edgestore/server` and `@edgestore/react` to `^0.8.0` until you are ready.


# EdgeStore Docs: Quick Start
URL: https://edgestore.dev/docs/quick-start
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/(getting-started)/quick-start.mdx



## Set up with your agent

<AgentPrompt>
  Read [https://edgestore.dev/SKILL.md](https://edgestore.dev/SKILL.md) and add file uploads to this application.
</AgentPrompt>

[Install the skill or connect MCP](/docs/agents).

<SetupGuide>
  ## Next.js Setup

  ### Install

  <CodeBlockTabs defaultValue="npm" groupId="package-manager" persist>
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="npm">
        npm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="pnpm">
        pnpm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="yarn">
        yarn
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="bun">
        bun
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="npm">
      ```bash
      npm install @edgestore/server@rc @edgestore/react@rc
      ```
    </CodeBlockTab>

    <CodeBlockTab value="pnpm">
      ```bash
      pnpm add @edgestore/server@rc @edgestore/react@rc
      ```
    </CodeBlockTab>

    <CodeBlockTab value="yarn">
      ```bash
      yarn add @edgestore/server@rc @edgestore/react@rc
      ```
    </CodeBlockTab>

    <CodeBlockTab value="bun">
      ```bash
      bun add @edgestore/server@rc @edgestore/react@rc
      ```
    </CodeBlockTab>
  </CodeBlockTabs>

  ### Environment Variables

  Copy your project's keys from the [dashboard](https://dashboard.edgestore.dev) to the backend env file:

  ```sh title=".env.local"
  EDGESTORE_ACCESS_KEY=your-access-key
  EDGESTORE_SECRET_KEY=your-secret-key
  ```

  <Callout type="warning">
    Use the app's existing env file, or `.env.local` for a new app. Keep it gitignored.
  </Callout>

  ### Backend

  Choose your router below. This bucket's files are accessible to anyone with the link.

  <Tabs items={['app', 'pages']} groupId="next-router">
    <>
      <Tab value="app">
        ```ts  title="src/app/api/edgestore/[...edgestore]/route.ts"
        import { initEdgeStore } from '@edgestore/server';
        import { createEdgeStoreNextHandler } from '@edgestore/server/adapters/next/app';

        const es = initEdgeStore.create();

        /**
         * This is the main router for the EdgeStore buckets.
         */
        const router = es.router({
          publicFiles: es.fileBucket(),
        });

        const handler = createEdgeStoreNextHandler({
          router,
        });

        export { handler as GET, handler as POST };

        /**
         * This type is used to create the type-safe client for the frontend.
         */
        export type EdgeStoreRouter = typeof router;
        ```
      </Tab>

      <Tab value="pages">
        ```ts  title="src/pages/api/edgestore/[...edgestore].ts"
        import { initEdgeStore } from '@edgestore/server';
        import { createEdgeStoreNextHandler } from '@edgestore/server/adapters/next/pages';

        const es = initEdgeStore.create();

        /**
         * This is the main router for the edgestore buckets.
         */
        const router = es.router({
          publicFiles: es.fileBucket(),
        });

        export default createEdgeStoreNextHandler({
          router,
        });

        /**
         * This type is used to create the type-safe client for the frontend.
         */
        export type EdgeStoreRouter = typeof router;
        ```
      </Tab>
    </>
  </Tabs>

  ### Frontend

  Create the React provider:

  <Tabs items={['app', 'pages']} groupId="next-router">
    <>
      <Tab value="app">
        ```ts  title="src/lib/edgestore.ts"
        'use client';

        import { createEdgeStoreProvider } from '@edgestore/react';
        import { type EdgeStoreRouter } from '../app/api/edgestore/[...edgestore]/route';

        const { EdgeStoreProvider, useEdgeStore } =
          createEdgeStoreProvider<EdgeStoreRouter>();

        export { EdgeStoreProvider, useEdgeStore };
        ```
      </Tab>

      <Tab value="pages">
        ```ts  title="src/lib/edgestore.ts"
        'use client';

        import { createEdgeStoreProvider } from '@edgestore/react';
        import { type EdgeStoreRouter } from '../pages/api/edgestore/[...edgestore]';

        const { EdgeStoreProvider, useEdgeStore } =
          createEdgeStoreProvider<EdgeStoreRouter>();

        export { EdgeStoreProvider, useEdgeStore };
        ```
      </Tab>
    </>
  </Tabs>

  Wrap your app with the provider:

  <Tabs items={['app', 'pages']} groupId="next-router">
    <>
      <Tab value="app">
        ```tsx  title="src/app/layout.tsx"
        // [!code ++]
        import { EdgeStoreProvider } from '../lib/edgestore';
        import './globals.css';

        // ...

        export default function RootLayout({
          children,
        }: {
          children: React.ReactNode;
        }) {
          return (
            <html lang="en">
              <body>
                {/* [!code ++] */}
                <EdgeStoreProvider>{children}</EdgeStoreProvider>
              </body>
            </html>
          );
        }
        ```
      </Tab>

      <Tab value="pages">
        ```tsx  title="src/pages/_app.tsx"
        import '../styles/globals.css';
        import type { AppProps } from 'next/app';
        // [!code ++]
        import { EdgeStoreProvider } from '../lib/edgestore';

        export default function App({ Component, pageProps }: AppProps) {
          return (
            <EdgeStoreProvider>
              <Component {...pageProps} />
            </EdgeStoreProvider>
          );
        }
        ```
      </Tab>
    </>
  </Tabs>

  ### Upload file

  You can use the `useEdgeStore` hook to access type-safe frontend client and use it to upload files.

  ```tsx
  'use client';

  import * as React from 'react';
  import { useEdgeStore } from '../lib/edgestore';

  export default function Page() {
    const [file, setFile] = React.useState<File>();
    const { edgestore } = useEdgeStore();

    return (
      <div>
        <input
          type="file"
          onChange={(e) => {
            setFile(e.target.files?.[0]);
          }}
        />
        <button
          onClick={async () => {
            if (file) {
              const res = await edgestore.publicFiles.upload({
                file,
                onProgressChange: (progress) => {
                  // you can use this to show a progress bar
                  console.log(progress);
                },
              });
              // you can run some server action or api here
              // to save `res.id` and `res.url` in your database
              console.log(res);
            }
          }}
        >
          Upload
        </button>
      </div>
    );
  }
  ```

  ### Replace file

  By passing the `replaceTargetUrl` option, you can replace an existing file with a new one.
  It will automatically delete the old file after the upload is complete.

  You can also just upload the file using the same file name, but in that case, you might still see the old file for a while because of the CDN cache.

  ```tsx
  const res = await edgestore.publicFiles.upload({
    file,
    // [!code ++:3]
    options: {
      replaceTargetUrl: oldFileUrl,
    },
  });
  ```

  ### Delete file

  You can delete a file by passing its URL to the `delete` method.

  To be able to delete a file from a client component like this, you will need to set the `beforeDelete` [lifecycle hook](/docs/configuration#lifecycle-hooks) on the bucket.

  ```tsx
  await edgestore.publicFiles.delete({
    url: urlToDelete,
  });
  ```

  Use `deleteMany` to send one request for multiple files. Storage failures are
  reported per URL:

  ```tsx
  const result = await edgestore.publicFiles.deleteMany({
    urls: selectedFiles.map((file) => file.url),
  });

  for (const failure of result.failed) {
    console.error(failure.url, failure.error.code);
  }
  ```

  EdgeStore runs `beforeDelete` for every file before deleting any of them. If
  one file is unauthorized, the entire request is rejected without calling the
  storage provider. Once authorization succeeds, the provider may still return
  partial storage failures in `result.failed`.

  ### Cancel upload

  To cancel an ongoing file upload, you can use an AbortController the same way you would use it to cancel a fetch request.

  ```tsx
  // prepare a state for the AbortController
  const [abortController, setAbortController] = useState<AbortController>();

  // ...

  // instantiate the AbortController and add the signal to the upload method
  const abortController = new AbortController();
  setAbortController(abortController);
  const res = await edgestore.publicFiles.upload({
    file,
    signal: abortController.signal,
  });

  // ...

  // to cancel the upload, call the controller's abort method
  abortController?.abort();
  ```

  <Callout>
    When you cancel an upload, an `UploadAbortedError` will be thrown. <br />
    You can catch this error and handle it as needed. <br />
    For more information, check the [Error Handling](/docs/error-handling) page.
  </Callout>

  ### Transform files before upload

  You can transform a file before EdgeStore validates and uploads it by passing
  the `transform` option. If the transform keeps the same extension, you can
  return the transformed `File` or `Blob` directly. If the transform changes the
  file type, return the transformed file with its new extension.

  For example, you can convert JPEG and PNG images to WebP before upload:

  <CodeBlockTabs defaultValue="npm" groupId="package-manager" persist>
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="npm">
        npm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="pnpm">
        pnpm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="yarn">
        yarn
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="bun">
        bun
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="npm">
      ```bash
      npm install browser-image-compression
      ```
    </CodeBlockTab>

    <CodeBlockTab value="pnpm">
      ```bash
      pnpm add browser-image-compression
      ```
    </CodeBlockTab>

    <CodeBlockTab value="yarn">
      ```bash
      yarn add browser-image-compression
      ```
    </CodeBlockTab>

    <CodeBlockTab value="bun">
      ```bash
      bun add browser-image-compression
      ```
    </CodeBlockTab>
  </CodeBlockTabs>

  ```tsx
  import imageCompression from 'browser-image-compression';

  const res = await edgestore.publicImages.upload({
    file,
    options: {
      transform: async ({ file, extension, signal }) => {
        if (!['image/jpeg', 'image/png'].includes(file.type)) {
          return { file, extension };
        }

        const compressedFile = await imageCompression(file, {
          fileType: 'image/webp',
          initialQuality: 0.8,
          useWebWorker: true,
          signal,
        });

        return {
          file: compressedFile,
          extension: 'webp',
        };
      },
    },
  });
  ```

  If you provide `manualFileName`, EdgeStore will use that exact file name. Make
  sure the file name extension matches the transformed file type.

  ### Temporary files

  You can upload temporary files by passing the `temporary` option to the `upload` method.
  Temporary files will be automatically deleted after 24 hours if they are not confirmed.

  ```tsx
  await edgestore.publicFiles.upload({
    file: fileToUpload,
    // [!code ++:3]
    options: {
      temporary: true,
    },
  });
  ```

  For forms, upload files as temporary and save their returned IDs/keys and URLs
  with your record before confirming them. If the database save fails, leave the
  files temporary. Confirmation does not require waiting for hosted processing.

  Use the `confirm` method after saving:

  ```tsx
  await edgestore.publicFiles.confirm({
    url: urlToConfirm,
  });
  ```

  To confirm several temporary files in one request, use `confirmMany`:

  ```tsx
  const result = await edgestore.publicFiles.confirmMany({
    urls: temporaryFiles.map((file) => file.url),
  });
  ```

  <Callout>
    You can check if a file is temporary in the dashboard. <br />
    Temporary files are marked with a clock icon.
  </Callout>

  ### Wait for processing

  `upload` resolves as soon as the file is transferred. EdgeStore then processes
  it in the background, for example to generate an image thumbnail. The file ID
  and URL are final right away, so most apps can save them without waiting.

  When you need processed details immediately, such as whether the image got a
  thumbnail, pass `waitForProcessing`. The upload then resolves with the
  processed file, including freshly signed URLs for buckets with
  `autoSignedUrls`, and `onPhaseChange` tells you when the transfer finishes and
  processing begins.

  ```tsx
  const res = await edgestore.publicImages.upload({
    file,
    onProgressChange: (progress) => setProgress(progress),
    // [!code ++:6]
    onPhaseChange: (phase) => {
      if (phase === 'processing') setStatus('Processing…');
    },
    options: {
      waitForProcessing: true, // or { timeoutMs: 120_000 }
    },
  });
  ```

  Processing failures reject with `UploadCanceledError`. If processing takes
  longer than `timeoutMs` (60 seconds by default), the upload rejects with
  `UploadProcessingTimeoutError`; the file may still finish processing. Both
  errors include the file `id`. See [Error Handling](/docs/error-handling).

  Waiting for processing does not confirm a [temporary file](#temporary-files).
  Confirm it separately once your app decides to keep it.

  Providers without background processing, such as S3 and Azure Blob, resolve
  once the transfer completes.
</SetupGuide>

## Troubleshooting

If you have any problems using EdgeStore, please check the [Troubleshooting](./troubleshooting) page.

## FAQ

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

<Accordions type="single">
  <Accordion title="What is EdgeStore?" id="what-is-edgestore">
    EdgeStore is a type-safe file upload solution for React applications. It
    provides an easy-to-use API for uploading, managing, and serving files with
    features like progress tracking, file validation, and automatic cleanup of
    temporary files.
  </Accordion>

  <Accordion title="Can I use EdgeStore for free?" id="is-edgestore-free">
    Yes! The EdgeStore Provider has a free plan with generous limits, so you can
    get started without any cost. You can also use EdgeStore with your own
    infrastructure (like AWS S3 or Azure Blob Storage) if you prefer to manage
    your own storage.
  </Accordion>

  <Accordion title="Is EdgeStore open source?" id="is-open-source">
    The EdgeStore packages (`@edgestore/server`, `@edgestore/react`, etc.) are
    open source and released under the MIT license. However, the EdgeStore
    Provider (cloud service) is not open source.
  </Accordion>

  <Accordion title="Which frameworks are supported?" id="supported-frameworks">
    EdgeStore supports multiple frameworks including Next.js (App Router and Pages
    Router), Astro, Express, Fastify, Hono, Remix, and TanStack Start. Check the
    [Adapters](/docs/adapters/next) section for setup guides.
  </Accordion>

  <Accordion title="What file types and sizes are supported?" id="file-validation">
    By default, EdgeStore accepts most common file types. You can customize
    allowed file types and maximum file sizes per bucket using the `accept` and
    `maxSize` options. See the [Configuration](/docs/configuration) page for
    details.
  </Accordion>

  <Accordion title="Can I use my own storage provider?" id="custom-provider">
    Yes! EdgeStore supports AWS S3, Azure Blob Storage, and custom providers in
    addition to EdgeStore Cloud. Check the [Providers](/docs/providers/edgestore)
    section for setup instructions.
  </Accordion>

  <Accordion title="Can I use EdgeStore for streaming videos or audio?" id="streaming-large-files">
    EdgeStore is not recommended for real-time streaming of large files like
    videos and audio. It's optimized for file uploads and serving static files,
    not for streaming use cases. For video/audio streaming, consider using a
    dedicated streaming service or CDN.
  </Accordion>
</Accordions>


# EdgeStore Docs: Low-level SDK
URL: https://edgestore.dev/docs/sdk
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/(getting-started)/sdk.mdx



`@edgestore/sdk` is the public, low-level client for EdgeStore API v2. Use it
when you need API operations that are not tied to an EdgeStore router. For
router-derived bucket names, input, path, and metadata types, use the
[backend client](/docs/backend-client) instead.

<Callout type="warn">
  The SDK is server-only. Project secrets and management tokens must never be
  included in browser bundles.
</Callout>

## Install

<CodeBlockTabs defaultValue="npm" groupId="package-manager" persist>
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @edgestore/sdk@rc
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @edgestore/sdk@rc
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @edgestore/sdk@rc
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @edgestore/sdk@rc
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Project client

Project credentials expose runtime operations for the credential's current
project. The reserved project selector is handled internally.

```ts
import { createEdgeStoreSdk } from '@edgestore/sdk';

const sdk = createEdgeStoreSdk({
  credentials: {
    accessKey: process.env.EDGESTORE_ACCESS_KEY!,
    secretKey: process.env.EDGESTORE_SECRET_KEY!,
  },
});

const file = await sdk.runtime.uploads.upload({
  bucket: 'documents',
  source: pdfBlob,
  fileName: 'invoice.pdf',
  metadata: { invoiceId: invoice.id },
  signal,
  onProgress: ({ percentage, phase }) => {
    console.log(phase, percentage);
  },
});
```

The upload helper selects single or multipart upload automatically, reports
progress, supports cancellation, and waits for upload processing to finish.
Upload creation is never retried because it is not idempotent. Signed storage
transfers may be retried safely, and processing polls follow `Retry-After`. You
can also use `runtime.uploads.request`, `createParts`, and `completeMultipart`
when you need to manage transfer details yourself.

Sources can be text, a `Blob`, an `ArrayBuffer` or typed-array view, or a
known-size Web `ReadableStream`:

```ts
await sdk.runtime.uploads.upload({
  bucket: 'archives',
  source: { stream, sizeBytes },
  fileName: 'archive.tar',
});

await sdk.runtime.uploads.uploadFromUrl({
  bucket: 'imports',
  url: 'https://example.com/report.csv',
});
```

The defaults are a 100 MiB multipart threshold, 16 MiB parts, concurrency 4, a
30-second control timeout, no transfer timeout, and a 60-second processing
timeout. Configure upload defaults with the `upload` option on
`createEdgeStoreSdk`; pass an `AbortSignal` for per-operation cancellation or
deadlines.

## Runtime resources

```ts
const page = await sdk.runtime.files.search({
  bucket: 'documents',
  filter: { metadata: { ownerId: user.id } },
  pagination: { limit: 50 },
});

if (page.pagination.hasMore) {
  const nextPage = await sdk.runtime.files.search({
    bucket: 'documents',
    pagination: {
      cursor: page.pagination.nextCursor ?? undefined,
      limit: 50,
    },
  });
}

const { signedUrls } = await sdk.runtime.files.generateSignedReadUrls({
  bucket: 'documents',
  urls: page.files.map((file) => file.url),
  expiresIn: 15 * 60,
});

await sdk.runtime.files.confirm({ file: { id: file.file.id } });
await sdk.runtime.files.delete({ file: { key: file.file.key } });

const batch = await sdk.runtime.files.deleteMany({
  files: [{ id: file.file.id }, { url: legacyFileUrl }],
});

for (const result of batch.results) {
  if (!result.success) console.error(result.fileRef, result.error.code);
}
```

Runtime resources also include projects, buckets, file lookup, signed read
URLs, access tokens, upload inspection, cancellation, and singular or plural
restore operations. Singular mutations throw `EdgeStoreFileMutationError` for
an item failure; plural mutations return the complete partial result.

## Management client

A management token uses Bearer authentication and exposes account, project,
credential, token, and membership resources. Runtime calls can select a
project per operation or create an eagerly scoped runtime client once.

```ts
const management = createEdgeStoreSdk({
  credentials: {
    token: process.env.EDGESTORE_MANAGEMENT_TOKEN!,
  },
});

const projects = await management.management.projects.list({
  account: 'account-id',
});

const project = management.runtime.forProject(projects.projects[0]!.id);
const buckets = await project.buckets.list();

// An explicit selector remains useful for one-off calls.
const anotherProject = await management.runtime.projects.get({
  project: 'another-project-id',
});

const { accessUrls } =
  await management.management.files.generateAccessUrls({
    project: projects.projects[0]!.id,
    files: [{ id: 'file-id' }],
    expiresIn: 15 * 60,
  });
```

## Reusing SDK types

Common runtime workflows have named public input and result types:

```ts
import type {
  RuntimeFileLookupInput,
  RuntimeFileLookupResult,
  RuntimeSignedReadUrlsGenerateInput,
  RuntimeSignedReadUrlsGenerateResult,
  RuntimeUploadInput,
  RuntimeUploadResult,
} from '@edgestore/sdk';
```

For any other operation, derive its friendly input and resolved output from the
public SDK interface. This includes SDK selectors such as `account`, `project`,
and `bucket`, plus `signal`.

```ts
import type { ManagementEdgeStoreSdk } from '@edgestore/sdk';

type CreateProjectMethod =
  ManagementEdgeStoreSdk['management']['projects']['create'];

type CreateProjectInput = Parameters<CreateProjectMethod>[0];
type CreateProjectOutput = Awaited<ReturnType<CreateProjectMethod>>;
```

You can use the same pattern with a configured SDK value:

```ts
type LookupInput = Parameters<typeof sdk.runtime.files.lookup>[0];
type LookupOutput = Awaited<
  ReturnType<typeof sdk.runtime.files.lookup>
>;
```

The generated OpenAPI operation types remain internal. Deriving from the public
interface keeps application types aligned with the supported SDK surface.

## Errors

```ts
import { EdgeStoreApiError, EdgeStoreNetworkError } from '@edgestore/sdk';

try {
  await sdk.runtime.files.lookup({ file: { url } });
} catch (error) {
  if (error instanceof EdgeStoreApiError) {
    console.error(error.status, error.code, error.requestId);
  } else if (error instanceof EdgeStoreNetworkError) {
    console.error('The API could not be reached', error.cause);
  }
}
```

API errors preserve the HTTP status, machine-readable code, details, request
ID, and retry guidance. Abort, network, upload, cancellation, and processing
timeout errors have dedicated classes.

## Custom environments

Use `apiUrl` for a compatible API v2 deployment and `fetch` to provide a
custom server-side transport implementation.

```ts
const sdk = createEdgeStoreSdk({
  credentials: { accessKey, secretKey },
  apiUrl: 'https://api.example.com/v2',
  fetch: instrumentedFetch,
});
```

`apiUrl` is the complete v2 URL. The SDK does not append `/v2` to an explicit
value.


# EdgeStore Docs: Troubleshooting
URL: https://edgestore.dev/docs/troubleshooting
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/(getting-started)/troubleshooting.mdx



## Ask your agent to debug it

<AgentPrompt>
  Read [https://edgestore.dev/docs/troubleshooting.md](https://edgestore.dev/docs/troubleshooting.md) and inspect my existing
  EdgeStore integration. Explain the cause before making changes.

  Problem:

  \[Describe the problem]
</AgentPrompt>

Include the error message and steps to reproduce it.

## Route not found or method not allowed

Open the handler's health endpoint. With the default Next.js route it is
[http://localhost:3000/api/edgestore/health](http://localhost:3000/api/edgestore/health).
Use your backend origin and mounted path for other adapters.

For a 404 or 405, check the catch-all route and GET/POST exports. Match the React
provider's `basePath` to the mounted endpoint, including any proxy prefix.

## Credentials or access denied

Confirm the backend loads the expected env file before creating the storage
provider, and that the keys belong to the intended project.

For protected buckets, check the application's authentication context and access
rules.

## Browser upload failures

Check the browser console for errors and the failing request and response in the
Network panel, then use
[Error handling](/docs/error-handling) to identify validation, size, or access
errors. Confirm that the React provider wraps the upload component.

For separate frontend and backend origins, allow the intended frontend origin in
CORS and check the adapter's cookie and deployment requirements.

## Enable server debug logging

Enable [debug logging](/docs/logging) to inspect server-side failures. Debug output
includes application context and cookies. Remove those values before sharing logs.

## Inspect the application with the CLI

```sh
edgestore --cwd <app> agent context --json
edgestore --cwd <app> doctor --offline --json
```

Use the backend directory for server checks in a split workspace. `agent context`
reports installed versions and local references. `doctor --offline` inspects
configuration without authenticating or running the application.

## Try an example app

Run an [example close to your framework](https://github.com/edgestorejs/edgestore/tree/main/examples)
to compare with your application.

For Next.js:

```sh
npx degit edgestorejs/edgestore/examples/next-basic#main edgestore-example
cd edgestore-example
npm install
```

Add your EdgeStore keys to `.env.local` as shown in
[Quick start](/docs/quick-start#environment-variables), then run:

```sh
npm run dev
```

## Still blocked?

Ask in [Discord](https://discord.gg/HvrnhRTfgQ) or
[open an issue](https://github.com/edgestorejs/edgestore/issues) with your framework,
installed EdgeStore versions, and the error.


# EdgeStore Docs: Utils
URL: https://edgestore.dev/docs/utils
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/(getting-started)/utils.mdx



## Download links

Sometimes the browser shows the file directly in the browser instead of downloading it. To force the browser to download the file, you can use the `getDownloadUrl` function.

```ts
import { getDownloadUrl } from '@edgestore/react/utils';

getDownloadUrl(
  url, // the url of the file
  'overwrite-file-name.jpg', // optional, the name of the file to download
);
```

## Format file size

You might want to display the file size in a human-readable format. You can use the `formatFileSize` function to do that.

```ts
import { formatFileSize } from '@edgestore/react/utils';

formatFileSize(10485760); // => 10MB
```


# EdgeStore Docs: Avatar
URL: https://edgestore.dev/docs/components/avatar
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/components/avatar.mdx



import { DemoBlock } from '@/components/demo-block';
import { LimitedCode } from '@/components/ui/limited-code';
import {
  OpenTabs,
  OpenTabsContent,
  OpenTabsList,
  OpenTabsTrigger,
} from '@/components/ui/open-tabs';
import AvatarDropzoneBlock from '@/components/upload/blocks/avatar-block';
import { Step, Steps } from 'fumadocs-ui/components/steps';

<DemoBlock registryUrl="https://edgestore.dev/r/avatar-dropzone-block.json">
  <AvatarDropzoneBlock />
</DemoBlock>

Click or drop onto the image to replace it. With `minDimension`, the image's pixel size is checked in the browser before it is uploaded.

## Installation

<OpenTabs defaultValue="cli">
  <OpenTabsList>
    <OpenTabsTrigger value="cli">
      CLI
    </OpenTabsTrigger>

    <OpenTabsTrigger value="manual">
      Manual
    </OpenTabsTrigger>
  </OpenTabsList>

  <OpenTabsContent value="cli">
    Use the shadcn CLI to add the component to your project.

    <CodeBlockTabs defaultValue="npm" groupId="package-manager" persist>
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add https://edgestore.dev/r/avatar-dropzone.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add https://edgestore.dev/r/avatar-dropzone.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add https://edgestore.dev/r/avatar-dropzone.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add https://edgestore.dev/r/avatar-dropzone.json
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </OpenTabsContent>

  <OpenTabsContent value="manual">
    <Steps>
      <Step>
        ### Setup for manual installation

        First you will need to follow the [manual install setup](./manual-install) guide.
      </Step>

      <Step>
        ### Install required components

        * [uploader-provider](./uploader-provider)
        * [dropzone](./dropzone)
        * [progress-circle](./progress-circle)
        * [shadcn/ui button](https://ui.shadcn.com/docs/components/button)
      </Step>

      <Step>
        ### Copy this component

        <LimitedCode>
          ````tsx title="components/upload/avatar-dropzone.tsx"
          'use client';

          import { Button } from '@/components/ui/button';
          import { cn } from '@/lib/utils';
          import { CameraIcon, Loader2Icon, UserIcon } from 'lucide-react';
          import * as React from 'react';
          import { type Accept } from 'react-dropzone';
          import { dropzoneState, useUploadDropzone } from './dropzone';
          import { ProgressCircle } from './progress-circle';
          import {
            formatFileSize,
            IMAGE_ACCEPT,
            minImageSize,
            useObjectUrl,
          } from './upload-utils';
          import { useUploader } from './uploader-provider';

          /**
           * Props for the AvatarDropzone component.
           */
          export type AvatarDropzoneProps = Omit<
            React.ComponentProps<'div'>,
            'children'
          > & {
            /**
             * Label shown next to the image and used in accessible labels.
             * @default "Profile photo"
             */
            label?: string;

            /**
             * Help text shown under the label. Defaults to a summary of the limits.
             */
            description?: React.ReactNode;

            /**
             * Shape of the image.
             * @default "circle"
             */
            shape?: 'circle' | 'square';

            /**
             * Size of the image in pixels.
             * @default 88
             */
            size?: number;

            /**
             * Maximum file size in bytes.
             */
            maxSize?: number;

            /**
             * Minimum width and height of the image in pixels.
             */
            minDimension?: number;

            /**
             * Accepted image types.
             * @default PNG, JPG, WEBP and GIF
             */
            accept?: Accept;

            /**
             * Human-readable list of accepted types, shown in the description and messages.
             * @default "PNG, JPG, WEBP or GIF"
             */
            typesLabel?: string;

            /**
             * Shown when there is no image.
             */
            placeholder?: React.ReactNode;

            /**
             * Whether the dropzone is disabled.
             */
            disabled?: boolean;
          };

          /**
           * A single image in a fixed shape, for profile photos and logos.
           * Click or drop onto the image to replace it.
           *
           * @example
           * ```tsx
           * <AvatarDropzone
           *   label="Profile photo"
           *   maxSize={1024 * 1024 * 2} // 2MB
           *   minDimension={128}
           * />
           * ```
           */
          export function AvatarDropzone({
            label = 'Profile photo',
            description,
            shape = 'circle',
            size = 88,
            maxSize,
            minDimension,
            accept = IMAGE_ACCEPT,
            typesLabel = 'PNG, JPG, WEBP or GIF',
            placeholder,
            disabled,
            className,
            ...props
          }: AvatarDropzoneProps) {
            const { fileStates, removeFile, uploadFiles } = useUploader();
            const fileState = fileStates[0];
            const preview = useObjectUrl(fileState?.file);
            const src = preview ?? fileState?.url;

            const validator = React.useMemo(
              () => (minDimension ? minImageSize(minDimension) : undefined),
              [minDimension],
            );

            const {
              getRootProps,
              getInputProps,
              open,
              isDragActive,
              isDragReject,
              isProcessing,
              errors,
              clearErrors,
            } = useUploadDropzone({
              accept,
              maxSize,
              typesLabel,
              disabled,
              validator,
              replace: true,
            });

            const isBusy = isProcessing || fileState?.status === 'UPLOADING';
            const accessibleLabel = label.toLowerCase();

            return (
              <div className={cn('flex items-start gap-4', className)} {...props}>
                <div
                  {...getRootProps({
                    role: 'button',
                    'aria-label': fileState
                      ? `Change ${accessibleLabel}`
                      : `Upload ${accessibleLabel}`,
                    style: { width: size, height: size },
                    className: cn(
                      'group/avatar relative flex shrink-0 cursor-pointer items-center justify-center overflow-hidden border-[1.5px] border-dashed border-muted-foreground/30 bg-muted/40 text-muted-foreground/70 transition-[border-color,box-shadow] outline-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 data-[disabled]:cursor-not-allowed data-[disabled]:opacity-60 data-[dragging]:border-2 data-[dragging]:border-solid data-[dragging]:border-primary data-[dragging]:ring-4 data-[dragging]:ring-primary/20 data-[rejected]:border-destructive data-[rejected]:ring-destructive/20',
                      shape === 'circle' ? 'rounded-full' : 'rounded-xl',
                      src && 'border-solid border-border',
                      fileState?.status === 'ERROR' && 'border-destructive',
                    ),
                  })}
                  {...dropzoneState({ isDragActive, isDragReject, disabled })}
                >
                  <input {...getInputProps()} />
                  {src ? (
                    <img src={src} alt="" className="size-full object-cover" />
                  ) : (
                    (placeholder ?? (
                      <UserIcon
                        strokeWidth={1.5}
                        style={{ width: size * 0.4, height: size * 0.4 }}
                      />
                    ))
                  )}
                  {!disabled && (
                    <span
                      aria-hidden="true"
                      className="absolute inset-0 grid place-items-center bg-black/55 text-white opacity-0 transition-opacity group-hover/avatar:opacity-100 group-focus-visible/avatar:opacity-100 group-data-[dragging]/avatar:opacity-100"
                    >
                      <CameraIcon style={{ width: size * 0.24, height: size * 0.24 }} />
                    </span>
                  )}
                  {isBusy && (
                    <span className="absolute inset-0 grid place-items-center bg-black/55 text-white">
                      {isProcessing ? (
                        <Loader2Icon className="size-5 animate-spin" />
                      ) : (
                        <ProgressCircle
                          progress={fileState?.progress ?? 0}
                          size={Math.min(44, size * 0.55)}
                          strokeWidth={3}
                          showValue={size >= 72}
                          className="text-[10px]"
                        />
                      )}
                    </span>
                  )}
                </div>

                <div className="grid min-w-0 gap-1.5">
                  <p className="text-sm font-semibold">{label}</p>
                  <p className="text-sm text-muted-foreground">
                    {description ??
                      [
                        typesLabel,
                        minDimension && `at least ${minDimension}×${minDimension}px`,
                        maxSize && `up to ${formatFileSize(maxSize)}`,
                      ]
                        .filter(Boolean)
                        .join(', ')}
                  </p>
                  {!disabled && (
                    <div className="mt-1 flex gap-2">
                      <Button
                        type="button"
                        variant="outline"
                        size="sm"
                        onClick={open}
                        disabled={isBusy}
                      >
                        {fileState ? 'Change' : 'Upload'}
                      </Button>
                      {fileState && (
                        <Button
                          type="button"
                          variant="ghost"
                          size="sm"
                          onClick={() => {
                            removeFile(fileState.key);
                            clearErrors();
                          }}
                        >
                          Remove
                        </Button>
                      )}
                    </div>
                  )}
                  {fileState?.status === 'ERROR' && (
                    <p className="text-sm text-destructive">
                      {fileState.error ?? 'Upload failed'}{' '}
                      {!disabled && (
                        <button
                          type="button"
                          onClick={() => void uploadFiles([fileState.key])}
                          className="font-medium underline underline-offset-2"
                        >
                          Retry
                        </button>
                      )}
                    </p>
                  )}
                  {errors[0] && (
                    <p role="alert" className="text-sm text-destructive">
                      {errors[0]}
                    </p>
                  )}
                </div>
              </div>
            );
          }

          ````
        </LimitedCode>
      </Step>
    </Steps>
  </OpenTabsContent>
</OpenTabs>

## Usage

Install or copy the component from [Installation](#installation) before using this example.

```tsx
'use client';

import { AvatarDropzone } from '@/components/upload/avatar-dropzone';
import {
  UploaderProvider,
  type UploadFn,
} from '@/components/upload/uploader-provider';
import { useEdgeStore } from '@/lib/edgestore';
import * as React from 'react';

export function AvatarDropzoneUsage() {
  const { edgestore } = useEdgeStore();

  const uploadFn: UploadFn = React.useCallback(
    async ({ file, onProgressChange, signal }) => {
      const res = await edgestore.publicImages.upload({
        file,
        signal,
        onProgressChange,
      });
      // you can run some server action or api here
      // to add the necessary data to your database
      console.log(res);
      return res;
    },
    [edgestore],
  );

  return (
    <UploaderProvider uploadFn={uploadFn} autoUpload>
      <AvatarDropzone
        label="Profile photo"
        maxSize={1024 * 1024 * 2} // 2 MB
        minDimension={128}
      />
    </UploaderProvider>
  );
}
```

## Props

| Prop           | Type                   | Default                   | Description                                                                                                              |
| -------------- | ---------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `label`        | `string`               | `"Profile photo"`         | Label shown next to the image and used in accessible labels.                                                             |
| `description`  | `ReactNode`            |                           | Help text under the label. Defaults to a summary of the limits.                                                          |
| `shape`        | `"circle" \| "square"` | `"circle"`                | Shape of the image.                                                                                                      |
| `size`         | `number`               | `88`                      | Size of the image in pixels.                                                                                             |
| `minDimension` | `number`               |                           | Minimum width and height of the image in pixels.                                                                         |
| `placeholder`  | `ReactNode`            | user icon                 | Shown when there is no image.                                                                                            |
| `maxSize`      | `number`               |                           | Maximum file size in bytes.                                                                                              |
| `accept`       | `Accept`               | PNG, JPG, WEBP, GIF       | Accepted file types, in [react-dropzone's format](https://react-dropzone.js.org/#section-accepting-specific-file-types). |
| `typesLabel`   | `string`               | `"PNG, JPG, WEBP or GIF"` | Human-readable list of accepted types, shown in the hint and in error messages.                                          |
| `disabled`     | `boolean`              | `false`                   | Disables the component.                                                                                                  |


# EdgeStore Docs: Dropzone
URL: https://edgestore.dev/docs/components/dropzone
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/components/dropzone.mdx



import { LimitedCode } from '@/components/ui/limited-code';
import {
  OpenTabs,
  OpenTabsContent,
  OpenTabsList,
  OpenTabsTrigger,
} from '@/components/ui/open-tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';

`dropzone.tsx` exports:

* `Dropzone`: a drop area that adds files to the nearest `UploaderProvider`.
* `useUploadDropzone`: [react-dropzone](https://react-dropzone.js.org/)'s `useDropzone`, connected to the `UploaderProvider`. It enforces `maxFiles` across drops, adds what fits, and returns readable messages about skipped files.
* `DropzonePrompt`, `DropzoneOverlay` and `UploadErrors`: the building blocks for the empty state, the drag overlay and the error notice.
* `dropzoneVariants` and `dropzoneState`: the classes for a drop area and the data attributes that drive its drag styles.

<Callout>
  If you are installing the other upload components via the CLI, this
  component will be installed automatically. You can skip the following steps.
</Callout>

## Installation

<OpenTabs defaultValue="cli">
  <OpenTabsList>
    <OpenTabsTrigger value="cli">
      CLI
    </OpenTabsTrigger>

    <OpenTabsTrigger value="manual">
      Manual
    </OpenTabsTrigger>
  </OpenTabsList>

  <OpenTabsContent value="cli">
    Use the shadcn CLI to add the component to your project.

    <CodeBlockTabs defaultValue="npm" groupId="package-manager" persist>
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add https://edgestore.dev/r/dropzone.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add https://edgestore.dev/r/dropzone.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add https://edgestore.dev/r/dropzone.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add https://edgestore.dev/r/dropzone.json
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </OpenTabsContent>

  <OpenTabsContent value="manual">
    <Steps>
      <Step>
        ### Setup for manual installation

        First you will need to follow the [manual install setup](./manual-install) guide.
      </Step>

      <Step>
        ### Install required components

        * [uploader-provider](./uploader-provider)
      </Step>

      <Step>
        ### Copy this component

        <LimitedCode>
          ````tsx title="components/upload/dropzone.tsx"
          'use client';

          import { cn } from '@/lib/utils';
          import { AlertCircleIcon, UploadIcon, XIcon } from 'lucide-react';
          import * as React from 'react';
          import { useDropzone, type DropzoneOptions } from 'react-dropzone';
          import {
            describeLimits,
            rejectionMessages,
            uploadErrorMessage,
          } from './upload-utils';
          import { useUploader } from './uploader-provider';

          /**
           * Options for the `useUploadDropzone` hook.
           */
          export type UseUploadDropzoneOptions = Omit<
            DropzoneOptions,
            'onDrop' | 'getErrorMessage' | 'maxFiles'
          > & {
            /**
             * Maximum number of files the uploader can hold in total.
             * Extra files in a drop are skipped with a message.
             */
            maxFiles?: number;

            /**
             * Swap the current file for the dropped one instead of adding it.
             * Implies `multiple: false`.
             */
            replace?: boolean;

            /**
             * Human-readable list of accepted types, used in messages. e.g. "PNG or JPG"
             */
            typesLabel?: string;

            /**
             * Called with the messages for files that were not added.
             */
            onRejected?: (messages: string[]) => void;
          };

          /**
           * `useDropzone` wired to the nearest `UploaderProvider`.
           * Adds what fits, skips the rest and keeps a list of messages about skipped files.
           *
           * @example
           * ```tsx
           * const { getRootProps, getInputProps, errors } = useUploadDropzone({ maxFiles: 5 });
           * ```
           */
          export function useUploadDropzone({
            maxFiles,
            replace,
            typesLabel,
            onRejected,
            disabled,
            ...options
          }: UseUploadDropzoneOptions = {}) {
            const { fileStates, addFiles, removeFile } = useUploader();
            const [errors, setErrors] = React.useState<string[]>([]);
            const isFull =
              !replace && maxFiles !== undefined && fileStates.length >= maxFiles;

            const multiple = options.multiple ?? !replace;

            const dropzone = useDropzone({
              ...options,
              multiple,
              disabled: disabled || isFull,
              getErrorMessage: uploadErrorMessage({
                maxSize: options.maxSize,
                minSize: options.minSize,
                maxFiles: multiple ? maxFiles : 1,
                typesLabel,
              }),
              onDrop: (accepted, rejected) => {
                const messages = rejectionMessages(rejected);
                if (replace) {
                  if (accepted.length > 0) {
                    fileStates.forEach((fileState) => removeFile(fileState.key));
                    addFiles(accepted.slice(0, 1));
                  }
                } else {
                  // react-dropzone's `maxFiles` only counts a single drop, so the total is enforced here.
                  const room =
                    maxFiles === undefined
                      ? accepted.length
                      : Math.max(maxFiles - fileStates.length, 0);
                  if (accepted.length > room) {
                    messages.push(
                      `You can add up to ${maxFiles} files. ${accepted.length - room} skipped.`,
                    );
                  }
                  addFiles(accepted.slice(0, room));
                }
                setErrors(messages);
                if (messages.length > 0) onRejected?.(messages);
              },
            });

            const clearErrors = React.useCallback(() => setErrors([]), []);

            return { ...dropzone, errors, clearErrors, isFull };
          }

          /**
           * Data attributes that drive the drag styles of `dropzoneVariants`.
           */
          export function dropzoneState({
            isDragActive,
            isDragReject,
            disabled,
          }: {
            isDragActive?: boolean;
            isDragReject?: boolean;
            disabled?: boolean;
          }) {
            return {
              'data-dragging': isDragActive || undefined,
              'data-rejected': isDragReject || undefined,
              'data-disabled': disabled || undefined,
            };
          }

          /**
           * Base classes for a drop area. Pair with `dropzoneState()`.
           */
          export const dropzoneVariants =
            'group/dropzone relative flex cursor-pointer flex-col items-center justify-center rounded-xl border-[1.5px] border-dashed border-muted-foreground/30 bg-muted/40 text-center outline-none transition-[border-color,background-color,box-shadow] hover:border-primary/50 hover:bg-muted/70 focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 data-[dragging]:border-solid data-[dragging]:border-primary data-[dragging]:bg-primary/5 data-[rejected]:border-destructive data-[rejected]:bg-destructive/5 data-[disabled]:cursor-not-allowed data-[disabled]:opacity-60 data-[disabled]:hover:border-muted-foreground/30 data-[disabled]:hover:bg-muted/40';

          /**
           * Icon, title and hint shown inside an empty drop area.
           */
          export function DropzonePrompt({
            icon = <UploadIcon />,
            title,
            hint,
            isDragActive,
            isDragReject,
            activeText = 'Drop to upload',
            rejectText = 'File type not supported',
            className,
          }: {
            icon?: React.ReactNode;
            title: React.ReactNode;
            hint?: React.ReactNode;
            isDragActive?: boolean;
            isDragReject?: boolean;
            activeText?: string;
            rejectText?: string;
            className?: string;
          }) {
            return (
              <div
                className={cn(
                  'pointer-events-none flex flex-col items-center gap-1 px-5 py-7',
                  className,
                )}
              >
                <span className="mb-2 grid size-11 place-items-center rounded-xl border bg-background text-muted-foreground shadow-xs transition group-data-[dragging]/dropzone:-translate-y-0.5 group-data-[dragging]/dropzone:border-primary/40 group-data-[dragging]/dropzone:text-primary group-data-[rejected]/dropzone:border-destructive/40 group-data-[rejected]/dropzone:text-destructive motion-reduce:transition-none [&_svg]:size-5">
                  {icon}
                </span>
                <p className="text-sm font-medium group-data-[rejected]/dropzone:text-destructive">
                  {isDragReject ? rejectText : isDragActive ? activeText : title}
                </p>
                {hint && <p className="text-xs text-muted-foreground">{hint}</p>}
              </div>
            );
          }

          /**
           * Covers a drop area that already shows files while something is dragged over it.
           */
          export function DropzoneOverlay({
            isDragReject,
            children,
          }: {
            isDragReject?: boolean;
            children: React.ReactNode;
          }) {
            return (
              <div
                data-rejected={isDragReject || undefined}
                className="pointer-events-none absolute inset-0 z-10 grid animate-in place-items-center rounded-[inherit] border-2 border-primary bg-background/80 p-4 text-sm font-semibold text-primary backdrop-blur-[2px] fade-in-0 data-[rejected]:border-destructive data-[rejected]:text-destructive"
              >
                {children}
              </div>
            );
          }

          /**
           * Lists messages about files that were not added.
           */
          export function UploadErrors({
            errors,
            onDismiss,
            className,
          }: {
            errors: string[];
            onDismiss?: () => void;
            className?: string;
          }) {
            if (errors.length === 0) return null;
            return (
              <div
                role="alert"
                className={cn(
                  'flex animate-in items-start gap-2 rounded-lg border border-destructive/30 bg-destructive/5 py-2 pr-2 pl-3 text-sm text-destructive fade-in-0',
                  className,
                )}
              >
                <AlertCircleIcon className="mt-0.5 size-4 shrink-0" />
                <ul className="grid flex-1 gap-0.5 break-words">
                  {errors.map((error) => (
                    <li key={error}>{error}</li>
                  ))}
                </ul>
                {onDismiss && (
                  <button
                    type="button"
                    onClick={onDismiss}
                    aria-label="Dismiss"
                    className="grid size-5 shrink-0 place-items-center rounded-md outline-none hover:bg-destructive/10 focus-visible:ring-2 focus-visible:ring-destructive/40"
                  >
                    <XIcon className="size-3.5" />
                  </button>
                )}
              </div>
            );
          }

          /**
           * Props for the Dropzone component.
           */
          export type DropzoneProps = Omit<React.ComponentProps<'div'>, 'title'> & {
            /**
             * Options passed to `useUploadDropzone` (and react-dropzone).
             */
            dropzoneOptions?: UseUploadDropzoneOptions;

            /**
             * Whether the dropzone is disabled.
             */
            disabled?: boolean;

            /**
             * Icon shown above the title.
             */
            icon?: React.ReactNode;

            /**
             * Title shown when idle.
             */
            title?: React.ReactNode;

            /**
             * Hint shown below the title. Defaults to a summary of the limits.
             */
            hint?: React.ReactNode;

            /**
             * Title shown while files are dragged over the dropzone.
             */
            activeText?: string;
          };

          /**
           * A drop area that adds files to the nearest `UploaderProvider`.
           *
           * @example
           * ```tsx
           * <Dropzone
           *   dropzoneOptions={{
           *     maxFiles: 5,
           *     maxSize: 1024 * 1024 * 10, // 10MB
           *   }}
           * />
           * ```
           */
          export function Dropzone({
            dropzoneOptions,
            disabled,
            icon,
            title,
            hint,
            activeText = 'Drop files to upload',
            className,
            ...props
          }: DropzoneProps) {
            const {
              getRootProps,
              getInputProps,
              isDragActive,
              isDragReject,
              errors,
              clearErrors,
              isFull,
            } = useUploadDropzone({ ...dropzoneOptions, disabled });

            return (
              <div className="flex w-full flex-col gap-3">
                <div
                  {...getRootProps({
                    role: 'button',
                    'aria-label': 'Upload files',
                    ...props,
                    className: cn(dropzoneVariants, 'min-h-40', className),
                  })}
                  {...dropzoneState({
                    isDragActive,
                    isDragReject,
                    disabled: disabled || isFull,
                  })}
                >
                  <input {...getInputProps()} />
                  <DropzonePrompt
                    icon={icon}
                    isDragActive={isDragActive}
                    isDragReject={isDragReject}
                    activeText={activeText}
                    title={
                      isFull
                        ? 'File limit reached'
                        : (title ?? (
                            <>
                              <span className="font-semibold text-primary">
                                Click to upload
                              </span>{' '}
                              or drag and drop
                            </>
                          ))
                    }
                    hint={hint ?? describeLimits(dropzoneOptions ?? {})}
                  />
                </div>
                <UploadErrors errors={errors} onDismiss={clearErrors} />
              </div>
            );
          }

          ````

          ````tsx title="components/upload/upload-utils.ts"
          'use client';

          import * as React from 'react';
          import {
            type Accept,
            type FileError,
            type FileRejection,
          } from 'react-dropzone';

          export const IMAGE_ACCEPT: Accept = {
            'image/png': ['.png'],
            'image/jpeg': ['.jpg', '.jpeg'],
            'image/webp': ['.webp'],
            'image/gif': ['.gif'],
          };

          export const DOCUMENT_ACCEPT: Accept = {
            'application/pdf': ['.pdf'],
            'application/msword': ['.doc'],
            'application/vnd.openxmlformats-officedocument.wordprocessingml.document': [
              '.docx',
            ],
          };

          export const SPREADSHEET_ACCEPT: Accept = {
            'text/csv': ['.csv'],
            'application/vnd.ms-excel': ['.xls'],
            'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': [
              '.xlsx',
            ],
          };

          /**
           * Formats a file size in bytes to a human-readable string.
           *
           * @example
           * ```ts
           * formatFileSize(1024); // "1 KB"
           * formatFileSize(1024 * 1024 * 2.5); // "2.5 MB"
           * ```
           */
          export function formatFileSize(bytes?: number) {
            if (!bytes) return '0 B';
            if (bytes < 1024) return `${Math.round(bytes)} B`;
            const units = ['KB', 'MB', 'GB', 'TB'];
            let value = bytes / 1024;
            let i = 0;
            while (value >= 1024 && i < units.length - 1) {
              value /= 1024;
              i++;
            }
            return `${value < 10 ? Number(value.toFixed(1)) : Math.round(value)} ${units[i]}`;
          }

          export function fileExtension(name: string) {
            const dot = name.lastIndexOf('.');
            return dot > 0 ? name.slice(dot + 1).toLowerCase() : '';
          }

          export type FileKind =
            | 'image'
            | 'video'
            | 'audio'
            | 'pdf'
            | 'doc'
            | 'sheet'
            | 'slides'
            | 'archive'
            | 'code'
            | 'other';

          const KIND_BY_EXTENSION: Record<string, FileKind> = {
            pdf: 'pdf',
            doc: 'doc',
            docx: 'doc',
            txt: 'doc',
            md: 'doc',
            rtf: 'doc',
            xls: 'sheet',
            xlsx: 'sheet',
            csv: 'sheet',
            ppt: 'slides',
            pptx: 'slides',
            key: 'slides',
            zip: 'archive',
            rar: 'archive',
            '7z': 'archive',
            tar: 'archive',
            gz: 'archive',
            js: 'code',
            ts: 'code',
            tsx: 'code',
            jsx: 'code',
            json: 'code',
            html: 'code',
            css: 'code',
            py: 'code',
          };

          export function fileKind(file: File): FileKind {
            if (file.type.startsWith('image/')) return 'image';
            if (file.type.startsWith('video/')) return 'video';
            if (file.type.startsWith('audio/')) return 'audio';
            return KIND_BY_EXTENSION[fileExtension(file.name)] ?? 'other';
          }

          export type UploadLimits = {
            maxSize?: number;
            minSize?: number;
            maxFiles?: number;
            /** Human-readable list of accepted types, e.g. "PNG or JPG". */
            typesLabel?: string;
          };

          /**
           * Friendlier rejection messages than react-dropzone's defaults
           * ("File is larger than 1048576 bytes"). Pass it to the `getErrorMessage` option.
           */
          export function uploadErrorMessage(limits: UploadLimits) {
            return (error: FileError, file: File): string => {
              switch (error.code) {
                case 'file-too-large':
                  return `${file.name} is ${formatFileSize(file.size)}. The limit is ${formatFileSize(limits.maxSize)}.`;
                case 'file-too-small':
                  return `${file.name} is smaller than ${formatFileSize(limits.minSize)}.`;
                case 'file-invalid-type':
                  return limits.typesLabel
                    ? `${file.name} isn't supported. Use ${limits.typesLabel}.`
                    : `${file.name} isn't a supported file type.`;
                case 'too-many-files':
                  if (limits.maxFiles === 1) return 'Choose a single file.';
                  return limits.maxFiles
                    ? `You can add up to ${limits.maxFiles} files.`
                    : 'Too many files.';
                default:
                  return error.message;
              }
            };
          }

          /** Flattens rejections into unique, human-readable messages. */
          export function rejectionMessages(rejections: readonly FileRejection[]) {
            return [
              ...new Set(rejections.flatMap((r) => r.errors.map((e) => e.message))),
            ];
          }

          /** Short summary of the limits, e.g. "PNG or JPG · up to 2 MB · 5 max". */
          export function describeLimits({
            typesLabel,
            maxSize,
            maxFiles,
          }: UploadLimits) {
            return [
              typesLabel,
              maxSize &&
                `up to ${formatFileSize(maxSize)}${maxFiles === 1 ? '' : ' each'}`,
              maxFiles && maxFiles > 1 && `${maxFiles} max`,
            ]
              .filter(Boolean)
              .join(' · ');
          }

          /**
           * Async validator that rejects images smaller than `min` pixels on either side.
           * Pass it to the `validator` option.
           */
          export function minImageSize(min: number) {
            return async (file: File): Promise<FileError | null> => {
              // Let `accept` report the type error.
              if (!file.type.startsWith('image/')) return null;
              const url = URL.createObjectURL(file);
              try {
                const img = new Image();
                img.src = url;
                await img.decode();
                if (img.naturalWidth < min || img.naturalHeight < min) {
                  return {
                    code: 'image-too-small',
                    message: `${file.name} is ${img.naturalWidth}×${img.naturalHeight}px. Use at least ${min}×${min}px.`,
                  };
                }
                return null;
              } catch {
                return {
                  code: 'image-unreadable',
                  message: `${file.name} couldn't be read as an image.`,
                };
              } finally {
                URL.revokeObjectURL(url);
              }
            };
          }

          /**
           * Returns an object URL for previewing `file`, created once per file and
           * revoked when the file changes or the component unmounts.
           */
          export function useObjectUrl(file?: File | null) {
            const [url, setUrl] = React.useState<string>();

            React.useEffect(() => {
              if (!file) return;
              const objectUrl = URL.createObjectURL(file);
              setUrl(objectUrl);
              return () => {
                URL.revokeObjectURL(objectUrl);
                setUrl(undefined);
              };
            }, [file]);

            return url;
          }

          ````
        </LimitedCode>
      </Step>
    </Steps>
  </OpenTabsContent>
</OpenTabs>

## Usage

Install or copy the component from [Installation](#installation) before using this example.

```tsx
'use client';

import { Dropzone } from '@/components/upload/dropzone';
import {
  UploaderProvider,
  type UploadFn,
} from '@/components/upload/uploader-provider';
import { useEdgeStore } from '@/lib/edgestore';
import * as React from 'react';

export function DropzoneUsage() {
  const { edgestore } = useEdgeStore();

  const uploadFn: UploadFn = React.useCallback(
    async ({ file, onProgressChange, signal }) => {
      const res = await edgestore.publicFiles.upload({
        file,
        signal,
        onProgressChange,
      });
      // you can run some server action or api here
      // to add the necessary data to your database
      console.log(res);
      return res;
    },
    [edgestore],
  );

  return (
    <UploaderProvider uploadFn={uploadFn} autoUpload>
      <Dropzone
        dropzoneOptions={{
          maxFiles: 5,
          maxSize: 1024 * 1024 * 2, // 2MB
          accept: {
            'image/*': ['.jpeg', '.jpg', '.png'],
          },
          typesLabel: 'JPG or PNG',
        }}
      />
      {/* You can create a component that uses the provider context */}
      {/* (from the `useUploader` hook) to show a custom file list here */}
    </UploaderProvider>
  );
}
```

### Custom dropzones

Use `useUploadDropzone` to build your own drop area. Spread `dropzoneState()` on the root element so the `data-dragging`, `data-rejected` and `data-disabled` attributes drive the styles in `dropzoneVariants`:

```tsx
import {
  dropzoneState,
  dropzoneVariants,
  UploadErrors,
  useUploadDropzone,
} from '@/components/upload/dropzone';

function MyDropzone() {
  const { getRootProps, getInputProps, isDragActive, isDragReject, errors } =
    useUploadDropzone({ maxFiles: 3, maxSize: 1024 * 1024 });

  return (
    <>
      <div
        {...getRootProps({ className: dropzoneVariants })}
        {...dropzoneState({ isDragActive, isDragReject })}
      >
        <input {...getInputProps()} />
        <p>Drop files here</p>
      </div>
      <UploadErrors errors={errors} />
    </>
  );
}
```

`upload-utils.ts` has the helpers the components share: `formatFileSize`, accept presets (`IMAGE_ACCEPT`, `DOCUMENT_ACCEPT`, `SPREADSHEET_ACCEPT`), the `minImageSize` validator and the `useObjectUrl` preview hook.


# EdgeStore Docs: File Field
URL: https://edgestore.dev/docs/components/file-field
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/components/file-field.mdx



import { DemoBlock } from '@/components/demo-block';
import { LimitedCode } from '@/components/ui/limited-code';
import {
  OpenTabs,
  OpenTabsContent,
  OpenTabsList,
  OpenTabsTrigger,
} from '@/components/ui/open-tabs';
import FileFieldBlock from '@/components/upload/blocks/file-field-block';
import { Step, Steps } from 'fumadocs-ui/components/steps';

<DemoBlock registryUrl="https://edgestore.dev/r/file-field-block.json">
  <FileFieldBlock />
</DemoBlock>

Once a file is chosen, the field shows it with its progress and a remove button instead of the drop area.

## Installation

<OpenTabs defaultValue="cli">
  <OpenTabsList>
    <OpenTabsTrigger value="cli">
      CLI
    </OpenTabsTrigger>

    <OpenTabsTrigger value="manual">
      Manual
    </OpenTabsTrigger>
  </OpenTabsList>

  <OpenTabsContent value="cli">
    Use the shadcn CLI to add the component to your project.

    <CodeBlockTabs defaultValue="npm" groupId="package-manager" persist>
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add https://edgestore.dev/r/file-field.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add https://edgestore.dev/r/file-field.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add https://edgestore.dev/r/file-field.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add https://edgestore.dev/r/file-field.json
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </OpenTabsContent>

  <OpenTabsContent value="manual">
    <Steps>
      <Step>
        ### Setup for manual installation

        First you will need to follow the [manual install setup](./manual-install) guide.
      </Step>

      <Step>
        ### Install required components

        * [uploader-provider](./uploader-provider)
        * [dropzone](./dropzone)
        * [multi-file](./multi-file)
      </Step>

      <Step>
        ### Copy this component

        <LimitedCode>
          ````tsx title="components/upload/file-field.tsx"
          'use client';

          import { cn } from '@/lib/utils';
          import { UploadIcon } from 'lucide-react';
          import * as React from 'react';
          import { type Accept } from 'react-dropzone';
          import { dropzoneState, dropzoneVariants, useUploadDropzone } from './dropzone';
          import { FileListItem } from './multi-file';
          import { formatFileSize } from './upload-utils';
          import { useUploader } from './uploader-provider';

          /**
           * Props for the FileField component.
           */
          export type FileFieldProps = Omit<React.ComponentProps<'div'>, 'children'> & {
            /**
             * Accepted file types.
             */
            accept?: Accept;

            /**
             * Human-readable list of accepted types, shown in the hint and messages.
             *
             * @example "PDF, DOC or DOCX"
             */
            typesLabel?: string;

            /**
             * Maximum file size in bytes.
             */
            maxSize?: number;

            /**
             * Whether the field is disabled.
             */
            disabled?: boolean;

            /**
             * Id for the hidden file input, so a `<label htmlFor>` opens the file dialog.
             */
            inputId?: string;
          };

          /**
           * A compact, single-file input that sits in a form next to regular fields.
           * Once a file is chosen, it shows the file with its progress instead.
           *
           * @example
           * ```tsx
           * <Label id="resume-label" htmlFor="resume">Resume</Label>
           * <FileField
           *   inputId="resume"
           *   aria-labelledby="resume-label"
           *   accept={{ 'application/pdf': ['.pdf'] }}
           *   typesLabel="PDF"
           *   maxSize={1024 * 1024 * 5} // 5MB
           * />
           * ```
           */
          export function FileField({
            accept,
            typesLabel,
            maxSize,
            disabled,
            inputId,
            className,
            'aria-label': ariaLabel,
            'aria-labelledby': ariaLabelledBy,
            'aria-describedby': ariaDescribedBy,
            ...props
          }: FileFieldProps) {
            const { fileStates } = useUploader();
            const fileState = fileStates[0];
            const errorId = React.useId();

            const { getRootProps, getInputProps, isDragActive, isDragReject, errors } =
              useUploadDropzone({ accept, maxSize, typesLabel, disabled, replace: true });

            const hint = [typesLabel, maxSize && formatFileSize(maxSize)]
              .filter(Boolean)
              .join(' · ');

            return (
              <div className={cn('grid gap-1.5', className)} {...props}>
                {fileState ? (
                  <ul>
                    <FileListItem fileState={fileState} disabled={disabled} />
                  </ul>
                ) : (
                  <div
                    {...getRootProps({
                      role: 'button',
                      'aria-label':
                        ariaLabel ?? (ariaLabelledBy ? undefined : 'Upload a file'),
                      'aria-labelledby': ariaLabelledBy,
                      'aria-describedby':
                        [ariaDescribedBy, errors.length > 0 && errorId]
                          .filter(Boolean)
                          .join(' ') || undefined,
                      'aria-invalid': errors.length > 0 || undefined,
                      className: cn(
                        dropzoneVariants,
                        'flex-row justify-start rounded-lg bg-background px-3.5 py-3 text-left hover:bg-background aria-invalid:border-destructive',
                      ),
                    })}
                    {...dropzoneState({ isDragActive, isDragReject, disabled })}
                  >
                    <input {...getInputProps({ id: inputId })} />
                    <UploadIcon className="mr-2.5 size-4 shrink-0 text-muted-foreground group-data-[dragging]/dropzone:text-primary" />
                    <span className="min-w-0 flex-1 text-sm group-data-[rejected]/dropzone:text-destructive">
                      {isDragReject ? (
                        'File type not supported'
                      ) : isDragActive ? (
                        'Drop to upload'
                      ) : (
                        <>
                          Drop a file or{' '}
                          <span className="font-semibold text-primary">browse</span>
                        </>
                      )}
                    </span>
                    {hint && (
                      <span className="ml-2.5 shrink-0 text-xs text-muted-foreground">
                        {hint}
                      </span>
                    )}
                  </div>
                )}
                {errors[0] && (
                  <p id={errorId} role="alert" className="text-sm text-destructive">
                    {errors[0]}
                  </p>
                )}
              </div>
            );
          }

          ````
        </LimitedCode>
      </Step>
    </Steps>
  </OpenTabsContent>
</OpenTabs>

## Usage

Install or copy the component from [Installation](#installation) before using this example.

```tsx
'use client';

import { FileField } from '@/components/upload/file-field';
import { DOCUMENT_ACCEPT } from '@/components/upload/upload-utils';
import {
  UploaderProvider,
  type UploadFn,
} from '@/components/upload/uploader-provider';
import { useEdgeStore } from '@/lib/edgestore';
import * as React from 'react';

export function FileFieldUsage() {
  const { edgestore } = useEdgeStore();

  const uploadFn: UploadFn = React.useCallback(
    async ({ file, onProgressChange, signal }) => {
      const res = await edgestore.publicFiles.upload({
        file,
        signal,
        onProgressChange,
      });
      // you can run some server action or api here
      // to add the necessary data to your database
      console.log(res);
      return res;
    },
    [edgestore],
  );

  return (
    <UploaderProvider uploadFn={uploadFn} autoUpload>
      <label id="resume-label" htmlFor="resume-input">
        Resume
      </label>
      <FileField
        inputId="resume-input"
        aria-labelledby="resume-label"
        accept={DOCUMENT_ACCEPT}
        typesLabel="PDF, DOC or DOCX"
        maxSize={1024 * 1024 * 5} // 5 MB
      />
    </UploaderProvider>
  );
}
```

## Props

| Prop              | Type      | Default   | Description                                                                                                              |
| ----------------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------ |
| `inputId`         | `string`  |           | Id for the hidden file input, so a `<label htmlFor>` opens the file dialog.                                              |
| `maxSize`         | `number`  |           | Maximum file size in bytes.                                                                                              |
| `accept`          | `Accept`  | all types | Accepted file types, in [react-dropzone's format](https://react-dropzone.js.org/#section-accepting-specific-file-types). |
| `typesLabel`      | `string`  |           | Human-readable list of accepted types, shown in the hint and in error messages.                                          |
| `disabled`        | `boolean` | `false`   | Disables the component.                                                                                                  |
| `aria-labelledby` | `string`  |           | Id of the element that labels the field.                                                                                 |

### With React Hook Form

Give each field its own `UploaderProvider` and write the completed file into the form value from `onChange`:

```tsx
const handleChange = React.useCallback(
  ({ completedFiles }: { completedFiles: CompletedFileState[] }) => {
    const [completed] = completedFiles;
    field.onChange(
      completed ? { filename: completed.file.name, url: completed.url } : null,
    );
  },
  [field],
);

<UploaderProvider uploadFn={uploadFn} onChange={handleChange} autoUpload>
  <FileField aria-labelledby="resume-label" />
</UploaderProvider>;
```


# EdgeStore Docs: Image
URL: https://edgestore.dev/docs/components/image
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/components/image.mdx



import { DemoBlock } from '@/components/demo-block';
import { LimitedCode } from '@/components/ui/limited-code';
import {
  OpenTabs,
  OpenTabsContent,
  OpenTabsList,
  OpenTabsTrigger,
} from '@/components/ui/open-tabs';
import SingleImageUploaderBlock from '@/components/upload/blocks/single-image-block';
import { Step, Steps } from 'fumadocs-ui/components/steps';

<DemoBlock registryUrl="https://edgestore.dev/r/single-image-dropzone-block.json">
  <SingleImageUploaderBlock />
</DemoBlock>

Use it for covers, thumbnails and product shots. Dropping or choosing a new image replaces the current one, and the Replace and Remove buttons stay available after the upload completes.

## Installation

<OpenTabs defaultValue="cli">
  <OpenTabsList>
    <OpenTabsTrigger value="cli">
      CLI
    </OpenTabsTrigger>

    <OpenTabsTrigger value="manual">
      Manual
    </OpenTabsTrigger>
  </OpenTabsList>

  <OpenTabsContent value="cli">
    Use the shadcn CLI to add the component to your project.

    <CodeBlockTabs defaultValue="npm" groupId="package-manager" persist>
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add https://edgestore.dev/r/single-image-dropzone.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add https://edgestore.dev/r/single-image-dropzone.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add https://edgestore.dev/r/single-image-dropzone.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add https://edgestore.dev/r/single-image-dropzone.json
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </OpenTabsContent>

  <OpenTabsContent value="manual">
    <Steps>
      <Step>
        ### Setup for manual installation

        First you will need to follow the [manual install setup](./manual-install) guide.
      </Step>

      <Step>
        ### Install required components

        * [uploader-provider](./uploader-provider)
        * [dropzone](./dropzone)
        * [progress-bar](./progress-bar)
      </Step>

      <Step>
        ### Copy this component

        <LimitedCode>
          ````tsx title="components/upload/single-image.tsx"
          'use client';

          import { cn } from '@/lib/utils';
          import {
            ImageIcon,
            RefreshCwIcon,
            RotateCwIcon,
            Trash2Icon,
            XIcon,
          } from 'lucide-react';
          import * as React from 'react';
          import { type Accept } from 'react-dropzone';
          import {
            DropzoneOverlay,
            DropzonePrompt,
            dropzoneState,
            dropzoneVariants,
            UploadErrors,
            useUploadDropzone,
          } from './dropzone';
          import { ProgressBar } from './progress-bar';
          import {
            describeLimits,
            formatFileSize,
            IMAGE_ACCEPT,
            useObjectUrl,
          } from './upload-utils';
          import { useUploader } from './uploader-provider';

          function OverlayButton({
            label,
            className,
            ...props
          }: React.ComponentProps<'button'> & { label: string }) {
            return (
              <button
                type="button"
                aria-label={label}
                title={label}
                className={cn(
                  'grid size-7 place-items-center rounded-md bg-black/60 text-white backdrop-blur-sm transition-colors outline-none hover:bg-black/80 focus-visible:ring-2 focus-visible:ring-white/70 [&_svg]:size-3.5',
                  className,
                )}
                {...props}
              />
            );
          }

          /**
           * Props for the SingleImageDropzone component.
           */
          export type SingleImageDropzoneProps = React.ComponentProps<'div'> & {
            /**
             * CSS aspect ratio of the dropzone. Set the width with `className`.
             * @default "1 / 1"
             */
            aspectRatio?: string;

            /**
             * Maximum file size in bytes.
             */
            maxSize?: number;

            /**
             * Accepted image types.
             * @default PNG, JPG, WEBP and GIF
             */
            accept?: Accept;

            /**
             * Human-readable list of accepted types, shown in the hint and messages.
             * @default "PNG, JPG, WEBP or GIF"
             */
            typesLabel?: string;

            /**
             * Name of the image, used in accessible labels.
             * @default "image"
             */
            label?: string;

            /**
             * Whether the dropzone is disabled.
             */
            disabled?: boolean;
          };

          /**
           * One image in a fixed aspect ratio: avatars, covers, thumbnails.
           * Dropping or choosing a new image replaces the current one.
           *
           * @example
           * ```tsx
           * <SingleImageDropzone
           *   className="w-64"
           *   aspectRatio="16 / 9"
           *   maxSize={1024 * 1024 * 2} // 2MB
           * />
           * ```
           */
          export function SingleImageDropzone({
            aspectRatio = '1 / 1',
            maxSize,
            accept = IMAGE_ACCEPT,
            typesLabel = 'PNG, JPG, WEBP or GIF',
            label = 'image',
            disabled,
            className,
            ...props
          }: SingleImageDropzoneProps) {
            const { fileStates, removeFile, cancelUpload, uploadFiles } = useUploader();
            const fileState = fileStates[0];
            const preview = useObjectUrl(fileState?.file);
            const src = preview ?? fileState?.url;

            const {
              getRootProps,
              getInputProps,
              open,
              isDragActive,
              isDragReject,
              errors,
              clearErrors,
            } = useUploadDropzone({
              accept,
              maxSize,
              typesLabel,
              disabled,
              replace: true,
              // With an image shown, the Replace button opens the dialog instead of click-anywhere.
              noClick: !!fileState,
              noKeyboard: !!fileState,
            });

            return (
              <div className={cn('flex w-full flex-col gap-3', className)} {...props}>
                <div
                  {...getRootProps({
                    role: fileState ? 'group' : 'button',
                    'aria-label': fileState
                      ? `${label}. Drop an image to replace it.`
                      : `Upload ${label}`,
                    style: { aspectRatio },
                    className: cn(
                      dropzoneVariants,
                      'overflow-hidden',
                      fileState &&
                        'cursor-default border-solid border-border bg-muted hover:border-border hover:bg-muted',
                    ),
                  })}
                  {...dropzoneState({ isDragActive, isDragReject, disabled })}
                >
                  <input {...getInputProps()} />
                  {fileState ? (
                    <>
                      {src && (
                        <img
                          src={src}
                          alt={fileState.file.name}
                          className="absolute inset-0 size-full animate-in object-cover fade-in-0"
                        />
                      )}
                      {fileState.status === 'UPLOADING' && (
                        <ProgressBar
                          progress={fileState.progress}
                          aria-label={`Uploading ${fileState.file.name}`}
                          className="absolute inset-x-0 top-0 h-[3px] rounded-none bg-white/25"
                          indicatorClassName="rounded-none"
                        />
                      )}
                      {fileState.status === 'ERROR' && (
                        <p className="absolute inset-x-2.5 top-2.5 rounded-md bg-destructive px-2.5 py-1.5 text-left text-xs font-medium text-white">
                          {fileState.error ?? 'Upload failed'}
                        </p>
                      )}
                      <div className="absolute inset-x-0 bottom-0 flex items-end justify-between gap-2 bg-linear-to-t from-black/60 to-transparent px-2.5 pt-8 pb-2.5 text-left text-white">
                        <span className="min-w-0 truncate pb-1 text-xs opacity-90">
                          {fileState.file.name} · {formatFileSize(fileState.file.size)}
                        </span>
                        {!disabled && (
                          <div className="flex shrink-0 gap-1.5">
                            {fileState.status === 'ERROR' && (
                              <OverlayButton
                                label="Retry upload"
                                onClick={() => void uploadFiles([fileState.key])}
                              >
                                <RotateCwIcon />
                              </OverlayButton>
                            )}
                            <OverlayButton label={`Replace ${label}`} onClick={open}>
                              <RefreshCwIcon />
                            </OverlayButton>
                            {fileState.status === 'UPLOADING' ? (
                              <OverlayButton
                                label="Cancel upload"
                                onClick={() => cancelUpload(fileState.key)}
                              >
                                <XIcon />
                              </OverlayButton>
                            ) : (
                              <OverlayButton
                                label={`Remove ${label}`}
                                onClick={() => {
                                  removeFile(fileState.key);
                                  clearErrors();
                                }}
                              >
                                <Trash2Icon />
                              </OverlayButton>
                            )}
                          </div>
                        )}
                      </div>
                      {isDragActive && (
                        <DropzoneOverlay isDragReject={isDragReject}>
                          {isDragReject ? 'Only images are supported' : 'Drop to replace'}
                        </DropzoneOverlay>
                      )}
                    </>
                  ) : (
                    <DropzonePrompt
                      icon={<ImageIcon />}
                      isDragActive={isDragActive}
                      isDragReject={isDragReject}
                      activeText="Drop image here"
                      rejectText="Only images are supported"
                      title={
                        <>
                          <span className="font-semibold text-primary">
                            Click to upload
                          </span>{' '}
                          or drag and drop
                        </>
                      }
                      hint={describeLimits({ typesLabel, maxSize, maxFiles: 1 })}
                    />
                  )}
                </div>
                <UploadErrors errors={errors} onDismiss={clearErrors} />
              </div>
            );
          }

          ````
        </LimitedCode>
      </Step>
    </Steps>
  </OpenTabsContent>
</OpenTabs>

## Usage

Install or copy the component from [Installation](#installation) before using this example.

```tsx
'use client';

import { SingleImageDropzone } from '@/components/upload/single-image';
import {
  UploaderProvider,
  type UploadFn,
} from '@/components/upload/uploader-provider';
import { useEdgeStore } from '@/lib/edgestore';
import * as React from 'react';

export function SingleImageDropzoneUsage() {
  const { edgestore } = useEdgeStore();

  const uploadFn: UploadFn = React.useCallback(
    async ({ file, onProgressChange, signal }) => {
      const res = await edgestore.publicImages.upload({
        file,
        signal,
        onProgressChange,
      });
      // you can run some server action or api here
      // to add the necessary data to your database
      console.log(res);
      return res;
    },
    [edgestore],
  );

  return (
    <UploaderProvider uploadFn={uploadFn} autoUpload>
      <SingleImageDropzone
        className="w-64"
        aspectRatio="16 / 9"
        maxSize={1024 * 1024 * 1} // 1 MB
      />
    </UploaderProvider>
  );
}
```

## Props

| Prop          | Type      | Default                   | Description                                                                                                              |
| ------------- | --------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `aspectRatio` | `string`  | `"1 / 1"`                 | CSS aspect ratio of the dropzone. Set the width with `className`.                                                        |
| `maxSize`     | `number`  |                           | Maximum file size in bytes.                                                                                              |
| `accept`      | `Accept`  | PNG, JPG, WEBP, GIF       | Accepted file types, in [react-dropzone's format](https://react-dropzone.js.org/#section-accepting-specific-file-types). |
| `typesLabel`  | `string`  | `"PNG, JPG, WEBP or GIF"` | Human-readable list of accepted types, shown in the hint and in error messages.                                          |
| `disabled`    | `boolean` | `false`                   | Disables the component.                                                                                                  |
| `label`       | `string`  | `"image"`                 | Name of the image, used in accessible labels.                                                                            |


# EdgeStore Docs: Manual Installation Setup
URL: https://edgestore.dev/docs/components/manual-install
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/components/manual-install.mdx



import {
  OpenTabs,
  OpenTabsContent,
  OpenTabsList,
  OpenTabsTrigger,
} from '@/components/ui/open-tabs';
import { Callout } from 'fumadocs-ui/components/callout';

If you're not using shadcn/ui, you can install the components manually. Follow the steps below to prepare for the components manual installation.

<Callout type="info">
  The components use the shadcn/ui color tokens (`background`, `foreground`,
  `primary`, `muted`, `muted-foreground`, `destructive`, `border` and `ring`).
  If you don't use shadcn/ui, define these colors in your Tailwind theme.
</Callout>

## Install dependencies

<CodeBlockTabs defaultValue="npm" groupId="package-manager" persist>
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install tailwind-merge clsx react-dropzone lucide-react
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add tailwind-merge clsx react-dropzone lucide-react
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add tailwind-merge clsx react-dropzone lucide-react
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add tailwind-merge clsx react-dropzone lucide-react
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Some components (multi-image, multi-file, avatar and upload button) also use the shadcn/ui [Button](https://ui.shadcn.com/docs/components/button) at `@/components/ui/button`.

The enter animations use classes from [tw-animate-css](https://github.com/Wombosvideo/tw-animate-css). Without it, the components work the same, just without the animations.

## Add the cn helper

```ts title="src/lib/utils.ts"
import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}
```

## Start adding the components

Now you can follow the manual installation guide for the components you need.


# EdgeStore Docs: Multi-file
URL: https://edgestore.dev/docs/components/multi-file
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/components/multi-file.mdx



import { DemoBlock } from '@/components/demo-block';
import { LimitedCode } from '@/components/ui/limited-code';
import {
  OpenTabs,
  OpenTabsContent,
  OpenTabsList,
  OpenTabsTrigger,
} from '@/components/ui/open-tabs';
import MultiFileUploaderBlock from '@/components/upload/blocks/multi-file-block';
import { Step, Steps } from 'fumadocs-ui/components/steps';

<DemoBlock registryUrl="https://edgestore.dev/r/file-uploader-block.json">
  <MultiFileUploaderBlock />
</DemoBlock>

Each file shows its type, size and progress. Failed uploads show the error with a retry button, and running uploads can be canceled.

## Installation

<OpenTabs defaultValue="cli">
  <OpenTabsList>
    <OpenTabsTrigger value="cli">
      CLI
    </OpenTabsTrigger>

    <OpenTabsTrigger value="manual">
      Manual
    </OpenTabsTrigger>
  </OpenTabsList>

  <OpenTabsContent value="cli">
    Use the shadcn CLI to add the component to your project.

    <CodeBlockTabs defaultValue="npm" groupId="package-manager" persist>
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add https://edgestore.dev/r/file-uploader.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add https://edgestore.dev/r/file-uploader.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add https://edgestore.dev/r/file-uploader.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add https://edgestore.dev/r/file-uploader.json
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </OpenTabsContent>

  <OpenTabsContent value="manual">
    <Steps>
      <Step>
        ### Setup for manual installation

        First you will need to follow the [manual install setup](./manual-install) guide.
      </Step>

      <Step>
        ### Install required components

        * [uploader-provider](./uploader-provider)
        * [dropzone](./dropzone)
        * [progress-bar](./progress-bar)
        * [shadcn/ui button](https://ui.shadcn.com/docs/components/button)
      </Step>

      <Step>
        ### Copy this component

        <LimitedCode>
          ````tsx title="components/upload/multi-file.tsx"
          'use client';

          import { Button } from '@/components/ui/button';
          import { cn } from '@/lib/utils';
          import { CheckIcon, RotateCwIcon, XIcon } from 'lucide-react';
          import * as React from 'react';
          import { type Accept } from 'react-dropzone';
          import { Dropzone } from './dropzone';
          import { ProgressBar } from './progress-bar';
          import {
            fileExtension,
            fileKind,
            formatFileSize,
            type FileKind,
          } from './upload-utils';
          import { useUploader, type FileState } from './uploader-provider';

          const KIND_CLASSNAMES: Record<FileKind, string> = {
            image: 'text-purple-600 dark:text-purple-400',
            video: 'text-pink-600 dark:text-pink-400',
            audio: 'text-cyan-600 dark:text-cyan-400',
            pdf: 'text-red-600 dark:text-red-400',
            doc: 'text-blue-600 dark:text-blue-400',
            sheet: 'text-green-600 dark:text-green-400',
            slides: 'text-orange-600 dark:text-orange-400',
            archive: 'text-yellow-600 dark:text-yellow-400',
            code: 'text-teal-600 dark:text-teal-400',
            other: 'text-muted-foreground',
          };

          /**
           * A colored tile with the file's extension.
           */
          export function FileBadge({
            file,
            className,
          }: {
            file: File;
            className?: string;
          }) {
            return (
              <span
                aria-hidden="true"
                className={cn(
                  'grid h-10 w-9 shrink-0 place-items-center rounded-md border border-current/25 bg-current/10 font-mono text-[10px] font-bold uppercase',
                  KIND_CLASSNAMES[fileKind(file)],
                  className,
                )}
              >
                {fileExtension(file.name).slice(0, 4) || 'file'}
              </span>
            );
          }

          function IconButton({
            label,
            className,
            ...props
          }: React.ComponentProps<'button'> & { label: string }) {
            return (
              <button
                type="button"
                aria-label={label}
                title={label}
                className={cn(
                  'grid size-8 place-items-center rounded-md text-muted-foreground transition-colors outline-none hover:bg-muted hover:text-foreground focus-visible:ring-[3px] focus-visible:ring-ring/50 [&_svg]:size-4',
                  className,
                )}
                {...props}
              />
            );
          }

          /**
           * One file with its status, progress and actions (retry, cancel, remove).
           */
          export function FileListItem({
            fileState,
            disabled,
            className,
            ...props
          }: React.ComponentProps<'li'> & {
            fileState: FileState;
            /** Hides the retry, cancel and remove actions. */
            disabled?: boolean;
          }) {
            const { removeFile, cancelUpload, uploadFiles } = useUploader();
            const { file, key, status, progress, error } = fileState;

            return (
              <li
                data-status={status}
                className={cn(
                  'relative flex animate-in items-center gap-3 overflow-hidden rounded-xl border bg-background py-2.5 pr-2 pl-2.5 fade-in-0 slide-in-from-top-1 data-[status=ERROR]:border-destructive/40',
                  className,
                )}
                {...props}
              >
                <FileBadge file={file} />
                <div className="grid min-w-0 flex-1 gap-1">
                  <div className="flex min-w-0 items-center gap-1.5">
                    <span className="truncate text-sm font-medium" title={file.name}>
                      {file.name}
                    </span>
                    {status === 'COMPLETE' && (
                      <span className="grid size-4 shrink-0 place-items-center rounded-full bg-emerald-600 text-white dark:bg-emerald-500">
                        <CheckIcon className="size-2.5" strokeWidth={4} />
                        <span className="sr-only">Uploaded</span>
                      </span>
                    )}
                  </div>
                  <p
                    className={cn(
                      'text-xs text-muted-foreground tabular-nums',
                      status === 'ERROR' && 'text-destructive',
                    )}
                  >
                    {status === 'ERROR'
                      ? (error ?? 'Upload failed')
                      : status === 'UPLOADING'
                        ? `${formatFileSize((file.size * progress) / 100)} of ${formatFileSize(file.size)} · ${Math.round(progress)}%`
                        : formatFileSize(file.size)}
                  </p>
                </div>
                {/* Pinned to the bottom edge so the row keeps its height when the upload ends. */}
                {status === 'UPLOADING' && (
                  <ProgressBar
                    progress={progress}
                    aria-label={`Uploading ${file.name}`}
                    className="absolute inset-x-0 bottom-0 h-0.5 rounded-none bg-transparent"
                    indicatorClassName="rounded-none"
                  />
                )}
                {!disabled && (
                  <div className="flex items-center">
                    {status === 'ERROR' && (
                      <IconButton
                        label={`Retry ${file.name}`}
                        onClick={() => void uploadFiles([key])}
                      >
                        <RotateCwIcon />
                      </IconButton>
                    )}
                    {status === 'UPLOADING' ? (
                      <IconButton
                        label={`Cancel ${file.name}`}
                        onClick={() => cancelUpload(key)}
                      >
                        <XIcon />
                      </IconButton>
                    ) : (
                      <IconButton
                        label={`Remove ${file.name}`}
                        onClick={() => removeFile(key)}
                      >
                        <XIcon />
                      </IconButton>
                    )}
                  </div>
                )}
              </li>
            );
          }

          /**
           * Lists the files of the nearest `UploaderProvider`.
           *
           * @example
           * ```tsx
           * <FileList className="my-4" />
           * ```
           */
          export function FileList({
            disabled,
            className,
            ...props
          }: React.ComponentProps<'ul'> & {
            /** Hides the retry, cancel and remove actions. */
            disabled?: boolean;
          }) {
            const { fileStates } = useUploader();
            if (fileStates.length === 0) return null;

            return (
              <ul
                aria-label="Files"
                className={cn('grid w-full gap-2', className)}
                {...props}
              >
                {fileStates.map((fileState) => (
                  <FileListItem
                    key={fileState.key}
                    fileState={fileState}
                    disabled={disabled}
                  />
                ))}
              </ul>
            );
          }

          /**
           * Props for the FileUploader component.
           */
          export type FileUploaderProps = React.ComponentProps<'div'> & {
            /**
             * Maximum number of files allowed in total.
             */
            maxFiles?: number;

            /**
             * Maximum file size in bytes.
             */
            maxSize?: number;

            /**
             * Accepted file types.
             *
             * @example
             * ```tsx
             * accept={{ 'application/pdf': ['.pdf'] }}
             * ```
             */
            accept?: Accept;

            /**
             * Human-readable list of accepted types, shown in the hint and messages.
             *
             * @example "PDF or TXT"
             */
            typesLabel?: string;

            /**
             * Whether the uploader is disabled.
             */
            disabled?: boolean;

            /**
             * Additional className for the dropzone.
             */
            dropzoneClassName?: string;

            /**
             * Additional className for the file list.
             */
            fileListClassName?: string;
          };

          /**
           * A dropzone with a list of files, their progress and a summary.
           *
           * @example
           * ```tsx
           * <FileUploader
           *   maxFiles={5}
           *   maxSize={1024 * 1024 * 10} // 10MB
           *   accept={{ 'application/pdf': ['.pdf'] }}
           *   typesLabel="PDF"
           * />
           * ```
           */
          export function FileUploader({
            maxFiles,
            maxSize,
            accept,
            typesLabel,
            disabled,
            className,
            dropzoneClassName,
            fileListClassName,
            ...props
          }: FileUploaderProps) {
            const { fileStates, resetFiles } = useUploader();
            const completed = fileStates.filter((fs) => fs.status === 'COMPLETE').length;
            const totalSize = fileStates.reduce((sum, fs) => sum + fs.file.size, 0);

            return (
              <div className={cn('flex w-full flex-col gap-3', className)} {...props}>
                <Dropzone
                  dropzoneOptions={{ maxFiles, maxSize, accept, typesLabel }}
                  disabled={disabled}
                  className={dropzoneClassName}
                />
                <FileList className={fileListClassName} disabled={disabled} />
                {fileStates.length > 0 && (
                  <div className="flex items-center justify-between gap-3 text-xs text-muted-foreground">
                    <span className="tabular-nums">
                      {completed} of {fileStates.length} uploaded ·{' '}
                      {formatFileSize(totalSize)}
                    </span>
                    <Button
                      type="button"
                      variant="ghost"
                      size="sm"
                      onClick={resetFiles}
                      disabled={disabled}
                    >
                      Clear all
                    </Button>
                  </div>
                )}
              </div>
            );
          }

          ````
        </LimitedCode>
      </Step>
    </Steps>
  </OpenTabsContent>
</OpenTabs>

## Usage

Install or copy the component from [Installation](#installation) before using this example.

```tsx
'use client';

import { FileUploader } from '@/components/upload/multi-file';
import {
  UploaderProvider,
  type UploadFn,
} from '@/components/upload/uploader-provider';
import { useEdgeStore } from '@/lib/edgestore';
import * as React from 'react';

export function MultiFileDropzoneUsage() {
  const { edgestore } = useEdgeStore();

  const uploadFn: UploadFn = React.useCallback(
    async ({ file, onProgressChange, signal }) => {
      const res = await edgestore.publicFiles.upload({
        file,
        signal,
        onProgressChange,
      });
      // you can run some server action or api here
      // to add the necessary data to your database
      console.log(res);
      return res;
    },
    [edgestore],
  );

  return (
    <UploaderProvider uploadFn={uploadFn} autoUpload>
      <FileUploader
        maxFiles={5}
        maxSize={1024 * 1024 * 1} // 1 MB
        accept={{
          'application/pdf': ['.pdf'],
          'text/plain': ['.txt'],
        }}
        typesLabel="PDF or TXT"
      />
    </UploaderProvider>
  );
}
```

## Props

| Prop                | Type      | Default   | Description                                                                                                              |
| ------------------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------ |
| `maxFiles`          | `number`  |           | Maximum number of files in total.                                                                                        |
| `maxSize`           | `number`  |           | Maximum file size in bytes.                                                                                              |
| `accept`            | `Accept`  | all types | Accepted file types, in [react-dropzone's format](https://react-dropzone.js.org/#section-accepting-specific-file-types). |
| `typesLabel`        | `string`  |           | Human-readable list of accepted types, shown in the hint and in error messages.                                          |
| `disabled`          | `boolean` | `false`   | Disables the component.                                                                                                  |
| `dropzoneClassName` | `string`  |           | Additional className for the dropzone.                                                                                   |
| `fileListClassName` | `string`  |           | Additional className for the file list.                                                                                  |

### Building your own layout

`multi-file.tsx` also exports the pieces it is made of, so you can arrange them differently:

* `FileList` lists the files of the nearest `UploaderProvider`.
* `FileListItem` renders one file with its status and actions.
* `FileBadge` renders the colored file-type tile.


# EdgeStore Docs: Multi-image
URL: https://edgestore.dev/docs/components/multi-image
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/components/multi-image.mdx



import { DemoBlock } from '@/components/demo-block';
import { LimitedCode } from '@/components/ui/limited-code';
import {
  OpenTabs,
  OpenTabsContent,
  OpenTabsList,
  OpenTabsTrigger,
} from '@/components/ui/open-tabs';
import MultiImageUploaderBlock from '@/components/upload/blocks/multi-image-block';
import { Step, Steps } from 'fumadocs-ui/components/steps';

<DemoBlock registryUrl="https://edgestore.dev/r/multi-image-uploader-block.json">
  <MultiImageUploaderBlock />
</DemoBlock>

When empty, it is a large dropzone. Once images are added, it shows a thumbnail grid that still accepts drops, plus an Add tile. If a drop has more images than there is room for, it keeps what fits and says how many were skipped.

## Installation

<OpenTabs defaultValue="cli">
  <OpenTabsList>
    <OpenTabsTrigger value="cli">
      CLI
    </OpenTabsTrigger>

    <OpenTabsTrigger value="manual">
      Manual
    </OpenTabsTrigger>
  </OpenTabsList>

  <OpenTabsContent value="cli">
    Use the shadcn CLI to add the component to your project.

    <CodeBlockTabs defaultValue="npm" groupId="package-manager" persist>
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add https://edgestore.dev/r/image-uploader.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add https://edgestore.dev/r/image-uploader.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add https://edgestore.dev/r/image-uploader.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add https://edgestore.dev/r/image-uploader.json
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </OpenTabsContent>

  <OpenTabsContent value="manual">
    <Steps>
      <Step>
        ### Setup for manual installation

        First you will need to follow the [manual install setup](./manual-install) guide.
      </Step>

      <Step>
        ### Install required components

        * [uploader-provider](./uploader-provider)
        * [dropzone](./dropzone)
        * [progress-bar](./progress-bar)
        * [shadcn/ui button](https://ui.shadcn.com/docs/components/button)
      </Step>

      <Step>
        ### Copy this component

        <LimitedCode>
          ````tsx title="components/upload/multi-image.tsx"
          'use client';

          import { Button } from '@/components/ui/button';
          import { cn } from '@/lib/utils';
          import {
            CheckIcon,
            ImageIcon,
            PlusIcon,
            RotateCwIcon,
            XIcon,
          } from 'lucide-react';
          import * as React from 'react';
          import { type Accept } from 'react-dropzone';
          import {
            DropzoneOverlay,
            DropzonePrompt,
            dropzoneState,
            dropzoneVariants,
            UploadErrors,
            useUploadDropzone,
          } from './dropzone';
          import { ProgressBar } from './progress-bar';
          import {
            describeLimits,
            formatFileSize,
            IMAGE_ACCEPT,
            useObjectUrl,
          } from './upload-utils';
          import { useUploader, type FileState } from './uploader-provider';

          /**
           * One image of the grid with its status and actions.
           */
          export function ImageTile({
            fileState,
            disabled,
          }: {
            fileState: FileState;
            disabled?: boolean;
          }) {
            const { removeFile, cancelUpload, uploadFiles } = useUploader();
            const preview = useObjectUrl(fileState.file);
            const { key, file, status, progress, error } = fileState;
            const src = preview ?? fileState.url;

            return (
              <li
                data-status={status}
                className="group/tile relative aspect-square animate-in overflow-hidden rounded-lg bg-muted fade-in-0 zoom-in-95"
              >
                {src && (
                  <img
                    src={src}
                    alt={file.name}
                    className="size-full object-cover transition duration-300 group-hover/tile:scale-[1.03] group-data-[status=ERROR]/tile:brightness-50 group-data-[status=ERROR]/tile:grayscale-[.6] group-data-[status=UPLOADING]/tile:brightness-75 motion-reduce:transition-none"
                  />
                )}

                {status === 'COMPLETE' && (
                  <span className="absolute top-1.5 left-1.5 grid size-5 animate-in place-items-center rounded-full bg-emerald-600 text-white shadow-sm zoom-in-50 dark:bg-emerald-500">
                    <CheckIcon className="size-3" strokeWidth={3} />
                    <span className="sr-only">Uploaded</span>
                  </span>
                )}

                {(status === 'COMPLETE' || status === 'PENDING') && (
                  <div className="pointer-events-none absolute inset-x-0 bottom-0 flex justify-between gap-1.5 bg-linear-to-t from-black/65 to-transparent px-2 pt-5 pb-1.5 text-[11px] text-white opacity-0 transition-opacity group-focus-within/tile:opacity-100 group-hover/tile:opacity-100">
                    <span className="truncate">{file.name}</span>
                    <span className="shrink-0">{formatFileSize(file.size)}</span>
                  </div>
                )}

                {status === 'UPLOADING' && (
                  <ProgressBar
                    progress={progress}
                    aria-label={`Uploading ${file.name}`}
                    className="absolute inset-x-2 bottom-2 w-auto bg-white/30"
                    indicatorClassName="bg-white"
                  />
                )}

                {status === 'ERROR' && (
                  <div className="absolute inset-0 flex flex-col items-center justify-center gap-2 p-2 text-center text-xs font-semibold text-white">
                    <span title={error}>Upload failed</span>
                    {!disabled && (
                      <button
                        type="button"
                        onClick={() => void uploadFiles([key])}
                        className="inline-flex items-center gap-1 rounded-md bg-black/60 px-2 py-1 font-medium backdrop-blur-sm outline-none hover:bg-black/80 focus-visible:ring-2 focus-visible:ring-white/70"
                      >
                        <RotateCwIcon className="size-3.5" /> Retry
                      </button>
                    )}
                  </div>
                )}

                {!disabled && (
                  <button
                    type="button"
                    onClick={() =>
                      status === 'UPLOADING' ? cancelUpload(key) : removeFile(key)
                    }
                    aria-label={
                      status === 'UPLOADING'
                        ? `Cancel ${file.name}`
                        : `Remove ${file.name}`
                    }
                    className="absolute top-1.5 right-1.5 grid size-6 place-items-center rounded-full bg-black/60 text-white opacity-0 backdrop-blur-sm transition outline-none group-focus-within/tile:opacity-100 group-hover/tile:opacity-100 group-data-[status=ERROR]/tile:opacity-100 hover:bg-black/80 focus-visible:opacity-100 focus-visible:ring-2 focus-visible:ring-white/70 [@media(hover:none)]:opacity-100"
                  >
                    <XIcon className="size-3.5" />
                  </button>
                )}
              </li>
            );
          }

          /**
           * Props for the ImageUploader component.
           */
          export type ImageUploaderProps = React.ComponentProps<'div'> & {
            /**
             * Maximum number of images allowed in total.
             */
            maxFiles?: number;

            /**
             * Maximum file size in bytes.
             */
            maxSize?: number;

            /**
             * Accepted image types.
             * @default PNG, JPG, WEBP and GIF
             */
            accept?: Accept;

            /**
             * Human-readable list of accepted types, shown in the hint and messages.
             * @default "PNG, JPG, WEBP or GIF"
             */
            typesLabel?: string;

            /**
             * Whether the uploader is disabled.
             */
            disabled?: boolean;
          };

          /**
           * A gallery uploader. Empty, it is a large dropzone. With images, it shows a
           * thumbnail grid that still accepts drops, plus an "Add" tile.
           *
           * @example
           * ```tsx
           * <ImageUploader
           *   maxFiles={10}
           *   maxSize={1024 * 1024 * 5} // 5MB
           * />
           * ```
           */
          export function ImageUploader({
            maxFiles,
            maxSize,
            accept = IMAGE_ACCEPT,
            typesLabel = 'PNG, JPG, WEBP or GIF',
            disabled,
            className,
            ...props
          }: ImageUploaderProps) {
            const { fileStates, resetFiles, isUploading } = useUploader();
            const hasFiles = fileStates.length > 0;

            const {
              getRootProps,
              getInputProps,
              open,
              isDragActive,
              isDragReject,
              errors,
              clearErrors,
              isFull,
            } = useUploadDropzone({
              accept,
              maxSize,
              maxFiles,
              typesLabel,
              disabled,
              // Once there are thumbnails, clicks belong to the tiles; the "Add" tile opens the dialog.
              noClick: hasFiles,
              noKeyboard: hasFiles,
            });

            return (
              <div className={cn('flex w-full flex-col gap-3', className)} {...props}>
                <div
                  {...getRootProps({
                    role: hasFiles ? 'group' : 'button',
                    'aria-label': hasFiles
                      ? 'Images. Drop images here to add more.'
                      : 'Upload images',
                    className: cn(
                      dropzoneVariants,
                      hasFiles
                        ? 'block cursor-default border-solid border-border p-3 hover:border-border hover:bg-muted/40'
                        : 'min-h-40',
                    ),
                  })}
                  {...dropzoneState({
                    isDragActive,
                    isDragReject,
                    disabled: !hasFiles && (disabled || isFull),
                  })}
                >
                  <input {...getInputProps()} />
                  {hasFiles ? (
                    <ul className="grid grid-cols-[repeat(auto-fill,minmax(6.5rem,1fr))] gap-2.5">
                      {fileStates.map((fileState) => (
                        <ImageTile
                          key={fileState.key}
                          fileState={fileState}
                          disabled={disabled}
                        />
                      ))}
                      {!isFull && !disabled && (
                        <li>
                          <button
                            type="button"
                            onClick={open}
                            className="flex aspect-square w-full flex-col items-center justify-center gap-1 rounded-lg border-[1.5px] border-dashed border-muted-foreground/30 bg-background text-sm font-medium text-muted-foreground transition-colors outline-none hover:border-primary hover:bg-primary/5 hover:text-primary focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50"
                          >
                            <PlusIcon className="size-5" />
                            Add
                          </button>
                        </li>
                      )}
                    </ul>
                  ) : (
                    <DropzonePrompt
                      icon={<ImageIcon />}
                      isDragActive={isDragActive}
                      isDragReject={isDragReject}
                      activeText="Drop images to upload"
                      rejectText="Only images are supported"
                      title={
                        <>
                          <span className="font-semibold text-primary">
                            Click to upload
                          </span>{' '}
                          or drag and drop
                        </>
                      }
                      hint={describeLimits({ typesLabel, maxSize, maxFiles })}
                    />
                  )}
                  {hasFiles && isDragActive && (
                    <DropzoneOverlay isDragReject={isDragReject}>
                      {isDragReject ? 'Only images are supported' : 'Drop to add images'}
                    </DropzoneOverlay>
                  )}
                </div>

                {hasFiles && (
                  <div className="flex items-center justify-between gap-3 text-xs text-muted-foreground">
                    <span className="tabular-nums">
                      {fileStates.length}
                      {maxFiles ? ` of ${maxFiles}` : ''} images
                      {isUploading && ' · uploading…'}
                    </span>
                    {!disabled && (
                      <Button
                        type="button"
                        variant="ghost"
                        size="sm"
                        onClick={resetFiles}
                      >
                        Remove all
                      </Button>
                    )}
                  </div>
                )}
                <UploadErrors errors={errors} onDismiss={clearErrors} />
              </div>
            );
          }

          ````
        </LimitedCode>
      </Step>
    </Steps>
  </OpenTabsContent>
</OpenTabs>

## Usage

Install or copy the component from [Installation](#installation) before using this example.

```tsx
'use client';

import { ImageUploader } from '@/components/upload/multi-image';
import {
  UploaderProvider,
  type UploadFn,
} from '@/components/upload/uploader-provider';
import { useEdgeStore } from '@/lib/edgestore';
import * as React from 'react';

export function MultiImageDropzoneUsage() {
  const { edgestore } = useEdgeStore();

  const uploadFn: UploadFn = React.useCallback(
    async ({ file, onProgressChange, signal }) => {
      const res = await edgestore.publicImages.upload({
        file,
        signal,
        onProgressChange,
      });
      // you can run some server action or api here
      // to add the necessary data to your database
      console.log(res);
      return res;
    },
    [edgestore],
  );

  return (
    <UploaderProvider uploadFn={uploadFn} autoUpload>
      <ImageUploader
        maxFiles={6}
        maxSize={1024 * 1024 * 1} // 1 MB
      />
    </UploaderProvider>
  );
}
```

## Props

| Prop         | Type      | Default                   | Description                                                                                                              |
| ------------ | --------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `maxFiles`   | `number`  |                           | Maximum number of images in total.                                                                                       |
| `maxSize`    | `number`  |                           | Maximum file size in bytes.                                                                                              |
| `accept`     | `Accept`  | PNG, JPG, WEBP, GIF       | Accepted file types, in [react-dropzone's format](https://react-dropzone.js.org/#section-accepting-specific-file-types). |
| `typesLabel` | `string`  | `"PNG, JPG, WEBP or GIF"` | Human-readable list of accepted types, shown in the hint and in error messages.                                          |
| `disabled`   | `boolean` | `false`                   | Disables the component.                                                                                                  |


# EdgeStore Docs: Progress Bar
URL: https://edgestore.dev/docs/components/progress-bar
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/components/progress-bar.mdx



import { DemoBlock } from '@/components/demo-block';
import { LimitedCode } from '@/components/ui/limited-code';
import {
  OpenTabs,
  OpenTabsContent,
  OpenTabsList,
  OpenTabsTrigger,
} from '@/components/ui/open-tabs';
import ProgressBarUsage from '@/components/upload/blocks/progress-bar-block';
import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';

<DemoBlock registryUrl="https://edgestore.dev/r/progress-bar-block.json">
  <ProgressBarUsage />
</DemoBlock>

The `ProgressBar` component displays a horizontal progress indicator, commonly used to show file upload progress.

<Callout>
  If you are installing the other upload components via the CLI, this
  component will be installed automatically. You can skip the following steps.
</Callout>

## Installation

<OpenTabs defaultValue="cli">
  <OpenTabsList>
    <OpenTabsTrigger value="cli">
      CLI
    </OpenTabsTrigger>

    <OpenTabsTrigger value="manual">
      Manual
    </OpenTabsTrigger>
  </OpenTabsList>

  <OpenTabsContent value="cli">
    Use the shadcn CLI to add the component to your project.

    <CodeBlockTabs defaultValue="npm" groupId="package-manager" persist>
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add https://edgestore.dev/r/progress-bar.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add https://edgestore.dev/r/progress-bar.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add https://edgestore.dev/r/progress-bar.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add https://edgestore.dev/r/progress-bar.json
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </OpenTabsContent>

  <OpenTabsContent value="manual">
    <Steps>
      <Step>
        ### Setup for manual installation

        First you will need to follow the [manual install setup](./manual-install) guide.
      </Step>

      <Step>
        ### Copy this component

        <LimitedCode>
          ````tsx title="components/upload/progress-bar.tsx"
          import { cn } from '@/lib/utils';
          import * as React from 'react';

          /**
           * Props for the ProgressBar component.
           */
          export type ProgressBarProps = React.ComponentProps<'div'> & {
            /**
             * The progress value as a percentage (0-100).
             */
            progress: number;

            /**
             * Additional className for the filled part of the bar.
             */
            indicatorClassName?: string;
          };

          /**
           * A horizontal progress bar that visualizes completion percentage.
           *
           * @example
           * ```tsx
           * <ProgressBar progress={75} />
           * <ProgressBar progress={75} className="bg-white/30" indicatorClassName="bg-white" />
           * ```
           */
          function ProgressBar({
            progress,
            className,
            indicatorClassName,
            ...props
          }: ProgressBarProps) {
            const value = Math.min(100, Math.max(0, progress));
            return (
              <div
                role="progressbar"
                aria-valuemin={0}
                aria-valuemax={100}
                aria-valuenow={Math.round(value)}
                className={cn(
                  'h-1 w-full overflow-hidden rounded-full bg-primary/15',
                  className,
                )}
                {...props}
              >
                <div
                  className={cn(
                    'h-full rounded-full bg-primary transition-[width] duration-150 ease-linear motion-reduce:transition-none',
                    indicatorClassName,
                  )}
                  style={{ width: `${value}%` }}
                />
              </div>
            );
          }

          export { ProgressBar };

          ````
        </LimitedCode>
      </Step>
    </Steps>
  </OpenTabsContent>
</OpenTabs>

## Usage

Import the component and provide the `progress` prop. Use `className` for the track and `indicatorClassName` for the filled part.

```tsx
import { ProgressBar } from '@/components/upload/progress-bar';

function ProgressDemo() {
  return (
    <div className="flex flex-col gap-4">
      <ProgressBar progress={75} />

      {/* On top of an image */}
      <ProgressBar
        progress={75}
        className="bg-white/30"
        indicatorClassName="bg-white"
      />
    </div>
  );
}
```


# EdgeStore Docs: Progress Circle
URL: https://edgestore.dev/docs/components/progress-circle
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/components/progress-circle.mdx



import { DemoBlock } from '@/components/demo-block';
import { LimitedCode } from '@/components/ui/limited-code';
import {
  OpenTabs,
  OpenTabsContent,
  OpenTabsList,
  OpenTabsTrigger,
} from '@/components/ui/open-tabs';
import ProgressCircleUsage from '@/components/upload/blocks/progress-circle-block';
import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';

<DemoBlock registryUrl="https://edgestore.dev/r/progress-circle-block.json">
  <ProgressCircleUsage />
</DemoBlock>

The `ProgressCircle` component displays a circular progress indicator. It draws with `currentColor`, so set its color with a text class.

<Callout>
  If you are installing the other upload components via the CLI, this
  component will be installed automatically. You can skip the following steps.
</Callout>

## Installation

<OpenTabs defaultValue="cli">
  <OpenTabsList>
    <OpenTabsTrigger value="cli">
      CLI
    </OpenTabsTrigger>

    <OpenTabsTrigger value="manual">
      Manual
    </OpenTabsTrigger>
  </OpenTabsList>

  <OpenTabsContent value="cli">
    Use the shadcn CLI to add the component to your project.

    <CodeBlockTabs defaultValue="npm" groupId="package-manager" persist>
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add https://edgestore.dev/r/progress-circle.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add https://edgestore.dev/r/progress-circle.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add https://edgestore.dev/r/progress-circle.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add https://edgestore.dev/r/progress-circle.json
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </OpenTabsContent>

  <OpenTabsContent value="manual">
    <Steps>
      <Step>
        ### Setup for manual installation

        First you will need to follow the [manual install setup](./manual-install) guide.
      </Step>

      <Step>
        ### Copy this component

        <LimitedCode>
          ````tsx title="components/upload/progress-circle.tsx"
          import { cn } from '@/lib/utils';
          import * as React from 'react';

          /**
           * Props for the ProgressCircle component.
           */
          export type ProgressCircleProps = React.ComponentProps<'div'> & {
            /**
             * The progress value as a percentage (0-100).
             */
            progress: number;

            /**
             * The diameter of the circle in pixels.
             * @default 48
             */
            size?: number;

            /**
             * The width of the progress stroke in pixels.
             * @default 4
             */
            strokeWidth?: number;

            /**
             * Whether to show the percentage in the middle.
             * @default true
             */
            showValue?: boolean;
          };

          /**
           * A circular progress indicator. It draws with `currentColor`,
           * so set the color with a text class.
           *
           * @example
           * ```tsx
           * <ProgressCircle progress={75} className="text-white" />
           * <ProgressCircle progress={50} size={64} strokeWidth={6} />
           * ```
           */
          function ProgressCircle({
            progress,
            size = 48,
            strokeWidth = 4,
            showValue = true,
            className,
            style,
            ...props
          }: ProgressCircleProps) {
            const value = Math.min(100, Math.max(0, progress));
            const radius = (size - strokeWidth) / 2;
            const circumference = 2 * Math.PI * radius;

            return (
              <div
                role="progressbar"
                aria-valuemin={0}
                aria-valuemax={100}
                aria-valuenow={Math.round(value)}
                className={cn('relative grid place-items-center', className)}
                style={{ width: size, height: size, ...style }}
                {...props}
              >
                <svg
                  className="absolute inset-0 -rotate-90"
                  width={size}
                  height={size}
                  viewBox={`0 0 ${size} ${size}`}
                  aria-hidden="true"
                >
                  <circle
                    cx={size / 2}
                    cy={size / 2}
                    r={radius}
                    strokeWidth={strokeWidth}
                    className="fill-none stroke-current opacity-25"
                  />
                  <circle
                    cx={size / 2}
                    cy={size / 2}
                    r={radius}
                    strokeWidth={strokeWidth}
                    strokeLinecap="round"
                    strokeDasharray={circumference}
                    strokeDashoffset={circumference * (1 - value / 100)}
                    className="fill-none stroke-current transition-[stroke-dashoffset] duration-150 ease-linear motion-reduce:transition-none"
                  />
                </svg>
                {showValue && (
                  <span className="text-xs font-medium tabular-nums">
                    {Math.round(value)}%
                  </span>
                )}
              </div>
            );
          }

          export { ProgressCircle };

          ````
        </LimitedCode>
      </Step>
    </Steps>
  </OpenTabsContent>
</OpenTabs>

## Usage

Import the component and provide the `progress` prop. You can optionally customize the `size`, `strokeWidth` and whether the percentage is shown.

```tsx
import { ProgressCircle } from '@/components/upload/progress-circle';

function ProgressDemo() {
  return (
    <div className="flex items-center gap-4 rounded-lg bg-black/80 p-4 text-white">
      {/* Default size */}
      <ProgressCircle progress={75} />

      {/* Larger size with thicker stroke */}
      <ProgressCircle progress={75} size={64} strokeWidth={6} />

      {/* Smaller size without the percentage */}
      <ProgressCircle progress={75} size={24} strokeWidth={3} showValue={false} />
    </div>
  );
}
```


# EdgeStore Docs: Upload Button
URL: https://edgestore.dev/docs/components/upload-button
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/components/upload-button.mdx



import { DemoBlock } from '@/components/demo-block';
import { LimitedCode } from '@/components/ui/limited-code';
import {
  OpenTabs,
  OpenTabsContent,
  OpenTabsList,
  OpenTabsTrigger,
} from '@/components/ui/open-tabs';
import UploadButtonBlock from '@/components/upload/blocks/upload-button-block';
import { Step, Steps } from 'fumadocs-ui/components/steps';

<DemoBlock registryUrl="https://edgestore.dev/r/upload-button-block.json">
  <UploadButtonBlock />
</DemoBlock>

It takes the same props as the shadcn/ui `Button`. Several buttons can feed the same `UploaderProvider`, so you can pair them with a `FileList` or build your own list with `useUploader`.

## Installation

<OpenTabs defaultValue="cli">
  <OpenTabsList>
    <OpenTabsTrigger value="cli">
      CLI
    </OpenTabsTrigger>

    <OpenTabsTrigger value="manual">
      Manual
    </OpenTabsTrigger>
  </OpenTabsList>

  <OpenTabsContent value="cli">
    Use the shadcn CLI to add the component to your project.

    <CodeBlockTabs defaultValue="npm" groupId="package-manager" persist>
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add https://edgestore.dev/r/upload-button.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add https://edgestore.dev/r/upload-button.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add https://edgestore.dev/r/upload-button.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add https://edgestore.dev/r/upload-button.json
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </OpenTabsContent>

  <OpenTabsContent value="manual">
    <Steps>
      <Step>
        ### Setup for manual installation

        First you will need to follow the [manual install setup](./manual-install) guide.
      </Step>

      <Step>
        ### Install required components

        * [uploader-provider](./uploader-provider)
        * [dropzone](./dropzone)
        * [shadcn/ui button](https://ui.shadcn.com/docs/components/button)
      </Step>

      <Step>
        ### Copy this component

        <LimitedCode>
          ````tsx title="components/upload/upload-button.tsx"
          'use client';

          import { Button } from '@/components/ui/button';
          import { cn } from '@/lib/utils';
          import * as React from 'react';
          import { type Accept } from 'react-dropzone';
          import { dropzoneState, useUploadDropzone } from './dropzone';

          /**
           * Props for the UploadButton component.
           */
          export type UploadButtonProps = Omit<
            React.ComponentProps<typeof Button>,
            'onClick' | 'type' | 'className'
          > & {
            className?: string;

            /**
             * Accepted file types.
             */
            accept?: Accept;

            /**
             * Human-readable list of accepted types, used in messages.
             */
            typesLabel?: string;

            /**
             * Maximum file size in bytes.
             */
            maxSize?: number;

            /**
             * Maximum number of files allowed in total.
             */
            maxFiles?: number;

            /**
             * Whether more than one file can be picked at once.
             * @default true
             */
            multiple?: boolean;

            /**
             * Called with messages about files that were not added
             * (wrong type, too large, over the limit).
             */
            onRejected?: (messages: string[]) => void;
          };

          /**
           * A button that opens the file dialog and also accepts files dropped onto it.
           * Several buttons can feed the same `UploaderProvider`.
           *
           * @example
           * ```tsx
           * <UploadButton maxSize={1024 * 1024 * 10} onRejected={setErrors}>
           *   <UploadIcon /> Upload files
           * </UploadButton>
           * ```
           */
          export function UploadButton({
            accept,
            typesLabel,
            maxSize,
            maxFiles,
            multiple = true,
            onRejected,
            disabled,
            className,
            children,
            ...props
          }: UploadButtonProps) {
            const { getRootProps, getInputProps, isDragActive, isDragReject, isFull } =
              useUploadDropzone({
                accept,
                typesLabel,
                maxSize,
                maxFiles,
                multiple,
                disabled,
                onRejected,
                // A <button> already opens the dialog on Enter and Space.
                noKeyboard: true,
              });

            // react-dropzone keeps its hidden input in the layout, so it is wrapped with the
            // button to keep it out of the parent's gaps.
            return (
              <span className="inline-flex">
                <Button
                  {...props}
                  {...getRootProps({ role: 'button' })}
                  {...dropzoneState({ isDragActive, isDragReject })}
                  type="button"
                  disabled={disabled || isFull}
                  className={cn(
                    'data-[dragging]:ring-[3px] data-[dragging]:ring-ring/50 data-[rejected]:ring-destructive/40',
                    className,
                  )}
                >
                  {children}
                </Button>
                <input {...getInputProps()} />
              </span>
            );
          }

          ````
        </LimitedCode>
      </Step>
    </Steps>
  </OpenTabsContent>
</OpenTabs>

## Usage

Install or copy the component from [Installation](#installation) before using this example.

```tsx
'use client';

import { UploadErrors } from '@/components/upload/dropzone';
import { FileList } from '@/components/upload/multi-file';
import { UploadButton } from '@/components/upload/upload-button';
import {
  UploaderProvider,
  type UploadFn,
} from '@/components/upload/uploader-provider';
import { useEdgeStore } from '@/lib/edgestore';
import { UploadIcon } from 'lucide-react';
import * as React from 'react';

export function UploadButtonUsage() {
  const [errors, setErrors] = React.useState<string[]>([]);
  const { edgestore } = useEdgeStore();

  const uploadFn: UploadFn = React.useCallback(
    async ({ file, onProgressChange, signal }) => {
      const res = await edgestore.publicFiles.upload({
        file,
        signal,
        onProgressChange,
      });
      // you can run some server action or api here
      // to add the necessary data to your database
      console.log(res);
      return res;
    },
    [edgestore],
  );

  return (
    <UploaderProvider uploadFn={uploadFn} autoUpload>
      <UploadButton
        maxSize={1024 * 1024 * 1} // 1 MB
        onRejected={setErrors}
      >
        <UploadIcon /> Upload files
      </UploadButton>
      <UploadErrors errors={errors} onDismiss={() => setErrors([])} />
      <FileList />
    </UploaderProvider>
  );
}
```

## Props

| Prop                   | Type                           | Default   | Description                                                                                                              |
| ---------------------- | ------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------ |
| `maxFiles`             | `number`                       |           | Maximum number of files in total.                                                                                        |
| `multiple`             | `boolean`                      | `true`    | Whether more than one file can be picked at once.                                                                        |
| `onRejected`           | `(messages: string[]) => void` |           | Called with messages about files that were not added.                                                                    |
| `maxSize`              | `number`                       |           | Maximum file size in bytes.                                                                                              |
| `accept`               | `Accept`                       | all types | Accepted file types, in [react-dropzone's format](https://react-dropzone.js.org/#section-accepting-specific-file-types). |
| `typesLabel`           | `string`                       |           | Human-readable list of accepted types, shown in the hint and in error messages.                                          |
| `disabled`             | `boolean`                      | `false`   | Disables the component.                                                                                                  |
| `variant`, `size`, ... |                                |           | Any other [Button](https://ui.shadcn.com/docs/components/button) prop.                                                   |


# EdgeStore Docs: Uploader Provider
URL: https://edgestore.dev/docs/components/uploader-provider
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/components/uploader-provider.mdx



import { LimitedCode } from '@/components/ui/limited-code';
import {
  OpenTabs,
  OpenTabsContent,
  OpenTabsList,
  OpenTabsTrigger,
} from '@/components/ui/open-tabs';
import { Callout } from 'fumadocs-ui/components/callout';

<Callout>
  If you are installing the other dropzone components via the CLI, this
  component will be installed automatically. You can skip the following steps.
</Callout>

## Installation

<OpenTabs defaultValue="cli">
  <OpenTabsList>
    <OpenTabsTrigger value="cli">
      CLI
    </OpenTabsTrigger>

    <OpenTabsTrigger value="manual">
      Manual
    </OpenTabsTrigger>
  </OpenTabsList>

  <OpenTabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager" persist>
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add https://edgestore.dev/r/uploader-provider.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add https://edgestore.dev/r/uploader-provider.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add https://edgestore.dev/r/uploader-provider.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add https://edgestore.dev/r/uploader-provider.json
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </OpenTabsContent>

  <OpenTabsContent value="manual">
    ### Copy this component

    <LimitedCode>
      ````tsx title="components/upload/uploader-provider.tsx"
      'use client';

      import * as React from 'react';

      /**
       * Represents the possible statuses of a file in the uploader.
       */
      export type FileStatus = 'PENDING' | 'UPLOADING' | 'COMPLETE' | 'ERROR';

      /**
       * Represents the state of a file in the uploader.
       */
      export type FileState = {
        /** The file object being uploaded */
        file: File;

        /** Unique identifier for the file */
        key: string;

        /** Upload progress (0-100) */
        progress: number;

        /** Current status of the file */
        status: FileStatus;

        /** URL of the uploaded file (available when status is COMPLETE) */
        url?: string;

        /** Error message if the upload failed */
        error?: string;
      };

      /**
       * Represents a file that has completed uploading.
       */
      export type CompletedFileState = Omit<FileState, 'status' | 'url'> & {
        /** Status is guaranteed to be 'COMPLETE' */
        status: 'COMPLETE';

        /** URL is guaranteed to be available */
        url: string;
      };

      /**
       * Function type for handling file uploads.
       */
      export type UploadFn<TOptions = unknown> = (props: {
        /** The file to be uploaded */
        file: File;

        /** AbortSignal to cancel the upload */
        signal: AbortSignal;

        /** Callback to update progress */
        onProgressChange: (progress: number) => void | Promise<void>;

        /** Additional options */
        options?: TOptions;
      }) => Promise<{ url: string }>;

      /**
       * Context type for the UploaderProvider.
       */
      type UploaderContextType<TOptions = unknown> = {
        /** List of all files in the uploader */
        fileStates: FileState[];

        /** Add files to the uploader. Returns the new file states. */
        addFiles: (files: File[]) => FileState[];

        /** Update a file's state */
        updateFileState: (key: string, changes: Partial<FileState>) => void;

        /** Remove a file from the uploader, aborting its upload if it is running */
        removeFile: (key: string) => void;

        /**
         * Cancel an ongoing upload. With `autoUpload` the file is removed,
         * otherwise it goes back to `PENDING`.
         */
        cancelUpload: (key: string) => void;

        /**
         * Upload files that are `PENDING` or `ERROR` (so it also retries failed uploads).
         * Pass keys to upload only those files.
         */
        uploadFiles: (keysToUpload?: string[], options?: TOptions) => Promise<void>;

        /** Remove all files, aborting any running uploads */
        resetFiles: () => void;

        /** Whether any file is currently uploading */
        isUploading: boolean;

        /** Whether files are uploaded as soon as they are added */
        autoUpload: boolean;
      };

      /**
       * Props for the UploaderProvider component.
       */
      type ProviderProps<TOptions = unknown> = {
        /** React children or render function */
        children:
          | React.ReactNode
          | ((context: UploaderContextType<TOptions>) => React.ReactNode);

        /** Callback when files change */
        onChange?: (args: {
          allFiles: FileState[];
          completedFiles: CompletedFileState[];
        }) => void | Promise<void>;

        /** Callback when a file is added */
        onFileAdded?: (file: FileState) => void | Promise<void>;

        /** Callback when a file is removed */
        onFileRemoved?: (key: string) => void | Promise<void>;

        /** Callback when a file upload completes */
        onUploadCompleted?: (file: CompletedFileState) => void | Promise<void>;

        /** Function to handle the actual upload */
        uploadFn: UploadFn<TOptions>;

        /** External value to control the file states */
        value?: FileState[];

        /** Whether files should be automatically uploaded when added */
        autoUpload?: boolean;
      };

      const UploaderContext =
        React.createContext<UploaderContextType<unknown> | null>(null);

      /**
       * Hook to access the uploader context.
       *
       * @throws Error if used outside of UploaderProvider
       *
       * @example
       * ```tsx
       * const { fileStates, addFiles, uploadFiles } = useUploader();
       * ```
       */
      export function useUploader<TOptions = unknown>() {
        const context = React.useContext(UploaderContext);
        if (!context) {
          throw new Error('useUploader must be used within a UploaderProvider');
        }
        return context as UploaderContextType<TOptions>;
      }

      /**
       * Holds the files of an uploader and runs their uploads.
       *
       * @example
       * ```tsx
       * <UploaderProvider
       *   uploadFn={async ({ file, signal, onProgressChange }) => {
       *     // Upload implementation
       *     return { url: 'https://example.com/uploads/image.jpg' };
       *   }}
       *   autoUpload
       * >
       *   <ImageUploader maxFiles={5} maxSize={1024 * 1024 * 2} />
       * </UploaderProvider>
       * ```
       */
      export function UploaderProvider<TOptions = unknown>({
        children,
        onChange,
        onFileAdded,
        onFileRemoved,
        onUploadCompleted,
        uploadFn,
        value: externalValue,
        autoUpload = false,
      }: ProviderProps<TOptions>) {
        const [fileStates, setFileStates] = React.useState<FileState[]>(
          externalValue ?? [],
        );
        // Abort controllers of running uploads, by file key.
        const controllers = React.useRef(new Map<string, AbortController>());

        // Sync with external value if provided
        React.useEffect(() => {
          if (externalValue) {
            setFileStates(externalValue);
          }
        }, [externalValue]);

        const updateFileState = React.useCallback(
          (key: string, changes: Partial<FileState>) => {
            setFileStates((prev) =>
              prev.map((fileState) =>
                fileState.key === key ? { ...fileState, ...changes } : fileState,
              ),
            );
          },
          [],
        );

        const upload = React.useCallback(
          async (fileState: FileState, options?: TOptions) => {
            const { key, file } = fileState;
            const controller = new AbortController();
            controllers.current.set(key, controller);
            updateFileState(key, {
              status: 'UPLOADING',
              progress: 0,
              error: undefined,
            });

            try {
              const { url } = await uploadFn({
                file,
                signal: controller.signal,
                onProgressChange: (progress) => {
                  if (!controller.signal.aborted) updateFileState(key, { progress });
                },
                options,
              });

              // Let the progress bar reach 100% before showing the completed state.
              await new Promise((resolve) => setTimeout(resolve, 500));
              if (controller.signal.aborted) return;

              updateFileState(key, { status: 'COMPLETE', progress: 100, url });
              void onUploadCompleted?.({
                ...fileState,
                status: 'COMPLETE',
                progress: 100,
                url,
                error: undefined,
              });
            } catch (err: unknown) {
              // cancelUpload/removeFile already updated the state.
              if (controller.signal.aborted) return;
              if (process.env.NODE_ENV === 'development') {
                console.error(err);
              }
              updateFileState(key, {
                status: 'ERROR',
                error: err instanceof Error ? err.message : 'Upload failed',
              });
            } finally {
              if (controllers.current.get(key) === controller) {
                controllers.current.delete(key);
              }
            }
          },
          [updateFileState, uploadFn, onUploadCompleted],
        );

        const uploadFiles = React.useCallback(
          async (keysToUpload?: string[], options?: TOptions) => {
            const filesToUpload = fileStates.filter(
              (fileState) =>
                (fileState.status === 'PENDING' || fileState.status === 'ERROR') &&
                (!keysToUpload || keysToUpload.includes(fileState.key)),
            );
            await Promise.all(
              filesToUpload.map((fileState) => upload(fileState, options)),
            );
          },
          [fileStates, upload],
        );

        const addFiles = React.useCallback(
          (files: File[]) => {
            if (files.length === 0) return [];
            const newFileStates = files.map<FileState>((file) => ({
              file,
              key: `${file.name}-${Date.now()}-${Math.random().toString(36).slice(2)}`,
              progress: 0,
              status: 'PENDING',
            }));
            setFileStates((prev) => [...prev, ...newFileStates]);
            newFileStates.forEach((fileState) => {
              void onFileAdded?.(fileState);
              if (autoUpload) void upload(fileState);
            });
            return newFileStates;
          },
          [autoUpload, onFileAdded, upload],
        );

        const removeFile = React.useCallback(
          (key: string) => {
            controllers.current.get(key)?.abort();
            setFileStates((prev) =>
              prev.filter((fileState) => fileState.key !== key),
            );
            void onFileRemoved?.(key);
          },
          [onFileRemoved],
        );

        const cancelUpload = React.useCallback(
          (key: string) => {
            const controller = controllers.current.get(key);
            if (!controller) return;
            controller.abort();
            if (autoUpload) {
              removeFile(key);
            } else {
              updateFileState(key, { status: 'PENDING', progress: 0 });
            }
          },
          [autoUpload, removeFile, updateFileState],
        );

        const resetFiles = React.useCallback(() => {
          controllers.current.forEach((controller) => controller.abort());
          setFileStates([]);
        }, []);

        // Abort running uploads when the provider unmounts.
        React.useEffect(() => {
          const running = controllers.current;
          return () => {
            running.forEach((controller) => controller.abort());
          };
        }, []);

        React.useEffect(() => {
          const completedFiles = fileStates.filter(
            (fs): fs is CompletedFileState => fs.status === 'COMPLETE' && !!fs.url,
          );
          void onChange?.({ allFiles: fileStates, completedFiles });
        }, [fileStates, onChange]);

        const isUploading = fileStates.some((fs) => fs.status === 'UPLOADING');

        const value = React.useMemo(
          () => ({
            fileStates,
            addFiles,
            updateFileState,
            removeFile,
            cancelUpload,
            uploadFiles,
            resetFiles,
            isUploading,
            autoUpload,
          }),
          [
            fileStates,
            addFiles,
            updateFileState,
            removeFile,
            cancelUpload,
            uploadFiles,
            resetFiles,
            isUploading,
            autoUpload,
          ],
        );

        return (
          <UploaderContext.Provider value={value as UploaderContextType<unknown>}>
            {typeof children === 'function' ? children(value) : children}
          </UploaderContext.Provider>
        );
      }

      ````
    </LimitedCode>
  </OpenTabsContent>
</OpenTabs>

## Usage

Install or copy the component from [Installation](#installation) before using these examples.

This section provides a step-by-step guide on how to use the `UploaderProvider` and the `useUploader` hook.

### 1. Setup `<UploaderProvider>`

Wrap the part of your application that needs uploader functionality with `UploaderProvider`. You must provide an `uploadFn` and can optionally configure `autoUpload`.

* **`uploadFn`**: An asynchronous function that handles the actual file upload. It receives the `file`, an `onProgressChange` callback, and an `AbortSignal`. It should return an object with the uploaded file's `url`.
* **`autoUpload`**: (Optional, default: `false`) If `true`, files will start uploading immediately after being added.

```tsx
import { UploaderProvider, UploadFn } from '@/components/upload/uploader-provider';
import { useEdgeStore } from '@/lib/edgestore'; // Adjust import path
import * as React from 'react';

function MyUploaderPage() {
  const { edgestore } = useEdgeStore();

  // Define the upload function
  const uploadFn: UploadFn = React.useCallback(
    async ({ file, onProgressChange, signal }) => {
      // Example using Edge Store client
      const res = await edgestore.publicFiles.upload({
        file,
        signal,
        onProgressChange,
      });
      // you can run some server action or api here
      // to add the necessary data to your database
      console.log('Upload successful:', res);
      return res; // Must return { url: string }
    },
    [edgestore],
  );

  return (
    // Provide the uploadFn and configure autoUpload
    <UploaderProvider uploadFn={uploadFn}>
      {/* Your uploader components go here */}
      <MyUploaderComponent />
    </UploaderProvider>
  );
}

// export default MyUploaderPage; // Assuming MyUploaderComponent is defined below
```

### 2. Use the `useUploader` Hook

Inside components nested under `UploaderProvider`, use the `useUploader` hook to access the uploader's state and control functions.

```tsx
import { useUploader } from '@/components/upload/uploader-provider';
import * as React from 'react';

function MyUploaderComponent() {
  const {
    fileStates, // Array of current file states
    addFiles, // Function to add files
    removeFile, // Function to remove a file by key
    cancelUpload, // Function to cancel an upload by key
    uploadFiles, // Function to trigger uploads (all pending or specific keys)
    isUploading, // Boolean indicating if any upload is in progress
  } = useUploader();

  // ... component logic using these values and functions ...

  return <div>{/* UI elements */}</div>;
}
```

### 3. Adding Files (`addFiles`)

Typically, you'll use a standard file input. You might hide it and trigger its click event from a custom button. Get the selected `File` objects from the input's `onChange` event and pass them to `addFiles`.

```tsx
function MyUploaderComponent() {
  const { addFiles } = useUploader();
  const inputRef = React.useRef<HTMLInputElement>(null);

  // Handle file selection from the input
  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    if (e.target.files) {
      addFiles(Array.from(e.target.files));
      // Optional: Reset input value to allow selecting the same file again
      e.target.value = '';
    }
  };

  // Trigger the hidden input click
  const handleAddClick = () => {
    inputRef.current?.click();
  };

  return (
    <div>
      {/* Hidden file input */}
      <input
        type="file"
        ref={inputRef}
        onChange={handleFileChange}
        multiple // Allow multiple files
        style={{ display: 'none' }}
      />
      {/* Button to open file selector */}
      <button onClick={handleAddClick}>Add Files</button>
      {/* ... rest of the component ... */}
    </div>
  );
}
```

### 4. Displaying File State (`fileStates`)

The `fileStates` array contains objects representing each file. Each object includes:

* `file`: The original `File` object.
* `key`: A unique string identifier.
* `status`: `'PENDING'`, `'UPLOADING'`, `'COMPLETE'`, or `'ERROR'`.
* `progress`: Upload progress (0-100).
* `url`: (Optional) The URL after successful upload (`status === 'COMPLETE'`).
* `error`: (Optional) Error message if upload failed (`status === 'ERROR'`).

Iterate over `fileStates` to render the UI for each file.

```tsx
function MyUploaderComponent() {
  const { fileStates, removeFile, cancelUpload } = useUploader();

  return (
    <div>
      {/* ... Add files button/input ... */}

      {/* List of files */}
      {fileStates.length > 0 && (
        <ul>
          {fileStates.map((fileState) => (
            <li key={fileState.key}>
              <span>{fileState.file.name}</span>
              <span> ({fileState.status})</span>
              {/* Show progress during upload */}
              {fileState.status === 'UPLOADING' && (
                <span> {fileState.progress}%</span>
              )}
              {/* Show cancel button during upload */}
              {fileState.status === 'UPLOADING' && (
                <button onClick={() => cancelUpload(fileState.key)}>
                  Cancel
                </button>
              )}
              {/* Show remove button otherwise */}
              {fileState.status !== 'UPLOADING' && (
                <button onClick={() => removeFile(fileState.key)}>
                  Remove
                </button>
              )}
              {/* Show error message */}
              {fileState.status === 'ERROR' && (
                <span style={{ color: 'red', marginLeft: '0.5rem' }}>
                  {' '}
                  Error: {fileState.error}
                </span>
              )}
              {/* Show link on completion */}
              {fileState.status === 'COMPLETE' && fileState.url && (
                <a
                  href={fileState.url}
                  target="_blank"
                  rel="noopener noreferrer"
                  style={{ color: 'green', marginLeft: '0.5rem' }}
                >
                  View File
                </a>
              )}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}
```

### 5. Triggering Uploads (`uploadFiles`)

Call `uploadFiles()` to upload all files with status `'PENDING'` or `'ERROR'`. You can optionally pass an array of specific file keys to `uploadFiles(keysToUpload)` to upload only those files. Use the `isUploading` boolean to disable the upload button during active uploads.

Since failed files are included, `uploadFiles([fileState.key])` is also how you retry a single failed upload:

```tsx
{
  fileState.status === 'ERROR' && (
    <button onClick={() => uploadFiles([fileState.key])}>Retry</button>
  );
}
```

```tsx
function MyUploaderComponent() {
  const { uploadFiles, isUploading, fileStates } = useUploader();

  // Check if there are any files pending upload
  const hasPendingFiles = fileStates.some((fs) => fs.status === 'PENDING');

  return (
    <div>
      {/* ... Add files button/input and file list ... */}

      {/* Upload button */}
      <button
        onClick={() => uploadFiles()} // Uploads all pending files
        disabled={isUploading || !hasPendingFiles} // Disable if uploading or no pending files
      >
        {isUploading ? 'Uploading...' : 'Upload All Pending'}
      </button>
    </div>
  );
}
```

### 6. Cancelling Uploads (`cancelUpload`)

Call `cancelUpload(key)` with the file's unique key to abort an ongoing upload. With `autoUpload`, the file is removed. Otherwise it goes back to `'PENDING'` so it can be uploaded again. Your `uploadFn` must pass the `AbortSignal` on (EdgeStore's `upload` accepts it as `signal`) for cancellation to stop the request.

```tsx
// Example within the file list rendering (see step 4)
{
  fileState.status === 'UPLOADING' && (
    <button onClick={() => cancelUpload(fileState.key)}>Cancel</button>
  );
}
```

### 7. Removing Files (`removeFile`)

Call `removeFile(key)` with the file's key to remove it from the list, regardless of its status. If the file is currently uploading, the upload is aborted. Removing a completed file only removes it from the uploader; it doesn't delete it from storage. Use `onFileRemoved` if you need to do that.

```tsx
// Example within the file list rendering (see step 4)
{
  <button onClick={() => removeFile(fileState.key)}>Remove</button>;
}
```

### 8. Callbacks

You can pass callback props (`onChange`, `onFileAdded`, `onFileRemoved`, `onUploadCompleted`) to the `UploaderProvider` to execute logic when the uploader state changes.

```tsx
<UploaderProvider
  uploadFn={uploadFn}
  onChange={({ allFiles, completedFiles }) => {
    console.log('Files changed:', allFiles);
    console.log('Completed files:', completedFiles);
  }}
  onFileAdded={(fileState) => console.log('File added:', fileState.file.name)}
  onUploadCompleted={(completedFile) =>
    console.log('Upload complete:', completedFile.url)
  }
>
  {/* ... */}
</UploaderProvider>
```

### Complete Component Example (`MyUploaderComponent`)

Here is the `MyUploaderComponent` combining the steps above:

```tsx
import { useUploader } from '@/components/upload/uploader-provider';
import * as React from 'react';

function MyUploaderComponent() {
  const {
    fileStates,
    addFiles,
    removeFile,
    cancelUpload,
    uploadFiles,
    isUploading,
  } = useUploader();
  const inputRef = React.useRef<HTMLInputElement>(null);

  // Function to handle file selection
  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    if (e.target.files) {
      addFiles(Array.from(e.target.files));
      e.target.value = ''; // Reset input
    }
  };

  // Function to trigger the hidden file input
  const handleAddClick = () => {
    inputRef.current?.click();
  };

  const hasPendingFiles = fileStates.some((fs) => fs.status === 'PENDING');

  return (
    <div>
      {/* Hidden file input */}
      <input
        type="file"
        ref={inputRef}
        onChange={handleFileChange}
        multiple // Allow multiple file selection
        style={{ display: 'none' }}
      />

      {/* Buttons */}
      <button onClick={handleAddClick} disabled={isUploading}>
        Add Files
      </button>
      <button
        onClick={() => uploadFiles()}
        disabled={isUploading || !hasPendingFiles}
      >
        {isUploading ? 'Uploading...' : 'Upload All Pending'}
      </button>

      {/* Display file states */}
      {fileStates.length > 0 && (
        <ul style={{ listStyle: 'none', padding: 0, marginTop: '1rem' }}>
          {fileStates.map((fileState) => (
            <li
              key={fileState.key}
              style={{
                marginBottom: '0.5rem',
                borderBottom: '1px solid #eee',
                paddingBottom: '0.5rem',
              }}
            >
              <span>{fileState.file.name}</span>
              <span
                style={{
                  marginLeft: '0.5rem',
                  fontSize: '0.8em',
                  color: '#666',
                }}
              >
                {' '}
                ({fileState.status})
              </span>
              {/* Progress and Controls */}
              <div style={{ marginTop: '0.25rem' }}>
                {fileState.status === 'UPLOADING' && (
                  <>
                    <progress
                      value={fileState.progress}
                      max="100"
                      style={{ width: '100px', marginRight: '0.5rem' }}
                    />
                    <span> {fileState.progress}%</span>
                    <button
                      onClick={() => cancelUpload(fileState.key)}
                      style={{ marginLeft: '0.5rem' }}
                    >
                      Cancel
                    </button>
                  </>
                )}
                {fileState.status !== 'UPLOADING' && (
                  <button
                    onClick={() => removeFile(fileState.key)}
                    style={{ marginLeft: '0.5rem' }}
                  >
                    Remove
                  </button>
                )}
                {fileState.status === 'ERROR' && (
                  <span style={{ color: 'red', marginLeft: '0.5rem' }}>
                    {' '}
                    Error: {fileState.error}
                  </span>
                )}
                {fileState.status === 'COMPLETE' && fileState.url && (
                  <a
                    href={fileState.url}
                    target="_blank"
                    rel="noopener noreferrer"
                    style={{ color: 'green', marginLeft: '0.5rem' }}
                  >
                    View File
                  </a>
                )}
              </div>
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}
```

### Putting It All Together (`MyUploaderPage`)

Finally, use the `MyUploaderComponent` within the page component wrapped by the `UploaderProvider`.

```tsx
import { UploaderProvider, UploadFn } from '@/components/upload/uploader-provider';
import { useEdgeStore } from '@/lib/edgestore'; // Adjust import path
import * as React from 'react';

// Assume MyUploaderComponent is defined in the same file or imported
// import { MyUploaderComponent } from './MyUploaderComponent';

function MyUploaderPage() {
  const { edgestore } = useEdgeStore();

  // Define the upload function (same as in step 1)
  const uploadFn: UploadFn = React.useCallback(
    async ({ file, onProgressChange, signal }) => {
      const res = await edgestore.publicFiles.upload({
        file,
        signal,
        onProgressChange,
      });
      console.log('Upload successful:', res);
      return res;
    },
    [edgestore],
  );

  return (
    <div>
      <h1>My File Uploader</h1>
      <UploaderProvider
        uploadFn={uploadFn}
        onUploadCompleted={(completedFile) => {
          console.log(
            `File ${completedFile.file.name} uploaded successfully to ${completedFile.url}`,
          );
          // Maybe trigger a database update here
        }}
      >
        <MyUploaderComponent />
      </UploaderProvider>
    </div>
  );
}

export default MyUploaderPage;
```

This provides a basic but functional file uploader using the context provider. You can style the elements and integrate them further into your application's UI.


# EdgeStore Docs: Astro
URL: https://edgestore.dev/docs/adapters/astro
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/adapters/astro.mdx



The Astro adapter handles server requests. The upload UI below uses a hydrated
React component.

## Setup

### Install

<CodeBlockTabs defaultValue="npm" groupId="package-manager" persist>
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### Environment variables

Copy your project's keys from the [dashboard](https://dashboard.edgestore.dev) to the backend env file:

```sh title=".env"
EDGESTORE_ACCESS_KEY=your-access-key
EDGESTORE_SECRET_KEY=your-secret-key
```

<Callout type="warning">
  Add `.env` to `.gitignore`.
</Callout>

### Backend

Configure an [Astro server adapter](https://docs.astro.build/en/guides/on-demand-rendering/)
for your deployment and enable the React integration for the UI below. The
EdgeStore endpoint must run on demand; a static-only deployment cannot serve it.

Create `src/pages/api/edgestore/[...edgestore].ts`:

```ts
import { initEdgeStore } from '@edgestore/server';
import { createEdgeStoreAstroHandler } from '@edgestore/server/adapters/astro';

export const prerender = false;

const es = initEdgeStore.create();

const router = es.router({
  publicFiles: es.fileBucket(),
});

const handler = createEdgeStoreAstroHandler({
  router,
});

export { handler as GET, handler as POST };

export type EdgeStoreRouter = typeof router;
```

This bucket's files are accessible to anyone with the link.

### Frontend

Create the React provider:

```tsx title="src/lib/edgestore.ts"
import { createEdgeStoreProvider } from '@edgestore/react';
import type { EdgeStoreRouter } from '../pages/api/edgestore/[...edgestore].ts';

const { EdgeStoreProvider, useEdgeStore } =
  createEdgeStoreProvider<EdgeStoreRouter>();

export { EdgeStoreProvider, useEdgeStore };
```

Create the upload component:

```tsx title="src/components/FileUploader.tsx"
import { useState } from 'react';
import { EdgeStoreProvider, useEdgeStore } from '../lib/edgestore';

export function FileUploader() {
  return (
    <EdgeStoreProvider>
      <FileUploaderInner />
    </EdgeStoreProvider>
  );
}

function FileUploaderInner() {
  const [file, setFile] = useState<File | null>(null);
  const { edgestore } = useEdgeStore();

  return (
    <div>
      <input
        type="file"
        onChange={(e) => {
          setFile(e.target.files?.[0] ?? null);
        }}
      />
      <button
        onClick={async () => {
          if (file) {
            const res = await edgestore.publicFiles.upload({
              file,
              onProgressChange: (progress) => {
                // you can use this to show a progress bar
                console.log(progress);
              },
            });
            // you can run some server action or api here
            // to add the necessary data to your database
            console.log(res);
          }
        }}
      >
        Upload
      </button>
    </div>
  );
}
```

Hydrate the component with `client:load`:

```astro title="src/pages/index.astro"
---
import { FileUploader } from '../components/FileUploader';
---

<html lang="en">
  {/* ... */}
  <body>
    <h1>EdgeStore with Astro</h1>
    <FileUploader client:load />
  </body>
</html>
```


# EdgeStore Docs: Express
URL: https://edgestore.dev/docs/adapters/express
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/adapters/express.mdx



## Setup

### Install

<CodeBlockTabs defaultValue="npm" groupId="package-manager" persist>
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### Environment variables

Copy your project's keys from the [dashboard](https://dashboard.edgestore.dev) to the backend env file:

```sh title=".env"
EDGESTORE_ACCESS_KEY=your-access-key
EDGESTORE_SECRET_KEY=your-secret-key
```

<Callout type="warning">
  Add `.env` to `.gitignore`.
</Callout>

### Backend

This example uses Express 5. Keep your existing middleware and load the backend
env file before constructing the provider; Express does not load it automatically.

This bucket's files are accessible to anyone with the link.

```ts
import { initEdgeStore } from '@edgestore/server';
import { createEdgeStoreExpressHandler } from '@edgestore/server/adapters/express';
import cookieParser from 'cookie-parser';
import cors from 'cors';
import express from 'express';

const PORT = process.env.PORT ?? 3001;

const app = express();

app.use(
  cors({
    // Replace with your frontend origin.
    origin: 'http://localhost:5173',
    credentials: true,
  }),
);
app.use(cookieParser());
app.use(express.json());

const es = initEdgeStore.create();

const router = es.router({
  publicFiles: es.fileBucket(),
});

export type EdgeStoreRouter = typeof router;

const handler = createEdgeStoreExpressHandler({
  router,
});

app.get('/edgestore/*splat', handler);
app.post('/edgestore/*splat', handler);

app.listen(PORT, () => {
  console.log(`Server running at http://localhost:${PORT}`);
});
```

Express 5 requires a named wildcard. On Express 4, use `/edgestore/*` instead.
See [Express 5 route syntax](https://expressjs.com/en/guide/migrating-5.html#path-syntax).

### Frontend

Create the React provider:

```tsx title="src/lib/edgestore.ts"
// Import the router type from your backend.
import type { EdgeStoreRouter } from '../../../path/to/express-backend/src';
import { createEdgeStoreProvider } from '@edgestore/react';

const { EdgeStoreProvider, useEdgeStore } =
  createEdgeStoreProvider<EdgeStoreRouter>();

export { EdgeStoreProvider, useEdgeStore };
```

Wrap your app with the provider:

```tsx title="src/App.tsx"
// [!code ++]
import { EdgeStoreProvider } from '../lib/edgestore';

function App() {
  return (
    <EdgeStoreProvider basePath="http://localhost:3001/edgestore">
      {/* Rest of your app */}
    </EdgeStoreProvider>
  );
}
```

## Usage

See [Quick start](/docs/quick-start) for the upload UI.

## Limitations

<Callout type="warning">
  In production, serve the frontend and backend on the same domain. Use
  [Vercel rewrites](https://vercel.com/docs/edge-network/rewrites) or a reverse proxy.
</Callout>


# EdgeStore Docs: Fastify
URL: https://edgestore.dev/docs/adapters/fastify
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/adapters/fastify.mdx



## Setup

### Install

<CodeBlockTabs defaultValue="npm" groupId="package-manager" persist>
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### Environment variables

Copy your project's keys from the [dashboard](https://dashboard.edgestore.dev) to the backend env file:

```sh title=".env"
EDGESTORE_ACCESS_KEY=your-access-key
EDGESTORE_SECRET_KEY=your-secret-key
```

<Callout type="warning">
  Add `.env` to `.gitignore`.
</Callout>

### Backend

Load the backend env file before constructing the provider; Fastify does not
load it automatically. Reuse existing cookie and CORS registrations.

This bucket's files are accessible to anyone with the link.

```ts
import { initEdgeStore } from '@edgestore/server';
import { createEdgeStoreFastifyHandler } from '@edgestore/server/adapters/fastify';
import cors from '@fastify/cors';
import cookie from '@fastify/cookie';
import fastify from 'fastify';

const PORT = process.env.PORT ?? 3001;

const app = fastify();

await app.register(cors, {
  // Replace with your frontend origin.
  origin: 'http://localhost:5173',
  credentials: true,
});

await app.register(cookie);

const es = initEdgeStore.create();

const router = es.router({
  publicFiles: es.fileBucket(),
});

export type EdgeStoreRouter = typeof router;

const handler = createEdgeStoreFastifyHandler({
  router,
});

app.get('/edgestore/*', handler);
app.post('/edgestore/*', handler);

app.listen({ port: PORT }, (err) => {
  if (err) {
    console.error(err);
    process.exit(1);
  }
  console.log(`Server running at http://localhost:${PORT}`);
});
```

### Frontend

Create the React provider:

```tsx title="src/lib/edgestore.ts"
// Import the router type from your backend.
import type { EdgeStoreRouter } from '../../../path/to/fastify-backend/src';
import { createEdgeStoreProvider } from '@edgestore/react';

const { EdgeStoreProvider, useEdgeStore } =
  createEdgeStoreProvider<EdgeStoreRouter>();

export { EdgeStoreProvider, useEdgeStore };
```

Wrap your app with the provider:

```tsx title="src/App.tsx"
// [!code ++]
import { EdgeStoreProvider } from '../lib/edgestore';

function App() {
  return (
    <EdgeStoreProvider basePath="http://localhost:3001/edgestore">
      {/* Rest of your app */}
    </EdgeStoreProvider>
  );
}
```

## Usage

See [Quick start](/docs/quick-start) for the upload UI.

## Limitations

<Callout type="warning">
  In production, serve the frontend and backend on the same domain. Use
  [Vercel rewrites](https://vercel.com/docs/edge-network/rewrites) or a reverse proxy.
</Callout>


# EdgeStore Docs: Hono
URL: https://edgestore.dev/docs/adapters/hono
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/adapters/hono.mdx



## Setup

### Install

Install `@edgestore/server` in the backend and `@edgestore/react` in the frontend.

<CodeBlockTabs defaultValue="npm" groupId="package-manager" persist>
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### Environment variables

Copy your project's keys from the [dashboard](https://dashboard.edgestore.dev) to the backend env file:

```sh title=".env.local (backend only)"
EDGESTORE_ACCESS_KEY=your-access-key
EDGESTORE_SECRET_KEY=your-secret-key
```

<Callout type="warning">
  Load the env file in the backend before creating the provider, and keep it gitignored.
  The [Hono example](https://github.com/edgestorejs/edgestore/tree/main/examples/hono-basic) loads `.env.local` in its dev command.
</Callout>

### Backend

This bucket's files are accessible to anyone with the link.

```ts
import { initEdgeStore } from '@edgestore/server';
import { createEdgeStoreHonoHandler } from '@edgestore/server/adapters/hono';
import { serve } from '@hono/node-server';
import { Hono } from 'hono';
import { cors } from 'hono/cors';

const PORT = process.env.PORT ?? 3001;
const frontendOrigin = process.env.FRONTEND_ORIGIN ?? 'http://localhost:5173';
const app = new Hono();

app.use(
  '/edgestore/*',
  cors({
    origin: frontendOrigin,
    credentials: true,
  }),
);

const es = initEdgeStore.create();

const router = es.router({
  publicFiles: es.fileBucket(),
});

export type EdgeStoreRouter = typeof router;

const handler = createEdgeStoreHonoHandler({
  router,
});

app.all('/edgestore/*', handler);

serve(
  {
    fetch: app.fetch,
    port: Number(PORT),
  },
  (info) => {
    console.log(`Server running at http://localhost:${info.port}`);
  },
);
```

### Frontend

Create the React provider:

```tsx title="src/lib/edgestore.ts"
// Import the router type from your backend.
import { type EdgeStoreRouter } from '../../../path/to/hono-backend/src';
import { createEdgeStoreProvider } from '@edgestore/react';

const { EdgeStoreProvider, useEdgeStore } =
  createEdgeStoreProvider<EdgeStoreRouter>();

export { EdgeStoreProvider, useEdgeStore };
```

Wrap your app with the provider:

```tsx title="src/App.tsx"
// [!code ++]
import { EdgeStoreProvider } from '../lib/edgestore';

function App() {
  return (
    <EdgeStoreProvider basePath={import.meta.env.VITE_EDGESTORE_BASE_PATH ?? '/edgestore'}>
      {/* Rest of your app */}
    </EdgeStoreProvider>
  );
}
```

For separate Vite and Hono dev servers, set these values to match your ports:

* Frontend: `VITE_EDGESTORE_BASE_PATH=http://localhost:3001/edgestore`
* Backend: `FRONTEND_ORIGIN=http://localhost:5173`

Across repositories, share the backend router's type through a package.

## Usage

See [Quick start](/docs/quick-start) for the upload UI.

## Limitations

<Callout type="warning">
  In production, serve the frontend and backend on the same domain. Use
  [Vercel rewrites](https://vercel.com/docs/edge-network/rewrites) or a reverse proxy.
</Callout>


# EdgeStore Docs: Next Adapter
URL: https://edgestore.dev/docs/adapters/next
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/adapters/next.mdx



There are two adapters available for Next.js. The `next-app` (for the app-router) and the `next-pages` (for the pages-router).

The steps to set up the adapter are in the main [Quick Start](/docs/quick-start) guide.


# EdgeStore Docs: Remix / React Router
URL: https://edgestore.dev/docs/adapters/remix
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/adapters/remix.mdx



Use the Remix adapter with Remix or React Router framework mode. A client-only
React Router application needs a separate backend; this route runs on the server.

## Setup

### Install

<CodeBlockTabs defaultValue="npm" groupId="package-manager" persist>
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### Environment variables

Copy your project's keys from the [dashboard](https://dashboard.edgestore.dev) to the backend env file:

```sh title=".env"
EDGESTORE_ACCESS_KEY=your-access-key
EDGESTORE_SECRET_KEY=your-secret-key
```

<Callout type="warning">
  Add `.env` to `.gitignore`.
</Callout>

### Backend

Create the EdgeStore API route:

```ts title="app/routes/api/edgestore.ts"
import { initEdgeStore } from '@edgestore/server';
import { createEdgeStoreRemixHandler } from '@edgestore/server/adapters/remix';

const es = initEdgeStore.create();

const router = es.router({
  publicFiles: es.fileBucket(),
});

export type EdgeStoreRouter = typeof router;

const handler = createEdgeStoreRemixHandler({
  router,
});

export { handler as loader, handler as action };
```

For React Router framework mode, add the endpoint to your existing routes file:

```ts title="app/routes.ts"
import { index, route, type RouteConfig } from '@react-router/dev/routes';

export default [
  index('routes/home.tsx'),
  // [!code ++]
  route('api/edgestore/*', 'routes/api/edgestore.ts'),
] satisfies RouteConfig;
```

For Remix v2's default file-based routing, put the same handler in
`app/routes/api.edgestore.$.ts` instead. For custom routing, see
[Remix route conventions](https://v2.remix.run/docs/file-conventions/routes/)
and [React Router routing](https://reactrouter.com/start/framework/routing).

### Frontend

Create the React provider:

```tsx title="app/lib/edgestore.ts"
import { createEdgeStoreProvider } from '@edgestore/react';
import type { EdgeStoreRouter } from '~/routes/api/edgestore';

const { EdgeStoreProvider, useEdgeStore } =
  createEdgeStoreProvider<EdgeStoreRouter>();

export { EdgeStoreProvider, useEdgeStore };
```

Point the type-only import at your actual route module; for the Remix filename
above, use `~/routes/api.edgestore.$`.

Wrap the root component with the provider:

```tsx title="app/root.tsx"
// [!code ++]
import { EdgeStoreProvider } from '~/lib/edgestore';

// ...

export default function App() {
  return (
    <EdgeStoreProvider>
      <Outlet />
    </EdgeStoreProvider>
  );
}
```

## Usage

See [Quick start](/docs/quick-start) for the upload UI.


# EdgeStore Docs: TanStack Start
URL: https://edgestore.dev/docs/adapters/tanstack-start
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/adapters/tanstack-start.mdx



## Setup

### Install

<CodeBlockTabs defaultValue="npm" groupId="package-manager" persist>
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @edgestore/server@rc @edgestore/react@rc
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### Environment variables

Copy your project's keys from the [dashboard](https://dashboard.edgestore.dev) to the backend env file:

```sh title=".env.local"
EDGESTORE_ACCESS_KEY=your-access-key
EDGESTORE_SECRET_KEY=your-secret-key
```

<Callout type="warning">
  Use the app's existing env file, or `.env.local` for a new app. Keep it gitignored.
</Callout>

### Backend

Create the EdgeStore API route:

```ts title="src/routes/api/edgestore.$.ts"
import { initEdgeStore } from '@edgestore/server';
import { createEdgeStoreStartHandler } from '@edgestore/server/adapters/start';
import { createFileRoute } from '@tanstack/react-router';

const es = initEdgeStore.create();
const router = es.router({
  publicFiles: es.fileBucket(),
});

export type EdgeStoreRouter = typeof router;

const handler = createEdgeStoreStartHandler({
  router,
});

export const Route = createFileRoute('/api/edgestore/$')({
  server: {
    handlers: {
      GET: handler,
      POST: handler,
    },
  },
});
```

### Frontend

Create the React provider:

```tsx title="src/utils/edgestore.ts"
import { createEdgeStoreProvider } from '@edgestore/react';
import { type EdgeStoreRouter } from '../routes/api/edgestore.$';

const { EdgeStoreProvider, useEdgeStore } =
  createEdgeStoreProvider<EdgeStoreRouter>();

export { EdgeStoreProvider, useEdgeStore };
```

Wrap your app with the provider:

```tsx title="src/routes/__root.tsx"
// [!code ++]
import { EdgeStoreProvider } from '~/utils/edgestore';

// ...

function RootComponent() {
  return (
    <EdgeStoreProvider>
      <Outlet />
    </EdgeStoreProvider>
  );
}
```

## Usage

See [Quick start](/docs/quick-start) for the upload UI.


# EdgeStore Docs: Azure Blob Storage
URL: https://edgestore.dev/docs/providers/azure-blob
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/providers/azure-blob.mdx



Use the Azure Blob provider when your files must live in your own Azure
storage account. It supports direct browser uploads, automatic block uploads
for large files, backend uploads, private signed reads, and stable key
references. Your application owns the container's CORS, access, and lifecycle
configuration.

The provider creates short-lived, blob-scoped SAS URLs for browser uploads and
private reads. The account key stays on the server, and permanent file URLs
never contain credentials. Hosted features such as image processing are not
available.

## Installation

<CodeBlockTabs defaultValue="npm" groupId="package-manager" persist>
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @azure/storage-blob
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @azure/storage-blob
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @azure/storage-blob
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @azure/storage-blob
    ```
  </CodeBlockTab>
</CodeBlockTabs>

```ts
import { initEdgeStore } from '@edgestore/server';
import { azureBlob } from '@edgestore/server/providers/azure-blob';

const es = initEdgeStore.create();
export const router = es.router({
  documents: es.fileBucket().accessControl('private'),
}).provider(
  azureBlob({
    storageAccountName: 'myaccount',
    containerName: 'edgestore',
  }),
);

export type EdgeStoreRouter = typeof router;
```

Pass `router` to your framework adapter as its `router` option. Set
`ES_AZURE_ACCOUNT_KEY` on the server, and set `EDGESTORE_JWT_SECRET` to a
stable random secret, for example one generated with `openssl rand -base64 32`.
All application instances must share it. Credentials are only checked when the
provider is first used, so defining a router does not require them.

| Option                       | Default / environment variable                                                         |
| ---------------------------- | -------------------------------------------------------------------------------------- |
| `storageAccountName`         | `ES_AZURE_ACCOUNT_NAME`                                                                |
| `storageAccountKey`          | `ES_AZURE_ACCOUNT_KEY`                                                                 |
| `containerName`              | `ES_AZURE_CONTAINER_NAME`                                                              |
| `endpoint`                   | `ES_AZURE_ENDPOINT`, otherwise `https://<account>.blob.core.windows.net`               |
| `baseUrl`                    | `EDGESTORE_BASE_URL`, otherwise `<endpoint>/<container>`                               |
| `uploadUrlExpiresIn`         | 3600 seconds                                                                           |
| `signedUrlExpiresIn`         | 3600 seconds                                                                           |
| `multipart.thresholdBytes`   | 100 MiB                                                                                |
| `multipart.partSizeBytes`    | 16 MiB; minimum 5 MiB, maximum 4000 MiB                                                |
| `multipart.sessionExpiresIn` | 86400 seconds                                                                          |
| `jwtSecret`                  | Multipart signing override; otherwise `EDGESTORE_JWT_SECRET` or `EDGESTORE_SECRET_KEY` |

Signed URL lifetimes must be between 1 and 604800 seconds. Upload URLs grant
only create/write permission on one blob, and read URLs grant only read
permission.

## Paths and object settings

Blobs are stored as `<router bucket>/<path>`. The default path adds `_public/`
for public buckets, then the router path values and the file name. Use `path`
to change everything after the router bucket, which is always kept:

```ts
azureBlob({
  path: ({ defaultPath }) => `tenants/${defaultPath}`,
  objectOptions: {
    cacheControl: 'private, max-age=3600',
    contentDisposition: 'attachment',
    metadata: { source: 'edgestore' },
  },
});
```

`objectOptions` can also be a function that receives the same arguments as
`path`. The content type comes from the uploaded file. Browser and backend
uploads apply the same settings.

## Large files and cancellation

Files above the threshold are uploaded as blocks, in parallel, with retries.
The browser requests block upload URLs as it reaches each block, so
`uploadUrlExpiresIn` only needs to cover one block transfer. A session can
request URLs and complete until `multipart.sessionExpiresIn` passes. Before
committing, the provider checks that every block exists with the expected size,
which catches incomplete uploads.

Azure has no multipart session to cancel. Blocks that are never committed are
discarded automatically after seven days, so canceled and failed uploads need
no lifecycle rule.

Backend uploads use the same paths, object settings, and block configuration,
and send up to four blocks at a time.

## Private files

Use `accessControl('private')` for private buckets. Cookie-based access-control
rules are not supported and fail at initialization. Create read URLs from the
backend client:

```ts
const { signedUrl } = await router.client.documents.createSignedUrl({
  url: { key: 'documents/report.pdf' },
  expiresIn: 300,
});
```

Add `.autoSignedUrls({ expiresIn: 300 })` to a private router bucket to receive
a read URL with each upload response.

## Container configuration

Keep the container private. Azure grants anonymous read access to a whole
container, not to a prefix, so public buckets need their own read path.
Public uploads return an unsigned URL under `_public/`, which a private
container answers with 403. Either:

* serve `_public/` through a CDN or proxy that can read the private container,
  such as Azure Front Door with a private origin, and set `baseUrl` to it; or
* if the container holds only public buckets, set its public access level to
  **Blob** (anonymous reads of individual blobs, no listing). Every file in
  that container is then readable by URL, so never combine this with private
  buckets.

Configure blob service CORS for your application origins so browsers can
upload:

```json
[{
  "AllowedOrigins": ["http://localhost:3000", "https://app.example.com"],
  "AllowedMethods": ["PUT", "GET", "HEAD"],
  "AllowedHeaders": ["*"],
  "ExposedHeaders": ["*"],
  "MaxAgeInSeconds": 3600
}]
```

## Local development with Azurite

[Azurite](https://learn.microsoft.com/azure/storage/common/storage-use-azurite)
emulates Blob Storage locally:

```bash
docker run -p 10000:10000 mcr.microsoft.com/azure-storage/azurite azurite-blob --blobHost 0.0.0.0
```

```ts
azureBlob({
  storageAccountName: 'devstoreaccount1',
  // Azurite's documented development account key.
  storageAccountKey:
    'Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==',
  containerName: 'edgestore',
  endpoint: 'http://127.0.0.1:10000/devstoreaccount1',
});
```

## Limitations

* `temporary` and `replaceTargetUrl` are rejected. Track application-owned files
  in your database and delete old files after a successful replacement.
* Azure SAS URLs grant write access to one blob and cannot limit its size or
  the write operation. A browser holding an upload URL can therefore write
  that blob directly, with any size and blob headers. The router's `maxSize`,
  mime-type checks, and `objectOptions` apply to the declared upload and to
  backend uploads, but are not enforced on bytes a browser sends. If you need
  those guarantees, validate each stored blob after upload from a storage
  event, for example an Event Grid `BlobCreated` subscription that triggers an
  Azure Function, and delete blobs that fail your checks.
* Confirmation, listing, restore, and generated thumbnails are unsupported.
* Only account-key authentication is supported.


# EdgeStore Docs: Custom
URL: https://edgestore.dev/docs/providers/custom
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/providers/custom.mdx



Use `defineProvider` to integrate another storage service or a custom storage
implementation. The same provider instance powers the EdgeStore HTTP handler
and the router-derived backend client:

```ts
const router = es.router({
  files: es.fileBucket(),
}).provider(myProvider);

createEdgeStoreNextHandler({ router });
router.client.files.get({ key: 'files/report.pdf' });
```

Method inputs are contextually typed. File references, cursors, returned file
fields, and provider-specific errors are inferred from the definition, so you
do not need to maintain a parallel provider interface or backend-operation
map.

## Minimal provider

A provider must implement the upload-planning operations used by browser
uploads and `files.get`, which EdgeStore uses to resolve a file before running
router lifecycle hooks. Other operations are optional and only appear on the
backend client when implemented.

This single-part example delegates storage-specific work to a small driver:

```ts title="src/lib/my-provider.ts"
import { defineProvider } from '@edgestore/server';
import { z } from 'zod';
import { storage } from './storage';

const baseUrl = 'https://files.example.com';

export const myProvider = defineProvider({
  name: 'my-storage',
  async init() {
    return {};
  },
  reference: {
    schema: z.object({ key: z.string().min(1) }),
    fromUrl(url) {
      return { key: new URL(url).pathname.slice(1) };
    },
  },
  uploads: {
    async request({ bucketName, fileInfo }) {
      const key = storage.createKey({ bucketName, fileInfo });
      return {
        uploadUrl: await storage.signUpload(key),
        url: `${baseUrl}/${key}`,
      };
    },
  },
  files: {
    async get({ bucketName, file }) {
      const object = await storage.head({
        bucketName,
        key: file.key,
      });
      return {
        url: `${baseUrl}/${file.key}`,
        sizeBytes: object.size,
        path: object.path,
        metadata: object.metadata,
        uploadedAt: object.createdAt,
        updatedAt: object.updatedAt,
      };
    },
  },
});
```

The resulting backend client exposes `get`, but not `upload`, `list`, or
mutations, because those optional capabilities were not defined.

`init` runs when the browser initializes EdgeStore. Return `{}` unless the
browser must prepare access to your file origin before loading protected
files. In that case, return `clientInit` with the absolute URLs to request and
any headers to send; the browser calls each URL with credentials:

```ts
async init({ ctx }) {
  return {
    clientInit: {
      urls: ['https://files.example.com/_init'],
      headers: { 'x-file-token': await createFileToken(ctx) },
    },
  };
},
```

## Complete provider

A complete provider can add direct backend uploads, pagination, mutations, and
signed read URLs. Standard Schema transformations let callers use convenient
input references while provider methods receive one normalized output shape:

```ts title="src/lib/my-provider.ts"
import { defineProvider } from '@edgestore/server';
import { z } from 'zod';
import { storage } from './storage';

const baseUrl = 'https://files.example.com';
const referenceSchema = z
  .union([z.string().url(), z.object({ key: z.string().min(1) })])
  .transform((reference) =>
    typeof reference === 'string'
      ? { key: new URL(reference).pathname.slice(1) }
      : reference,
  );

const toFile = (object: Awaited<ReturnType<typeof storage.head>>) => ({
  url: `${baseUrl}/${object.key}`,
  sizeBytes: object.size,
  path: object.path,
  metadata: object.metadata,
  uploadedAt: object.createdAt,
  updatedAt: object.updatedAt,
  etag: object.etag,
});

export const myProvider = defineProvider({
  name: 'my-storage',
  async init() {
    return {};
  },
  reference: {
    schema: referenceSchema,
    fromUrl: (url) => url,
  },
  uploads: {
    async request({ bucketName, fileInfo }) {
      return storage.createUploadPlan({ bucketName, fileInfo });
    },
    multipart: {
      async requestParts({ uploadId, key, parts }) {
        return { parts: await storage.signUploadParts({ uploadId, key, parts }) };
      },
      async complete({ uploadId, key, parts }) {
        await storage.completeMultipart({ uploadId, key, parts });
      },
      async abort({ uploadId, key }) {
        await storage.abortMultipart({ uploadId, key });
      },
    },
    async upload({ bucketName, fileInfo, source, signal, onProgress }) {
      const object = await storage.upload({
        bucketName,
        fileInfo,
        source,
        signal,
        onProgress,
      });
      return { file: toFile(object) };
    },
  },
  files: {
    cursorSchema: z.string().min(1),
    async get({ bucketName, file }) {
      return toFile(
        await storage.head({
          bucketName,
          key: file.key,
        }),
      );
    },
    async list({ bucketName, cursor, filter, limit = 20 }) {
      const page = await storage.list({ bucketName, cursor, filter, limit });
      return {
        items: page.objects.map(toFile),
        limit,
        nextCursor: page.nextCursor,
        hasMore: page.nextCursor !== null,
      };
    },
    async confirm({ bucketName, files }) {
      return {
        results: await storage.confirm({
          bucketName,
          files,
        }),
      };
    },
    async delete({ bucketName, files }) {
      return {
        results: await storage.delete({
          bucketName,
          files,
        }),
      };
    },
    async restore({ bucketName, files }) {
      return {
        results: await storage.restore({
          bucketName,
          files,
        }),
      };
    },
    async getSignedUrls({ bucketName, files, expiresIn = 3600 }) {
      return Promise.all(
        files.map(async (file) => ({
          url: `${baseUrl}/${file.key}`,
          signedUrl: await storage.signRead({
            bucketName,
            key: file.key,
            expiresIn,
          }),
          expiresAt: new Date(Date.now() + expiresIn * 1000),
          expiresIn,
        })),
      );
    },
  },
});
```

Here, callers may pass either a URL or `{ key }`, but every provider operation
receives `{ key: string }` after runtime validation. The backend client also
inherits the string cursor, the extra `etag` file field, and any literal
mutation error codes returned by the storage driver.

The backend client uses bucket-scoped names: `get`, `list`, `confirm`,
`confirmMany`, `delete`, `deleteMany`, `restore`, `restoreMany`,
`createSignedUrl`, and `createSignedUrls`. Provider method names remain
resource operations (`files.get`, `files.list`, `files.getSignedUrls`) and do
not need to mirror that public client surface.

`get` and `list` preserve the exact file fields inferred from the provider,
including its `path` and `metadata` shapes. An `upload` result instead exposes
the path and metadata EdgeStore computed from the router, even if the storage
driver returns different placeholders.

Every file operation must enforce the logical EdgeStore `bucketName`. Treat
`bucketName` and the normalized file reference as the complete storage
identity, and reject a reference that belongs to another logical bucket. This
keeps a frontend request authorized through bucket A from loading or mutating a
file in bucket B. The official providers enforce the same ownership invariant.

Mutation providers return exactly one status for each input file, in the same
order. EdgeStore attaches the original file references and derives success and
failure counts for the public client. A provider result therefore contains
only `{ success: true }` or `{ success: false, error }`; it does not repeat the
file reference or calculate counts.

Multipart support is optional. A single-part provider defines only
`uploads.request`. When `uploads.multipart` is present, `uploads.request` may
return a multipart plan and EdgeStore exposes the matching part-request,
completion, and cancellation routes. The plan only needs signed URLs for the
first parts: the browser requests the rest through `requestParts` in batches as
it reaches them, and requests a fresh URL once when storage rejects one. The
browser calls `abort` after a failed or canceled transfer. Cleanup is best
effort, so storage lifecycle rules should still remove abandoned uploads.

A single-part plan can include `uploadHeaders`. The browser sends them with the
upload request, which lets a provider sign headers such as `Content-Type` or
storage metadata into the URL.

Return `id` from `uploads.request` when your storage assigns stable file IDs.
The browser upload result includes it so apps can save it.

If your storage processes files after the transfer, return `id` and implement
`uploads.getStatus({ bucketName, id })`. It returns
`{ status: 'processing' }`, `{ status: 'canceled' }`, or
`{ status: 'completed', file }` with the processed `url`, `key`,
`thumbnailUrl`, and `sizeBytes`. Browser uploads with `waitForProcessing` poll
it through an encrypted status token that only the uploading browser receives.
Providers without `getStatus` treat uploads as ready once the transfer
completes.

Set `uploads.supportedOptions` to reject upload options your storage cannot
honor. For example, `supportedOptions: { temporary: false }` removes
`temporary` from the browser and backend upload types, and EdgeStore rejects it
at runtime before calling the provider.

`uploads.request` and `uploads.upload` remain separate because they perform
different work: the former creates signed instructions for a browser transfer,
while the latter receives bytes and performs a privileged server-side upload.

## Operation groups

The provider is organized by storage resource, not by caller:

* `uploads` contains browser upload planning and optional direct backend
  upload.
* `files` contains canonical file operations shared by HTTP adapters and the
  backend client.
* `reference` defines how frontend URLs and backend inputs become the
  provider's normalized file reference.

Frontend deletion still obeys the router: EdgeStore loads every file and runs
`beforeDelete` for all of them before calling `files.delete`. The privileged
backend client calls `files.delete` directly and is responsible for its own
authorization.

The official EdgeStore, S3, and Azure Blob providers use `defineProvider`
themselves and are useful reference implementations. If your provider could be
useful to others, consider contributing it to EdgeStore.


# EdgeStore Docs: EdgeStore
URL: https://edgestore.dev/docs/providers/edgestore
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/providers/edgestore.mdx



The hosted EdgeStore provider uses API v2 and is the default for `es.router()`.
No provider configuration is needed when using environment credentials. Chain
`.provider(edgestore(options))` to supply custom credentials or an API URL.

```ts
import { initEdgeStore } from '@edgestore/server';
import {
  createEdgeStoreNextHandler,
  type CreateContextOptions,
} from '@edgestore/server/adapters/next/pages';
// [!code ++]
import { edgestore } from '@edgestore/server/providers/edgestore';
import { z } from 'zod';

const es = initEdgeStore.context<Context>().create();
const router = es.router({
  publicFiles: es.fileBucket(),
}).provider(edgestore());

export default createEdgeStoreNextHandler<Context>({
  router,
  createContext,
});
```

## Options

```ts
export type EdgeStoreProviderOptions = {
  /**
   * Access key for your EdgeStore project.
   * Can be found in the EdgeStore dashboard.
   *
   * This can be omitted if the `EDGESTORE_ACCESS_KEY` environment variable is set.
   */
  accessKey?: string;
  /**
   * Secret key for your EdgeStore project.
   * Can be found in the EdgeStore dashboard.
   *
   * This can be omitted if the `EDGESTORE_SECRET_KEY` environment variable is set.
   */
  secretKey?: string;
  /**
   * Override the API v2 base URL.
   */
  apiUrl?: string;
};
```


# EdgeStore Docs: S3
URL: https://edgestore.dev/docs/providers/s3
Source: https://raw.githubusercontent.com/edgestorejs/edgestore/refs/heads/main/docs/content/docs/providers/s3.mdx



The S3 provider supports direct browser uploads, automatic multipart uploads,
backend uploads, signed downloads, object lookup, and deletion. Your application
owns the bucket's IAM, CORS, read permissions, and lifecycle configuration.

## Setup

Install the optional AWS dependencies:

<CodeBlockTabs defaultValue="npm" groupId="package-manager" persist>
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Configure the provider on your router:

```ts title="src/server/edgestore.ts"
import { initEdgeStore } from '@edgestore/server';
import { s3 } from '@edgestore/server/providers/s3';

const es = initEdgeStore.create();
export const router = es.router({
  documents: es.fileBucket().accessControl('private'),
}).provider(s3({
  region: 'us-east-1',
  bucketName: 'my-storage-bucket',
}));

export type EdgeStoreRouter = typeof router;
```

Pass `router` to your framework adapter as its `router` option.
Set `EDGESTORE_JWT_SECRET` to a stable random secret, for example one generated
with `openssl rand -base64 32`. All application instances must share it.

Pass `credentials` with an AWS credentials object or provider function. If it
is unset, `ES_AWS_ACCESS_KEY_ID` and `ES_AWS_SECRET_ACCESS_KEY` are used when
both are set; otherwise the AWS SDK's default provider chain applies, including
environment variables, shared config, and instance/task roles.

| Option                       | Default / environment variable                                                         |
| ---------------------------- | -------------------------------------------------------------------------------------- |
| `bucketName`                 | `ES_AWS_BUCKET_NAME`                                                                   |
| `region`                     | `ES_AWS_REGION`, then AWS SDK region resolution                                        |
| `endpoint`                   | `ES_AWS_ENDPOINT`                                                                      |
| `forcePathStyle`             | `ES_AWS_FORCE_PATH_STYLE === 'true'`                                                   |
| `baseUrl`                    | `EDGESTORE_BASE_URL`, otherwise the storage URL                                        |
| `uploadUrlExpiresIn`         | 3600 seconds                                                                           |
| `signedUrlExpiresIn`         | 3600 seconds                                                                           |
| `multipart.thresholdBytes`   | 100 MiB                                                                                |
| `multipart.partSizeBytes`    | 16 MiB; minimum 5 MiB                                                                  |
| `multipart.sessionExpiresIn` | 86400 seconds                                                                          |
| `jwtSecret`                  | Multipart signing override; otherwise `EDGESTORE_JWT_SECRET` or `EDGESTORE_SECRET_KEY` |

Setting `jwtSecret` does not replace the required environment secret.
Signed URL lifetimes must be between 1 and 604800 seconds; temporary AWS
credentials can expire sooner.

## Paths and filenames

The default key is the logical router bucket, an optional `_public` segment,
router path values, and a generated UUID plus extension:

```text
documents/acme/generated-id.pdf
avatars/_public/user-123/generated-id.webp
```

Use the router's `.path(...)` for context/input-derived folders. Use
`options: { manualFileName: file.name }` on a browser upload to preserve the
original filename. A repeated key overwrites the existing object (or creates a
new version if bucket versioning is enabled). Generated names avoid accidental
collisions; use manual names only when overwrite behavior is intentional.

For custom layouts, the async `path` callback can rewrite everything beneath the
logical bucket prefix:

```ts
s3({
  path: ({ defaultPath }) => defaultPath.replace(/^_public\//, ''),
});
```

The callback receives `edgestoreBucketName`, `fileInfo` (including router path
values and metadata), and `defaultPath`. It cannot remove the logical bucket
prefix or use `.` / `..` path segments. For example, it can produce
`documents/acme/invoices/report.pdf`, but cannot place that file outside
`documents/`.

S3 uploads return a `key`. Save it in your database for backend lookup,
deletion, and signed URL creation, which accept `{ key }` or `{ url }`. Key
references continue to work when you change CDN domains. URL references must
match the currently configured `baseUrl`.

## Large files and cancellation

Keep using the normal React `upload({ file, onProgressChange, signal })` call.
Files above the threshold automatically use multipart uploads with retries.
Use `AbortController` to cancel an upload.

```ts
s3({
  multipart: {
    thresholdBytes: 100 * 1024 * 1024,
    partSizeBytes: 16 * 1024 * 1024,
  },
});
```

The browser requests part URLs as it reaches each part and refreshes a rejected
URL once, so `uploadUrlExpiresIn` only needs to cover one part transfer. A
multipart session can request URLs, complete, or abort until
`multipart.sessionExpiresIn` passes. Uploads do not resume across page reloads.

Backend uploads send up to four parts at a time through your S3 client, so the
client's retry and transport settings apply.

Configure an S3 lifecycle rule to clean up incomplete uploads left by browser
shutdowns, network loss, or failed cancellation:

```json
{
  "Rules": [{
    "ID": "abort-incomplete-uploads",
    "Status": "Enabled",
    "Filter": { "Prefix": "" },
    "AbortIncompleteMultipartUpload": { "DaysAfterInitiation": 1 }
  }]
}
```

Merge this rule into your existing lifecycle configuration.

## Private downloads

Keep the physical bucket private and use `.accessControl('private')`. Your
backend must authorize the caller before issuing a signed URL:

```ts
// After checking that the current user can read this database file record:
const download = await router.client.documents.createSignedUrl({
  url: { key: storedFileKey },
  expiresIn: 300,
});
// Send download.signedUrl to the browser.
```

The backend client is privileged; it does not authenticate application users for
you. Cookie-based access-control schemas are unsupported and rejected at adapter
initialization. A logical bucket's public/private setting does not configure S3
permissions. `_public` is a naming convention that you can use in infrastructure
rules. For example, an S3 policy can grant public reads to
`avatars/_public/*`, or a CloudFront behavior can allow public viewing of that
path while other behaviors require signed access. The prefix alone grants no
access. With CloudFront origin access control, the S3 bucket can remain private.
If you customize the path, update your access rules to match.

Add `.autoSignedUrls({ expiresIn: 300 })` to a private router bucket to receive a
signed read URL with upload results. Save the key or canonical URL, not the
expiring signed URL. Request a fresh signed URL when needed; the client does not
refresh private download URLs automatically. Browser upload read URLs begin
expiring when the upload is requested, so allow enough time for the transfer.

For public files, configure public reads or a CDN separately. `baseUrl` changes
canonical file URLs, but signed downloads still use the S3 endpoint; it does not
create CloudFront signed URLs.

## Backend uploads and object settings

Use the same configured router for generated files and background jobs:

```ts
const uploaded = await router.client.documents.upload({
  content: {
    blob: new Blob([pdfBytes], { type: 'application/pdf' }),
    extension: 'pdf',
  },
  options: { manualFileName: 'report.pdf' },
});
```

Backend uploads use the same path, object settings, and multipart configuration.
They accept Blob, text, or URL content. Streaming sources are not supported.

Use `objectOptions` for cache policy, download filenames, metadata, tags, storage
class, and S3/KMS encryption settings. It accepts a static object or an async
callback with the same arguments as `path`:

```ts
s3({
  objectOptions: ({ fileInfo }) => ({
    CacheControl: 'private, max-age=60',
    ContentDisposition: 'attachment',
    Metadata: { category: fileInfo.metadata.category ?? 'general' },
  }),
});
```

`ContentType` comes from the file's MIME type. File contents are not inspected.

For custom AWS retry/transport behavior, pass `client: new S3Client(...)`.
For browser uploads, configure that client with
`requestChecksumCalculation: 'WHEN_REQUIRED'`.
When injecting a client with a custom endpoint, also set `baseUrl` explicitly.

## IAM and CORS

A baseline application role policy is below. Replace the bucket name and narrow
object prefixes to your logical buckets where appropriate. KMS encryption needs
additional key permissions.

```json
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject", "s3:AbortMultipartUpload"],
    "Resource": "arn:aws:s3:::my-storage-bucket/*"
  }]
}
```

Configure bucket CORS for your actual application origins. Exposing `ETag` is
required for browser multipart completion:

```json
[{
  "AllowedOrigins": ["http://localhost:3000", "https://app.example.com"],
  "AllowedMethods": ["PUT", "GET", "HEAD"],
  "AllowedHeaders": ["*"],
  "ExposeHeaders": ["ETag"],
  "MaxAgeSeconds": 3600
}]
```

## S3-compatible services

`s3()` works with services that implement the S3 API, including Cloudflare R2,
Backblaze B2, DigitalOcean Spaces, Google Cloud Storage, Tigris, Supabase
Storage, and MinIO. Point `endpoint` at the service, pass its access keys as
`credentials` (or the `ES_AWS_ACCESS_KEY_ID` / `ES_AWS_SECRET_ACCESS_KEY`
environment variables), and configure bucket CORS as described above, including
exposing `ETag`.

The endpoint must be reachable from both your server and the browser. `baseUrl`
defaults to `<endpoint>/<bucket>`; set it to the service's public or CDN URL when
public files are served from a different host. Services differ in support for
tags, storage classes, and KMS encryption, so only set `objectOptions` your
service supports. EdgeStore's CI runs against MinIO; the setups below follow each
service's S3 compatibility documentation.

### Cloudflare R2

```ts
s3({
  bucketName: 'edgestore',
  region: 'auto',
  endpoint: 'https://<ACCOUNT_ID>.r2.cloudflarestorage.com',
  credentials: { accessKeyId: '...', secretAccessKey: '...' },
  // Public files: an r2.dev subdomain or a custom domain on the bucket.
  baseUrl: 'https://files.example.com',
});
```

Create the keys as an R2 API token. R2 does not support object tagging or KMS
encryption, and supports the `STANDARD` and `STANDARD_IA` storage classes.

### Backblaze B2

```ts
s3({
  bucketName: 'edgestore',
  region: 'us-west-004',
  endpoint: 'https://s3.us-west-004.backblazeb2.com',
  credentials: { accessKeyId: '<keyID>', secretAccessKey: '<applicationKey>' },
});
```

Use the region from your bucket's S3 endpoint and an application key. B2 does
not support object tagging or KMS encryption.

### DigitalOcean Spaces

```ts
s3({
  bucketName: 'edgestore',
  region: 'nyc3',
  endpoint: 'https://nyc3.digitaloceanspaces.com',
  credentials: { accessKeyId: '...', secretAccessKey: '...' },
  // Optional: serve public files through the Spaces CDN.
  baseUrl: 'https://edgestore.nyc3.cdn.digitaloceanspaces.com',
});
```

Spaces supports customer-provided encryption keys but not KMS encryption.

### Google Cloud Storage

```ts
s3({
  bucketName: 'edgestore',
  region: 'auto',
  endpoint: 'https://storage.googleapis.com',
  credentials: { accessKeyId: '<HMAC access ID>', secretAccessKey: '<HMAC secret>' },
});
```

Cloud Storage's XML API is S3-compatible when you use HMAC keys, including
signed URLs, multipart uploads, and multi-object delete. Create an HMAC key for a
service account with access to the bucket. Tagging and KMS headers are not
supported.

### Tigris

```ts
s3({
  bucketName: 'edgestore',
  region: 'auto',
  endpoint: 'https://t3.storage.dev',
  credentials: { accessKeyId: '...', secretAccessKey: '...' },
});
```

### Supabase Storage

```ts
s3({
  bucketName: 'edgestore',
  region: '<project region>',
  endpoint: 'https://<project_ref>.storage.supabase.co/storage/v1/s3',
  forcePathStyle: true,
  credentials: { accessKeyId: '...', secretAccessKey: '...' },
  // Public buckets are served from the object endpoint.
  baseUrl:
    'https://<project_ref>.supabase.co/storage/v1/object/public/edgestore',
});
```

Create S3 access keys in your project's storage settings. Supabase Storage does
not support object tagging, storage classes, or server-side encryption options.

### MinIO

```ts
s3({
  bucketName: 'edgestore',
  region: 'us-east-1',
  endpoint: 'http://localhost:9000',
  forcePathStyle: true,
});
```

## Limitations

* `temporary` and `replaceTargetUrl` are rejected. Track application-owned files
  in your database and delete old files after successful replacement.
* Confirmation, listing/filtering, restore, and provider-generated thumbnails are
  unsupported. Thumbnail options do not generate thumbnails.
* Router path/metadata values are returned at upload time but are not persisted
  as an EdgeStore index. `get()` returns key, URL, size, and S3 timestamps. Persist
  application metadata in your database or explicitly set S3 `Metadata`.
* No collision-prevention mode, automatic CDN invalidation, or version-specific
  object references. Standard S3 overwrite/delete and versioning rules apply.
* Browser multipart cleanup is best effort, not a substitute for lifecycle rules.