Upload Files

Title

Description

</div>
        
        <div>
          <label class="block text-sm font-medium mb-2">
            Files
          </label>
          <FileUpload />
        </div>
        
        <button
          type="submit"
          disabled={uploadAction.isRunning}
          class="w-full bg-blue-500 text-white p-3 rounded-lg hover:bg-blue-600 disabled:opacity-50"
        >
          {uploadAction.isRunning ? "Uploading..." : "Upload Files"}
        </button>
      </Form>
    </main>
  );
});

export const head: DocumentHead = {
  title: 'Upload Form',
};
```

## Troubleshooting

<Callout type="warn">
  **Common Issues**

1. **Route not found**: Ensure your route is `src/routes/api/upload/[...path]/index.ts`
  2. **Build errors**: Check that pushduck is properly installed and configured
  3. **Environment variables**: Use `import.meta.env.VITE_` prefix for client-side variables
  4. **Resumability**: Remember to use `$` suffix for event handlers and functions
</Callout>

### Debug Mode

Enable debug logging:

```typescript title="src/lib/upload.ts"
export const uploadRouter = createS3Router({
  // ... routes
}).middleware(async ({ req, file }) => {
  if (import.meta.env.DEV) {
    console.log("Upload request:", req.url);
    console.log("File:", file.name, file.size);
  }
  return {};
});
```

### Qwik Configuration

```typescript title="vite.config.ts"
import { defineConfig } from 'vite';
import { qwikVite } from '@builder.io/qwik/optimizer';
import { qwikCity } from '@builder.io/qwik-city/vite';

export default defineConfig(() => {
  return {
    plugins: [qwikCity(), qwikVite()],
    preview: {
      headers: {
        'Cache-Control': 'public, max-age=600',
      },
    },
    // Environment variables configuration
    define: {
      'import.meta.env.VITE_AWS_ACCESS_KEY_ID': JSON.stringify(process.env.VITE_AWS_ACCESS_KEY_ID),
    }
  };
});
```

Qwik provides a modern approach to web development with pushduck, offering instant loading and resumability while maintaining full compatibility with Web Standards APIs for optimal edge performance.

# Remix (/docs/integrations/remix)

import { Callout } from "fumadocs-ui/components/callout";
import { Card, Cards } from "fumadocs-ui/components/card";
import { Tab, Tabs } from "fumadocs-ui/components/tabs";
import { Steps, Step } from "fumadocs-ui/components/steps";
import { File, Folder, Files } from "fumadocs-ui/components/files";

## Using pushduck with Remix

Remix is a full-stack React framework focused on web standards and modern UX. It uses Web Standards APIs and provides server-side rendering with client-side hydration. Since Remix uses standard `Request`/`Response` objects, pushduck handlers work directly without any adapters!

<Callout type="info">
  **Web Standards Native**: Remix loader and action functions use Web Standard `Request`/`Response` objects, making pushduck integration straightforward with zero overhead.
</Callout>

## Quick Setup

<Steps>
  <Step>
    **Install dependencies**

```bash
    npm install pushduck
    ```
  </Step>

<Step>
    **Configure upload router**

```typescript title="app/lib/upload.ts"
    import { createUploadConfig } from 'pushduck/server';

const { s3, createS3Router } = createUploadConfig()
      .provider("cloudflareR2",{
        accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
        region: 'auto',
        endpoint: process.env.AWS_ENDPOINT_URL!,
        bucket: process.env.S3_BUCKET_NAME!,
        accountId: process.env.R2_ACCOUNT_ID!,
      })
      .build();

export const uploadRouter = createS3Router({
      imageUpload: s3.image().maxFileSize("5MB"),
      documentUpload: s3.file().maxFileSize("10MB")
    });

export type AppUploadRouter = typeof uploadRouter;
    ```
  </Step>

<Step>
    **Create API route**

```typescript title="app/routes/api.upload.$.tsx"
    import type { ActionFunctionArgs, LoaderFunctionArgs } from "@remix-run/node";
    import { uploadRouter } from "~/lib/upload";

// Direct usage - no adapter needed!
    export async function loader({ request }: LoaderFunctionArgs) {
      return uploadRouter.handlers(request);
    }

export async function action({ request }: ActionFunctionArgs) {
      return uploadRouter.handlers(request);
    }
    ```
  </Step>
</Steps>

## Basic Integration

### Simple Upload Route

```typescript title="app/routes/api.upload.$.tsx"
import type { ActionFunctionArgs, LoaderFunctionArgs } from "@remix-run/node";
import { uploadRouter } from "~/lib/upload";

// Method 1: Combined handler (recommended)
export async function loader({ request }: LoaderFunctionArgs) {
  return uploadRouter.handlers(request);
}

export async function action({ request }: ActionFunctionArgs) {
  return uploadRouter.handlers(request);
}

// Method 2: Method-specific handlers (if you need different logic)
export async function loader({ request }: LoaderFunctionArgs) {
  if (request.method === 'GET') {
    return uploadRouter.handlers.GET(request);
  }
  throw new Response("Method not allowed", { status: 405 });
}

export async function action({ request }: ActionFunctionArgs) {
  if (request.method === 'POST') {
    return uploadRouter.handlers.POST(request);
  }
  throw new Response("Method not allowed", { status: 405 });
}
```

### With Resource Route

```typescript title="app/routes/api.upload.$.tsx"
import type { ActionFunctionArgs, LoaderFunctionArgs } from "@remix-run/node";
import { uploadRouter } from "~/lib/upload";

// Handle CORS for cross-origin requests
export async function loader({ request }: LoaderFunctionArgs) {
  // Handle preflight requests
  if (request.method === 'OPTIONS') {
    return new Response(null, {
      status: 200,
      headers: {
        'Access-Control-Allow-Origin': '*',
        'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
        'Access-Control-Allow-Headers': 'Content-Type',
      },
    });
  }
  
  const response = await uploadRouter.handlers(request);
  
  // Add CORS headers
  response.headers.set('Access-Control-Allow-Origin', '*');
  
  return response;
}

export async function action({ request }: ActionFunctionArgs) {
  const response = await uploadRouter.handlers(request);
  
  // Add CORS headers
  response.headers.set('Access-Control-Allow-Origin', '*');
  
  return response;
}
```

## Advanced Configuration

### Authentication with Remix

```typescript title="app/lib/upload.ts"
import { createUploadConfig } from 'pushduck/server';
import { getSession } from '~/sessions';

const { s3, createS3Router } = createUploadConfig()
  .provider("cloudflareR2",{
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    region: 'auto',
    endpoint: process.env.AWS_ENDPOINT_URL!,
    bucket: process.env.S3_BUCKET_NAME!,
    accountId: process.env.R2_ACCOUNT_ID!,
  })
  .paths({
    prefix: 'uploads',
    generateKey: (file, metadata) => {
      return `${metadata.userId}/${Date.now()}/${file.name}`;
    }
  })
  .build();

export const uploadRouter = createS3Router({
  // Private uploads with session authentication
  privateUpload: s3
    .image()
    .maxFileSize("5MB")
    .middleware(async ({ req }) => {
      const cookie = req.headers.get("Cookie");
      const session = await getSession(cookie);
      
      if (!session.has("userId")) {
        throw new Error("Authentication required");
      }
      
      return {
        userId: session.get("userId"),
        username: session.get("username"),
      };
    }),

// Public uploads (no auth)
  publicUpload: s3
    .image()
    .maxFileSize("2MB")
    // No middleware = public access
});

export type AppUploadRouter = typeof uploadRouter;
```

## Client-Side Usage

### Remix Upload Hook

```typescript title="app/hooks/useUpload.ts"
import { useUpload } from "pushduck/client";
import type { AppUploadRouter } from "~/lib/upload";

export const { UploadButton, UploadDropzone } = useUpload<AppUploadRouter>({
  endpoint: "/api/upload",
});
```

### Upload Component

```tsx title="app/components/FileUpload.tsx"
import { UploadButton, UploadDropzone } from "~/hooks/useUpload";

export function FileUpload() {
  function handleUploadComplete(files: any[]) {
    console.log("Files uploaded:", files);
    alert("Upload completed!");
  }

function handleUploadError(error: Error) {
    console.error("Upload error:", error);
    alert(`Upload failed: ${error.message}`);
  }

return (
    <div className="space-y-6">
      <div>
        <h3 className="text-lg font-semibold mb-2">Image Upload</h3>
        <UploadButton
          endpoint="imageUpload"
          onClientUploadComplete={handleUploadComplete}
          onUploadError={handleUploadError}
        />
      </div>

<div>
        <h3 className="text-lg font-semibold mb-2">Document Upload</h3>
        <UploadDropzone
          endpoint="documentUpload"
          onClientUploadComplete={handleUploadComplete}
          onUploadError={handleUploadError}
        />
      </div>
    </div>
  );
}
```

### Using in Routes

```tsx title="app/routes/_index.tsx"
import { FileUpload } from "~/components/FileUpload";

export default function Index() {
  return (
    <div className="p-8">
      <h1 className="text-2xl font-bold mb-6">File Upload Demo</h1>
      <FileUpload />
    </div>
  );
}
```

## File Management

### Server-Side File Loader

```typescript title="app/routes/files.tsx"
import type { LoaderFunctionArgs } from "@remix-run/node";
import { json } from "@remix-run/node";
import { useLoaderData } from "@remix-run/react";
import { FileUpload } from "~/components/FileUpload";
import { getSession } from "~/sessions";

export async function loader({ request }: LoaderFunctionArgs) {
  const cookie = request.headers.get("Cookie");
  const session = await getSession(cookie);
  
  if (!session.has("userId")) {
    throw new Response("Unauthorized", { status: 401 });
  }
  
  const userId = session.get("userId");
  
  // Fetch files from database
  const files = await db.file.findMany({
    where: { userId },
    orderBy: { createdAt: 'desc' },
  });
  
  return json({
    files: files.map(file => ({
      id: file.id,
      name: file.name,
      url: file.url,
      size: file.size,
      uploadedAt: file.createdAt,
    })),
  });
}

export default function FilesPage() {
  const { files } = useLoaderData<typeof loader>();
  
  function formatFileSize(bytes: number): string {
    const sizes = ['Bytes', 'KB', 'MB', 'GB'];
    if (bytes === 0) return '0 Bytes';
    const i = Math.floor(Math.log(bytes) / Math.log(1024));
    return Math.round(bytes / Math.pow(1024, i) * 100) / 100 + ' ' + sizes[i];
  }

return (
    <div className="container mx-auto px-4 py-8">
      <h1 className="text-3xl font-bold mb-8">My Files</h1>
      
      <div className="mb-8">
        <FileUpload />
      </div>
      
      <div>
        <h2 className="text-2xl font-semibold mb-4">Uploaded Files</h2>
        
        {files.length === 0 ? (
          <p className="text-gray-500">No files uploaded yet.</p>
        ) : (
          <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
            {files.map((file) => (
              <div key={file.id} className="border rounded-lg p-4 hover:shadow-md transition-shadow">
                <h3 className="font-medium truncate" title={file.name}>
                  {file.name}
                </h3>
                <p className="text-sm text-gray-500">
                  {formatFileSize(file.size)}
                </p>
                <p className="text-sm text-gray-500">
                  {new Date(file.uploadedAt).toLocaleDateString()}
                </p>
                <a
                  href={file.url}
                  target="_blank"
                  rel="noopener noreferrer"
                  className="text-blue-500 hover:underline text-sm mt-2 inline-block"
                >
                  View File
                </a>
              </div>
            ))}
          </div>
        )}
      </div>
    </div>
  );
}
```

## Deployment Options

<Tabs items={["Vercel", "Netlify", "Fly.io", "Railway"]}>
  <Tab value="Vercel">
    ```typescript title="remix.config.js"
    /** @type {import('@remix-run/dev').AppConfig} */
    export default {
      ignoredRouteFiles: ["**/.*"],
      server: "./server.ts",
      serverBuildPath: "api/index.js",
      // Vercel configuration
      serverConditions: ["workerd", "worker", "browser"],
      serverDependenciesToBundle: "all",
      serverMainFields: ["browser", "module", "main"],
      serverMinify: true,
      serverModuleFormat: "esm",
      serverPlatform: "neutral",
    };
    ```
  </Tab>

<Tab value="Netlify">
    ```typescript title="remix.config.js"
    /** @type {import('@remix-run/dev').AppConfig} */
    export default {
      ignoredRouteFiles: ["**/.*"],
      server: "./server.ts",
      serverBuildPath: ".netlify/functions-internal/server.js",
      // Netlify configuration
      serverConditions: ["deno", "worker", "browser"],
      serverDependenciesToBundle: "all",
      serverMainFields: ["browser", "module", "main"],
      serverMinify: true,
      serverModuleFormat: "esm",
      serverPlatform: "neutral",
    };
    ```
  </Tab>

<Tab value="Fly.io">
    ```dockerfile title="Dockerfile"
    FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
    RUN npm ci --only=production

COPY . .
    RUN npm run build

EXPOSE 3000

CMD ["npm", "start"]
    ```
  </Tab>

<Tab value="Railway">
    ```json title="package.json"
    {
      "scripts": {
        "build": "remix build",
        "dev": "remix dev",
        "start": "remix-serve build",
        "typecheck": "tsc"
      }
    }
    ```
  </Tab>
</Tabs>

## Environment Variables

```bash title=".env"
# AWS Configuration
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_S3_BUCKET=your-bucket-name

# Session Secret
SESSION_SECRET=your-session-secret

# Database
DATABASE_URL=your-database-url
```

## Performance Benefits

## Real-Time Upload Progress

```tsx title="app/components/AdvancedUpload.tsx"
import { useState } from "react";

export function AdvancedUpload() {
  const [uploadProgress, setUploadProgress] = useState(0);
  const [isUploading, setIsUploading] = useState(false);

async function handleFileUpload(event: React.ChangeEvent<HTMLInputElement>) {
    const files = event.target.files;
    
    if (!files || files.length === 0) return;
    
    setIsUploading(true);
    setUploadProgress(0);
    
    try {
      // Simulate upload progress
      for (let i = 0; i <= 100; i += 10) {
        setUploadProgress(i);
        await new Promise(resolve => setTimeout(resolve, 100));
      }
      
      alert('Upload completed!');
    } catch (error) {
      console.error('Upload failed:', error);
      alert('Upload failed!');
    } finally {
      setIsUploading(false);
      setUploadProgress(0);
    }
  }

return (
    <div className="upload-container max-w-md mx-auto">
      <input
        type="file"
        multiple
        onChange={handleFileUpload}
        disabled={isUploading}
        className="w-full p-3 border-2 border-dashed border-gray-300 rounded-lg cursor-pointer disabled:opacity-50 disabled:cursor-not-allowed"
      />
      
      {isUploading && (
        <div className="mt-4">
          <div className="w-full h-2 bg-gray-200 rounded-full overflow-hidden">
            <div 
              className="h-full bg-green-500 transition-all duration-300 ease-out"
              style={{ width: `${uploadProgress}%` }}
            />
          </div>
          <p className="text-center mt-2 text-sm text-gray-600">
            {uploadProgress}% uploaded
          </p>
        </div>
      )}
    </div>
  );
}
```

## Form Integration

```tsx title="app/routes/upload-form.tsx"
import type { ActionFunctionArgs } from "@remix-run/node";
import { json, redirect } from "@remix-run/node";
import { Form, useActionData, useNavigation } from "@remix-run/react";

export async function action({ request }: ActionFunctionArgs) {
  const formData = await request.formData();
  const title = formData.get("title") as string;
  const description = formData.get("description") as string;
  
  // Handle form submission with file uploads
  // Files are already uploaded via pushduck, just save metadata
  
  return redirect("/files");
}

export default function UploadForm() {
  const actionData = useActionData<typeof action>();
  const navigation = useNavigation();
  const isSubmitting = navigation.state === "submitting";

return (
    <div className="max-w-2xl mx-auto p-6">
      <h1 className="text-2xl font-bold mb-6">Upload Files</h1>
      
      <Form method="post" className="space-y-6">
        <div>
          <label htmlFor="title" className="block text-sm font-medium mb-2">
            Title
          </label>
          <input
            type="text"
            id="title"
            name="title"
            required
            className="w-full p-3 border border-gray-300 rounded-lg"
          />
        </div>
        
        <div>
          <label htmlFor="description" className="block text-sm font-medium mb-2">
            Description
          </label>
          <textarea
            id="description"
            name="description"
            rows={4}
            className="w-full p-3 border border-gray-300 rounded-lg"
          />
        </div>
        
        <div>
          <label className="block text-sm font-medium mb-2">
            Files
          </label>
          <FileUpload />
        </div>
        
        <button
          type="submit"
          disabled={isSubmitting}
          className="w-full bg-blue-500 text-white p-3 rounded-lg hover:bg-blue-600 disabled:opacity-50"
        >
          {isSubmitting ? "Uploading..." : "Upload Files"}
        </button>
      </Form>
    </div>
  );
}
```

## Troubleshooting

<Callout type="warn">
  **Common Issues**

1. **Route not found**: Ensure your route is `app/routes/api.upload.$.tsx`
  2. **Build errors**: Check that pushduck is properly installed
  3. **Session issues**: Make sure your session configuration is correct
  4. **CORS errors**: Add proper CORS headers in your resource routes
</Callout>

### Debug Mode

Enable debug logging:

```typescript title="app/lib/upload.ts"
export const uploadRouter = createS3Router({
  // ... routes
}).middleware(async ({ req, file }) => {
  if (process.env.NODE_ENV === "development") {
    console.log("Upload request:", req.url);
    console.log("File:", file.name, file.size);
  }
  return {};
});
```

### Session Configuration

```typescript title="app/sessions.ts"
import { createCookieSessionStorage } from "@remix-run/node";

export const { getSession, commitSession, destroySession } =
  createCookieSessionStorage({
    cookie: {
      name: "__session",
      httpOnly: true,
      maxAge: 60 * 60 * 24 * 30, // 30 days
      path: "/",
      sameSite: "lax",
      secrets: [process.env.SESSION_SECRET!],
      secure: process.env.NODE_ENV === "production",
    },
  });
```

Remix provides an excellent foundation for building full-stack React applications with pushduck, combining the power of React with Web Standards APIs and progressive enhancement for optimal user experience.

# SolidJS Start (/docs/integrations/solidjs-start)

## Using pushduck with SolidJS Start

SolidJS Start is a full-stack SolidJS framework with built-in Web Standards support. Since SolidJS Start provides `event.request` as a Web Standard `Request` object, pushduck handlers work directly without any adapters!

<Callout type="info">
  **Web Standards Native**: SolidJS Start's API handlers receive `event.request` as a Web Standard `Request` object, making pushduck integration straightforward with zero overhead.
</Callout>

## Quick Setup

<Steps>
  <Step>
    **Install dependencies**

<Tabs items={["npm", "yarn", "pnpm", "bun"]}>
      <Tab value="npm">
        ```bash
        npm install pushduck
        ```
      </Tab>

<Tab value="yarn">
        ```bash
        yarn add pushduck
        ```
      </Tab>

<Tab value="pnpm">
        ```bash
        pnpm add pushduck
        ```
      </Tab>

<Tab value="bun">
        ```bash
        bun add pushduck
        ```
      </Tab>
    </Tabs>
  </Step>

<Step>
    **Configure upload router**

```typescript title="src/lib/upload.ts"
    import { createUploadConfig } from 'pushduck/server';

export const uploadRouter = createS3Router({
      imageUpload: s3.image().maxFileSize("5MB"),
      documentUpload: s3.file().maxFileSize("10MB")
    });

export type AppUploadRouter = typeof uploadRouter;
    ```
  </Step>

<Step>
    **Create API route**

```typescript title="src/routes/api/upload/[...path].ts"
    import { APIEvent } from '@solidjs/start/server';
    import { uploadRouter } from '~/lib/upload';

export async function GET(event: APIEvent) {
      return uploadRouter.handlers(event.request);
    }

export async function POST(event: APIEvent) {
      return uploadRouter.handlers(event.request);
    }
    ```
  </Step>
</Steps>

## Basic Integration

### API Route Handler

```typescript title="src/routes/api/upload/[...path].ts"
import { APIEvent } from '@solidjs/start/server';
import { uploadRouter } from '~/lib/upload';

// Method 1: Individual handlers
export async function GET(event: APIEvent) {
  return uploadRouter.handlers.GET(event.request);
}

export async function POST(event: APIEvent) {
  return uploadRouter.handlers.POST(event.request);
}

// Method 2: Combined handler (alternative approach)
// export async function handler(event: APIEvent) {
//   return uploadRouter.handlers(event.request);
// }
```

### With CORS Middleware

```typescript title="src/routes/api/upload/[...path].ts"
import { APIEvent } from '@solidjs/start/server';
import { uploadRouter } from '~/lib/upload';

function addCORSHeaders(response: Response) {
  response.headers.set('Access-Control-Allow-Origin', '*');
  response.headers.set('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
  response.headers.set('Access-Control-Allow-Headers', 'Content-Type, Authorization');
  return response;
}

export async function GET(event: APIEvent) {
  const response = await uploadRouter.handlers.GET(event.request);
  return addCORSHeaders(response);
}

export async function POST(event: APIEvent) {
  const response = await uploadRouter.handlers.POST(event.request);
  return addCORSHeaders(response);
}

export async function OPTIONS() {
  return new Response(null, {
    status: 200,
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    }
  });
}
```

## Advanced Configuration

### Authentication with SolidJS Start

```typescript title="src/lib/upload.ts"
import { createUploadConfig } from 'pushduck/server';

const { s3, createS3Router } = createUploadConfig()
  .provider("cloudflareR2",{
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    region: 'auto',
    endpoint: process.env.AWS_ENDPOINT_URL!,
    bucket: process.env.S3_BUCKET_NAME!,
    accountId: process.env.R2_ACCOUNT_ID!,
  })
  .paths({
    prefix: 'uploads',
    generateKey: (file, metadata) => {
      return `${metadata.userId}/${Date.now()}/${file.name}`;
    }
  })
  .build();

export const uploadRouter = createS3Router({
  // Private uploads with authentication
  privateUpload: s3
    .image()
    .maxFileSize("5MB")
    .middleware(async ({ req }) => {
      const authHeader = req.headers.get('authorization');
      if (!authHeader?.startsWith('Bearer ')) {
        throw new Error('Authorization required');
      }

// Public uploads (no auth)
  publicUpload: s3
    .image()
    .maxFileSize("2MB")
    // No middleware = public access
});

async function verifyJWT(token: string) {
  // Your JWT verification logic here
  return { id: 'user-123', role: 'user' };
}

export type AppUploadRouter = typeof uploadRouter;
```

### Protected API Routes

```typescript title="src/routes/api/upload/[...path].ts"
import { APIEvent } from '@solidjs/start/server';
import { uploadRouter } from '~/lib/upload';

async function requireAuth(request: Request) {
  const authHeader = request.headers.get('authorization');
  if (!authHeader?.startsWith('Bearer ')) {
    throw new Response(JSON.stringify({ error: 'Authorization required' }), {
      status: 401,
      headers: { 'Content-Type': 'application/json' }
    });
  }
  
  const token = authHeader.substring(7);
  // Verify token logic here
  return { userId: 'user-123' };
}

export async function GET(event: APIEvent) {
  await requireAuth(event.request);
  return uploadRouter.handlers.GET(event.request);
}

export async function POST(event: APIEvent) {
  await requireAuth(event.request);
  return uploadRouter.handlers.POST(event.request);
}
```

## Client-Side Integration

### Upload Component

```typescript title="src/components/UploadDemo.tsx"
import { createSignal } from 'solid-js';
import { createUploadClient } from 'pushduck/client';
import type { AppUploadRouter } from '~/lib/upload';

const uploadClient = createUploadClient<AppUploadRouter>({
  baseUrl: import.meta.env.DEV 
    ? 'http://localhost:3000' 
    : 'https://your-domain.com'
});

export function UploadDemo() {
  const [uploading, setUploading] = createSignal(false);
  const [results, setResults] = createSignal<any[]>([]);

return (
    <div class="space-y-4">
      <div>
        <input
          type="file"
          multiple
          accept="image/*"
          onChange={(e) => {
            const files = e.target.files;
            if (files) {
              handleUpload(Array.from(files));
            }
          }}
          disabled={uploading()}
          class="block w-full text-sm text-gray-500 file:mr-4 file:py-2 file:px-4 file:rounded-full file:border-0 file:text-sm file:font-semibold file:bg-blue-50 file:text-blue-700 hover:file:bg-blue-100"
        />
      </div>
      
      {uploading() && (
        <div class="text-blue-600">Uploading...</div>
      )}
      
      {results().length > 0 && (
        <div class="space-y-2">
          <h3 class="font-medium">Upload Results:</h3>
          {results().map((result, index) => (
            <div key={index} class="p-2 bg-gray-50 rounded">
              <div class="text-sm">
                <strong>File:</strong> {result.name}
              </div>
              <div class="text-sm">
                <strong>Public URL:</strong> 
                <a href={result.url} target="_blank" rel="noopener noreferrer" class="text-blue-600 hover:underline ml-1">
                  {result.url}
                </a>
              </div>
              {result.presignedUrl && (
                <div class="text-sm">
                  <strong>Download URL:</strong> 
                  <a href={result.presignedUrl} target="_blank" rel="noopener noreferrer" class="text-green-600 hover:underline ml-1">
                    {result.presignedUrl}
                  </a>
                  <span class="text-xs text-gray-500 ml-2">(expires in 1 hour)</span>
                </div>
              )}
            </div>
          ))}
        </div>
      )}
    </div>
  );
}
```

### Page Integration

```typescript title="src/routes/upload.tsx"
import { Title } from '@solidjs/meta';
import { UploadDemo } from '~/components/UploadDemo';

export default function UploadPage() {
  return (
    <>
      <Title>File Upload Demo</Title>
      <div class="container mx-auto px-4 py-8">
        <h1 class="text-3xl font-bold mb-8">File Upload Demo</h1>
        <div class="max-w-md mx-auto">
          <UploadDemo />
        </div>
      </div>
    </>
  );
}
```

## Full Application Example

### Project Structure

```
src/
├── components/
│   └── UploadDemo.tsx
├── lib/
│   └── upload.ts
├── routes/
│   ├── api/
│   │   └── upload/
│   │       └── [...path].ts
│   ├── upload.tsx
│   └── (home).tsx
├── app.tsx
└── entry-server.tsx
```

### Root Layout

```typescript title="src/app.tsx"
import { Router } from '@solidjs/router';
import { FileRoutes } from '@solidjs/start/router';
import { Suspense } from 'solid-js';
import './app.css';

export default function App() {
  return (
    <Router
      root={props => (
        <div class="min-h-screen bg-gray-50">
          <nav class="bg-white shadow">
            <div class="container mx-auto px-4 py-4">
              <h1 class="text-xl font-semibold">Upload Demo</h1>
            </div>
          </nav>
          <main>
            <Suspense>{props.children}</Suspense>
          </main>
        </div>
      )}
    >
      <FileRoutes />
    </Router>
  );
}
```

### Home Page

```typescript title="src/routes/(home).tsx"
import { A } from '@solidjs/router';
import { Title } from '@solidjs/meta';

export default function Home() {
  return (
    <>
      <Title>SolidJS Start + Pushduck</Title>
      <div class="container mx-auto px-4 py-8">
        <div class="text-center">
          <h1 class="text-4xl font-bold text-gray-900 mb-4">
            SolidJS Start + Pushduck
          </h1>
          <p class="text-xl text-gray-600 mb-8">
            High-performance file uploads with SolidJS
          </p>
          <A 
            href="/upload" 
            class="inline-block bg-blue-600 text-white px-6 py-3 rounded-lg hover:bg-blue-700 transition-colors"
          >
            Try Upload Demo
          </A>
        </div>
      </div>
    </>
  );
}
```

## Performance Benefits

<Cards>
  <Card title="Zero Overhead" description="Direct Web Standards integration">
    No adapter layer means zero performance overhead - pushduck handlers run directly in SolidJS Start.
  </Card>

<Card title="SolidJS Performance" description="Fastest reactive framework">
    SolidJS provides exceptional performance with fine-grained reactivity and no virtual DOM.
  </Card>

<Card title="Full-Stack TypeScript" description="End-to-end type safety">
    Complete type safety from server to client with shared types.
  </Card>

<Card title="File-Based Routing" description="Intuitive API structure">
    Clean, organized API routes with SolidJS Start's file-based routing system.
  </Card>
</Cards>

## Deployment

### Vercel Deployment

```typescript title="app.config.ts"
import { defineConfig } from '@solidjs/start/config';

export default defineConfig({
  server: {
    preset: 'vercel'
  }
});
```

### Netlify Deployment

```typescript title="app.config.ts"
import { defineConfig } from '@solidjs/start/config';

export default defineConfig({
  server: {
    preset: 'netlify'
  }
});
```

### Node.js Deployment

```typescript title="app.config.ts"
import { defineConfig } from '@solidjs/start/config';

export default defineConfig({
  server: {
    preset: 'node-server'
  }
});
```

### Docker Deployment

```dockerfile title="Dockerfile"
FROM node:18-alpine as base
WORKDIR /app

# Install dependencies
COPY package*.json ./
RUN npm ci --only=production

# Copy source code
COPY . .

# Build the app
RUN npm run build

# Expose port
EXPOSE 3000

# Start the app
CMD ["npm", "start"]
```

***

<Callout type="success">
  **SolidJS + Pushduck**: The perfect combination of SolidJS's exceptional performance and pushduck's universal design for lightning-fast file upload experiences.
</Callout>

# SvelteKit (/docs/integrations/sveltekit)

<Callout type="warning">
  **🚧 Client-Side In Development**: SvelteKit server-side integration is fully functional with Web Standards APIs. However, SvelteKit-specific client-side components and hooks are still in development. You can use the standard pushduck client APIs for now.
</Callout>

## Using pushduck with SvelteKit

SvelteKit is the official application framework for Svelte. It uses Web Standards APIs and provides excellent performance with minimal JavaScript. Since SvelteKit uses standard `Request`/`Response` objects, pushduck handlers work directly without any adapters!

<Callout type="info">
  **Web Standards Native**: SvelteKit server endpoints use Web Standard `Request`/`Response` objects, making pushduck integration straightforward with zero overhead.
</Callout>

## Quick Setup

<Steps>
  <Step>
    **Install dependencies**

```bash
    npm install pushduck
    ```
  </Step>

<Step>
    **Configure upload router**

```typescript title="src/lib/upload.ts"
    import { createUploadConfig } from 'pushduck/server';

export const uploadRouter = createS3Router({
      imageUpload: s3.image().maxFileSize("5MB"),
      documentUpload: s3.file().maxFileSize("10MB")
    });

export type AppUploadRouter = typeof uploadRouter;
    ```
  </Step>

<Step>
    **Create API route**

```typescript title="src/routes/api/upload/[...path]/+server.ts"
    import type { RequestHandler } from './$types';
    import { uploadRouter } from '$lib/upload';

// Direct usage - no adapter needed!
    export const GET: RequestHandler = async ({ request }) => {
      return uploadRouter.handlers(request);
    };

export const POST: RequestHandler = async ({ request }) => {
      return uploadRouter.handlers(request);
    };
    ```
  </Step>
</Steps>

## Basic Integration

### Simple Upload Route

```typescript title="src/routes/api/upload/[...path]/+server.ts"
import type { RequestHandler } from './$types';
import { uploadRouter } from '$lib/upload';

// Method 1: Combined handler (recommended)
export const GET: RequestHandler = async ({ request }) => {
  return uploadRouter.handlers(request);
};

export const POST: RequestHandler = async ({ request }) => {
  return uploadRouter.handlers(request);
};

// Method 2: Separate handlers (if you need method-specific logic)
// export const { GET, POST } = uploadRouter.handlers;
```

### With SvelteKit Hooks

```typescript title="src/hooks.server.ts"
import type { Handle } from '@sveltejs/kit';
import { sequence } from '@sveltejs/kit/hooks';

const corsHandler: Handle = async ({ event, resolve }) => {
  if (event.url.pathname.startsWith('/api/upload')) {
    if (event.request.method === 'OPTIONS') {
      return new Response(null, {
        status: 200,
        headers: {
          'Access-Control-Allow-Origin': '*',
          'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
          'Access-Control-Allow-Headers': 'Content-Type',
        },
      });
    }
  }
  
  const response = await resolve(event);
  
  if (event.url.pathname.startsWith('/api/upload')) {
    response.headers.set('Access-Control-Allow-Origin', '*');
  }
  
  return response;
};

export const handle = sequence(corsHandler);
```

## Advanced Configuration

### Authentication with SvelteKit

```typescript title="src/lib/upload.ts"
import { createUploadConfig } from 'pushduck/server';
import { getUserFromSession } from '$lib/auth';

const { s3, createS3Router } = createUploadConfig()
  .provider("cloudflareR2",{
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    region: 'auto',
    endpoint: process.env.AWS_ENDPOINT_URL!,
    bucket: process.env.S3_BUCKET_NAME!,
    accountId: process.env.R2_ACCOUNT_ID!,
  })
  .paths({
    prefix: 'uploads',
    generateKey: (file, metadata) => {
      return `${metadata.userId}/${Date.now()}/${file.name}`;
    }
  })
  .build();

export const uploadRouter = createS3Router({
  // Private uploads with session authentication
  privateUpload: s3
    .image()
    .maxFileSize("5MB")
    .middleware(async ({ req }) => {
      const cookies = req.headers.get('Cookie');
      const sessionId = parseCookie(cookies)?.sessionId;
      
      if (!sessionId) {
        throw new Error('Authentication required');
      }
      
      const user = await getUserFromSession(sessionId);
      if (!user) {
        throw new Error('Invalid session');
      }
      
      return {
        userId: user.id,
        username: user.username,
      };
    }),

// Public uploads (no auth)
  publicUpload: s3
    .image()
    .maxFileSize("2MB")
    // No middleware = public access
});

export type AppUploadRouter = typeof uploadRouter;
```

## Client-Side Usage

### Upload Component

```svelte title="src/lib/components/FileUpload.svelte"
<script lang="ts">
  import { useUpload } from "pushduck/client";
  import type { AppUploadRouter } from "$lib/upload";
  
  const { UploadButton, UploadDropzone } = useUpload<AppUploadRouter>({
    endpoint: "/api/upload",
  });
  
  function handleUploadComplete(files: any[]) {
    console.log("Files uploaded:", files);
    alert("Upload completed!");
  }
  
  function handleUploadError(error: Error) {
    console.error("Upload error:", error);
    alert(`Upload failed: ${error.message}`);
  }
</script>

<div class="space-y-6">
  <div>
    <h3 class="text-lg font-semibold mb-2">Image Upload</h3>
    <UploadButton
      endpoint="imageUpload"
      onClientUploadComplete={handleUploadComplete}
      onUploadError={handleUploadError}
    />
  </div>

<div>
    <h3 class="text-lg font-semibold mb-2">Document Upload</h3>
    <UploadDropzone
      endpoint="documentUpload"
      onClientUploadComplete={handleUploadComplete}
      onUploadError={handleUploadError}
    />
  </div>
</div>
```

### Using in Pages

```svelte title="src/routes/+page.svelte"
<script lang="ts">
  import FileUpload from "$lib/components/FileUpload.svelte";
</script>

<svelte:head>
  <title>File Upload Demo</title>
</svelte:head>

<main class="container mx-auto px-4 py-8">
  <h1 class="text-3xl font-bold mb-8">File Upload Demo</h1>
  <FileUpload />
</main>
```

## File Management

### Server-Side File Listing

```typescript title="src/routes/files/+page.server.ts"
import type { PageServerLoad } from './$types';
import { db } from '$lib/database';

export const load: PageServerLoad = async ({ locals }) => {
  const files = await db.file.findMany({
    where: { userId: locals.user?.id },
    orderBy: { createdAt: 'desc' },
  });
  
  return {
    files: files.map(file => ({
      id: file.id,
      name: file.name,
      url: file.url,
      size: file.size,
      uploadedAt: file.createdAt,
    })),
  };
};
```

```svelte title="src/routes/files/+page.svelte"
<script lang="ts">
  import type { PageData } from './$types';
  import FileUpload from '$lib/components/FileUpload.svelte';
  
  export let data: PageData;
  
  function formatFileSize(bytes: number): string {
    const sizes = ['Bytes', 'KB', 'MB', 'GB'];
    if (bytes === 0) return '0 Bytes';
    const i = Math.floor(Math.log(bytes) / Math.log(1024));
    return Math.round(bytes / Math.pow(1024, i) * 100) / 100 + ' ' + sizes[i];
  }
</script>

<svelte:head>
  <title>My Files</title>
</svelte:head>

<main class="container mx-auto px-4 py-8">
  <h1 class="text-3xl font-bold mb-8">My Files</h1>
  
  <div class="mb-8">
    <FileUpload />
  </div>
  
  <div>
    <h2 class="text-2xl font-semibold mb-4">Uploaded Files</h2>
    
    {#if data.files.length === 0}
      <p class="text-gray-500">No files uploaded yet.</p>
    {:else}
      <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
        {#each data.files as file}
          <div class="border rounded-lg p-4 hover:shadow-md transition-shadow">
            <h3 class="font-medium truncate" title={file.name}>
              {file.name}
            </h3>
            <p class="text-sm text-gray-500">
              {formatFileSize(file.size)}
            </p>
            <p class="text-sm text-gray-500">
              {new Date(file.uploadedAt).toLocaleDateString()}
            </p>
            <a
              href={file.url}
              target="_blank"
              rel="noopener noreferrer"
              class="text-blue-500 hover:underline text-sm mt-2 inline-block"
            >
              View File
            </a>
          </div>
        {/each}
      </div>
    {/if}
  </div>
</main>
```

## Deployment Options

<Tabs items={["Vercel", "Netlify", "Node.js", "Cloudflare Pages"]}>
  <Tab value="Vercel">
    ```javascript title="svelte.config.js"
    import adapter from '@sveltejs/adapter-vercel';
    import { vitePreprocess } from '@sveltejs/kit/vite';

/** @type {import('@sveltejs/kit').Config} */
    const config = {
      preprocess: vitePreprocess(),
      
      kit: {
        adapter: adapter({
          runtime: 'nodejs18.x',
          regions: ['iad1'],
        }),
      }
    };

export default config;
    ```
  </Tab>

<Tab value="Netlify">
    ```javascript title="svelte.config.js"
    import adapter from '@sveltejs/adapter-netlify';

/** @type {import('@sveltejs/kit').Config} */
    const config = {
      kit: {
        adapter: adapter({
          edge: false,
          split: false
        }),
      }
    };

export default config;
    ```
  </Tab>

<Tab value="Node.js">
    ```javascript title="svelte.config.js"
    import adapter from '@sveltejs/adapter-node';

/** @type {import('@sveltejs/kit').Config} */
    const config = {
      kit: {
        adapter: adapter({
          out: 'build'
        }),
      }
    };

export default config;
    ```
  </Tab>

<Tab value="Cloudflare Pages">
    ```javascript title="svelte.config.js"
    import adapter from '@sveltejs/adapter-cloudflare';

/** @type {import('@sveltejs/kit').Config} */
    const config = {
      kit: {
        adapter: adapter({
          routes: {
            include: ['/*'],
            exclude: ['<build>']
          }
        }),
      }
    };

export default config;
    ```
  </Tab>
</Tabs>

## Environment Variables

```bash title=".env"
# AWS Configuration
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_S3_BUCKET=your-bucket-name

# SvelteKit
PUBLIC_UPLOAD_ENDPOINT=http://localhost:5173/api/upload
```

## Performance Benefits

## Real-Time Upload Progress

```svelte title="src/lib/components/AdvancedUpload.svelte"
<script lang="ts">
  import { onMount } from 'svelte';
  import { writable } from 'svelte/store';
  
  const uploadProgress = writable(0);
  const isUploading = writable(false);
  
  let fileInput: HTMLInputElement;
  
  async function handleFileUpload(event: Event) {
    const target = event.target as HTMLInputElement;
    const files = target.files;
    
    if (!files || files.length === 0) return;
    
    isUploading.set(true);
    uploadProgress.set(0);
    
    try {
      // Simulate upload progress
      for (let i = 0; i <= 100; i += 10) {
        uploadProgress.set(i);
        await new Promise(resolve => setTimeout(resolve, 100));
      }
      
      alert('Upload completed!');
    } catch (error) {
      console.error('Upload failed:', error);
      alert('Upload failed!');
    } finally {
      isUploading.set(false);
      uploadProgress.set(0);
    }
  }
</script>

<div class="upload-container">
  <input
    bind:this={fileInput}
    type="file"
    multiple
    on:change={handleFileUpload}
    disabled={$isUploading}
    class="file-input"
  />
  
  {#if $isUploading}
    <div class="progress-container">
      <div class="progress-bar" style="width: {$uploadProgress}%"></div>
    </div>
    <p class="progress-text">{$uploadProgress}% uploaded</p>
  {/if}
</div>

## Troubleshooting

<Callout type="warn">
  **Common Issues**

1. **Route not found**: Ensure your route is `src/routes/api/upload/[...path]/+server.ts`
  2. **Build errors**: Check that pushduck is properly installed
  3. **CORS issues**: SvelteKit handles CORS automatically for same-origin requests
</Callout>

### Debug Mode

Enable debug logging:

SvelteKit provides an excellent foundation for building fast, modern web applications with pushduck, combining the power of Svelte's reactive framework with Web Standards APIs.

# TanStack Start (/docs/integrations/tanstack-start)

## Using pushduck with TanStack Start

TanStack Start is a full-stack React framework with built-in Web Standards support. Since TanStack Start provides `event.request` as a Web Standard `Request` object, pushduck handlers work directly without any adapters!

<Callout type="info">
  **Web Standards Native**: TanStack Start's API handlers receive `{ request }` as a Web Standard `Request` object, making pushduck integration straightforward with zero overhead.
</Callout>

## Quick Setup

<Steps>
  <Step>
    **Install dependencies**

<Tabs items={["npm", "yarn", "pnpm", "bun"]}>
      <Tab value="npm">
        ```bash
        npm install pushduck
        ```
      </Tab>

<Tab value="yarn">
        ```bash
        yarn add pushduck
        ```
      </Tab>

<Tab value="pnpm">
        ```bash
        pnpm add pushduck
        ```
      </Tab>

<Tab value="bun">
        ```bash
        bun add pushduck
        ```
      </Tab>
    </Tabs>
  </Step>

<Step>
    **Configure upload router**

```typescript title="app/lib/upload.ts"
    import { createUploadConfig } from 'pushduck/server';

export const uploadRouter = createS3Router({
      imageUpload: s3.image().maxFileSize("5MB"),
      documentUpload: s3.file().maxFileSize("10MB")
    });

export type AppUploadRouter = typeof uploadRouter;
    ```
  </Step>

<Step>
    **Create API route**

```typescript title="app/routes/api.upload.$.ts"
    import { createAPIFileRoute } from '@tanstack/start/api';
    import { uploadRouter } from '../lib/upload';

export const Route = createAPIFileRoute('/api/upload/$')({
      GET: ({ request }) => uploadRouter.handlers(request),
      POST: ({ request }) => uploadRouter.handlers(request),
    });
    ```
  </Step>
</Steps>

## Basic Integration

### API Route Handler

```typescript title="app/routes/api.upload.$.ts"
import { createAPIFileRoute } from '@tanstack/start/api';
import { uploadRouter } from '../lib/upload';

export const Route = createAPIFileRoute('/api/upload/$')({
  // Method 1: Individual handlers
  GET: ({ request }) => uploadRouter.handlers.GET(request),
  POST: ({ request }) => uploadRouter.handlers.POST(request),
  
  // Method 2: Universal handler (alternative approach)
  // You could also create a single handler that delegates:
  // handler: ({ request }) => uploadRouter.handlers(request)
});
```

### With Middleware

```typescript title="app/routes/api.upload.$.ts"
import { createAPIFileRoute } from '@tanstack/start/api';
import { uploadRouter } from '../lib/upload';

// Simple CORS middleware
function withCORS(handler: (ctx: any) => Promise<Response>) {
  return async (ctx: any) => {
    const response = await handler(ctx);
    
    response.headers.set('Access-Control-Allow-Origin', '*');
    response.headers.set('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
    response.headers.set('Access-Control-Allow-Headers', 'Content-Type, Authorization');
    
    return response;
  };
}

export const Route = createAPIFileRoute('/api/upload/$')({
  GET: withCORS(({ request }) => uploadRouter.handlers.GET(request)),
  POST: withCORS(({ request }) => uploadRouter.handlers.POST(request)),
  OPTIONS: () => new Response(null, { 
    status: 200,
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    }
  }),
});
```

## Advanced Configuration

### Authentication with TanStack Start

```typescript title="app/lib/upload.ts"
import { createUploadConfig } from 'pushduck/server';

const { s3, createS3Router } = createUploadConfig()
  .provider("cloudflareR2",{
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    region: 'auto',
    endpoint: process.env.AWS_ENDPOINT_URL!,
    bucket: process.env.S3_BUCKET_NAME!,
    accountId: process.env.R2_ACCOUNT_ID!,
  })
  .paths({
    prefix: 'uploads',
    generateKey: (file, metadata) => {
      return `${metadata.userId}/${Date.now()}/${file.name}`;
    }
  })
  .build();

// Public uploads (no auth)
  publicUpload: s3
    .image()
    .maxFileSize("2MB")
    // No middleware = public access
});

async function verifyJWT(token: string) {
  // Your JWT verification logic here
  return { id: 'user-123', role: 'user' };
}

export type AppUploadRouter = typeof uploadRouter;
```

### Protected API Routes

```typescript title="app/routes/api.upload.$.ts"
import { createAPIFileRoute } from '@tanstack/start/api';
import { uploadRouter } from '../lib/upload';

// Authentication middleware
async function requireAuth(request: Request) {
  const authHeader = request.headers.get('authorization');
  if (!authHeader?.startsWith('Bearer ')) {
    throw new Response(JSON.stringify({ error: 'Authorization required' }), {
      status: 401,
      headers: { 'Content-Type': 'application/json' }
    });
  }
  
  const token = authHeader.substring(7);
  // Verify token logic here
  return { userId: 'user-123' };
}

export const Route = createAPIFileRoute('/api/upload/$')({
  GET: async ({ request }) => {
    await requireAuth(request);
    return uploadRouter.handlers.GET(request);
  },
  POST: async ({ request }) => {
    await requireAuth(request);
    return uploadRouter.handlers.POST(request);
  },
});
```

## Client-Side Integration

### Upload Component

```typescript title="app/components/UploadDemo.tsx"
import { useState } from 'react';
import { createUploadClient } from 'pushduck/client';
import type { AppUploadRouter } from '../lib/upload';

const uploadClient = createUploadClient<AppUploadRouter>({
  baseUrl: process.env.NODE_ENV === 'development' 
    ? 'http://localhost:3000' 
    : 'https://your-domain.com'
});

export function UploadDemo() {
  const [uploading, setUploading] = useState(false);
  const [results, setResults] = useState<any[]>([]);

return (
    <div className="space-y-4">
      <div>
        <input
          type="file"
          multiple
          accept="image/*"
          onChange={(e) => {
            if (e.target.files) {
              handleUpload(Array.from(e.target.files));
            }
          }}
          disabled={uploading}
          className="block w-full text-sm text-gray-500 file:mr-4 file:py-2 file:px-4 file:rounded-full file:border-0 file:text-sm file:font-semibold file:bg-blue-50 file:text-blue-700 hover:file:bg-blue-100"
        />
      </div>
      
      {uploading && (
        <div className="text-blue-600">Uploading...</div>
      )}
      
      {results.length > 0 && (
        <div className="space-y-2">
          <h3 className="font-medium">Upload Results:</h3>
          {results.map((result, index) => (
            <div key={index} className="p-2 bg-gray-50 rounded">
              <div className="text-sm">
                <strong>File:</strong> {result.name}
              </div>
              <div className="text-sm">
                <strong>Public URL:</strong> 
                <a href={result.url} target="_blank" rel="noopener noreferrer" className="text-blue-600 hover:underline ml-1">
                  {result.url}
                </a>
              </div>
              {result.presignedUrl && (
                <div className="text-sm">
                  <strong>Download URL:</strong> 
                  <a href={result.presignedUrl} target="_blank" rel="noopener noreferrer" className="text-green-600 hover:underline ml-1">
                    {result.presignedUrl}
                  </a>
                  <span className="text-xs text-gray-500 ml-2">(expires in 1 hour)</span>
                </div>
              )}
            </div>
          ))}
        </div>
      )}
    </div>
  );
}
```

### Page Integration

```typescript title="app/routes/upload.tsx"
import { createFileRoute } from '@tanstack/start';
import { UploadDemo } from '../components/UploadDemo';

export const Route = createFileRoute('/upload')({
  component: UploadPage,
});

function UploadPage() {
  return (
    <div className="container mx-auto px-4 py-8">
      <h1 className="text-3xl font-bold mb-8">File Upload Demo</h1>
      <div className="max-w-md mx-auto">
        <UploadDemo />
      </div>
    </div>
  );
}
```

## Full Application Example

### Project Structure

```
app/
├── components/
│   └── UploadDemo.tsx
├── lib/
│   └── upload.ts
├── routes/
│   ├── api.upload.$.ts
│   ├── upload.tsx
│   └── __root.tsx
├── router.ts
└── main.tsx
```

### Root Layout

```typescript title="app/routes/__root.tsx"
import { createRootRoute, Outlet } from '@tanstack/start';

export const Route = createRootRoute({
  component: RootComponent,
});

function RootComponent() {
  return (
    <html>
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>TanStack Start + Pushduck</title>
      </head>
      <body>
        <div className="min-h-screen bg-gray-50">
          <nav className="bg-white shadow">
            <div className="container mx-auto px-4 py-4">
              <h1 className="text-xl font-semibold">Upload Demo</h1>
            </div>
          </nav>
          <main>
            <Outlet />
          </main>
        </div>
      </body>
    </html>
  );
}
```

## Performance Benefits

<Cards>
  <Card title="Zero Overhead" description="Direct Web Standards integration">
    No adapter layer means zero performance overhead - pushduck handlers run directly in TanStack Start.
  </Card>

<Card title="React Server Components" description="Modern React architecture">
    Built on the latest React features with streaming and concurrent rendering.
  </Card>

<Card title="Full-Stack TypeScript" description="End-to-end type safety">
    Complete type safety from server to client with shared types.
  </Card>

<Card title="File-Based Routing" description="Intuitive API structure">
    Organized API routes with TanStack Start's file-based routing system.
  </Card>
</Cards>

## Deployment

### Vercel Deployment

```typescript title="app.config.ts"
import { defineConfig } from '@tanstack/start/config';

export default defineConfig({
  server: {
    preset: 'vercel'
  }
});
```

### Netlify Deployment

```typescript title="app.config.ts"
import { defineConfig } from '@tanstack/start/config';

export default defineConfig({
  server: {
    preset: 'netlify'
  }
});
```

### Docker Deployment

```dockerfile title="Dockerfile"
FROM node:18-alpine as base
WORKDIR /app

# Install dependencies
COPY package*.json ./
RUN npm ci --only=production

# Copy source code
COPY . .

# Build the app
RUN npm run build

# Expose port
EXPOSE 3000

# Start the app
CMD ["npm", "start"]
```

***

<Callout type="success">
  **Modern React + Pushduck**: TanStack Start's modern React architecture combined with pushduck's universal design creates a type-safe file upload solution.
</Callout>

# tRPC (/docs/integrations/trpc)

## Using pushduck with tRPC

tRPC enables end-to-end typesafe APIs with excellent TypeScript integration. With pushduck, you use **tRPC for storage operations** (listing, deleting, metadata) while **file uploads happen through your framework's routes** using pushduck handlers. This gives you the best of both worlds: framework-native uploads with type-safe storage management.

<Callout type="info">
  **Separation of Concerns**: File uploads use your framework's native upload routes with pushduck handlers, while tRPC procedures handle all storage-related CRUD operations using pushduck's storage API for full type safety.
</Callout>

## Architecture Overview

<Mermaid
  diagram={`
graph TD
  A[Client Upload Component] --> B[Framework Upload Route]
  A --> C[tRPC Storage Procedures]
  
  B --> D[pushduck Upload Handler]
  C --> E[pushduck Storage API]
  
  D --> F[S3/R2 Storage]
  E --> F
  
  B --> G[File Upload Success]
  G --> C
`}
/>

## Quick Setup

<Steps>
  <Step>
    **Install dependencies**

<Tabs items={["npm", "yarn", "pnpm", "bun"]}>
      <Tab value="npm">
        ```bash
        npm install @trpc/server @trpc/client pushduck
        # Framework-specific tRPC packages:
        # @trpc/next (for Next.js)
        # @trpc/react-query (for React)
        ```
      </Tab>

<Tab value="yarn">
        ```bash
        yarn add @trpc/server @trpc/client pushduck
        # Framework-specific tRPC packages:
        # @trpc/next (for Next.js)
        # @trpc/react-query (for React)
        ```
      </Tab>

<Tab value="pnpm">
        ```bash
        pnpm add @trpc/server @trpc/client pushduck
        # Framework-specific tRPC packages:
        # @trpc/next (for Next.js)
        # @trpc/react-query (for React)
        ```
      </Tab>

<Tab value="bun">
        ```bash
        bun add @trpc/server @trpc/client pushduck
        # Framework-specific tRPC packages:
        # @trpc/next (for Next.js)
        # @trpc/react-query (for React)
        ```
      </Tab>
    </Tabs>
  </Step>

<Step>
    **Configure storage and upload router**

```typescript title="lib/storage.ts"
    import { createUploadConfig } from 'pushduck/server';

// Configure storage
    export const { s3, storage, createS3Router } = createUploadConfig()
      .provider("cloudflareR2",{
        accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
        region: 'auto',
        endpoint: process.env.AWS_ENDPOINT_URL!,
        bucket: process.env.S3_BUCKET_NAME!,
        accountId: process.env.R2_ACCOUNT_ID!,
      })
      .build();

// Upload router for framework routes
    export const uploadRouter = createS3Router({
      imageUpload: s3.image().maxFileSize("5MB"),
      documentUpload: s3.file().maxFileSize("10MB")
    });

export type AppUploadRouter = typeof uploadRouter;
    ```
  </Step>

<Step>
    **Create tRPC router with storage operations**

```typescript title="server/trpc.ts"
    import { initTRPC, TRPCError } from '@trpc/server';
    import { z } from 'zod';
    import { storage } from '~/lib/storage';

const t = initTRPC.create();

export const appRouter = t.router({
      files: t.router({
        // List files with pagination
        list: t.procedure
          .input(z.object({ 
            prefix: z.string().optional(),
            limit: z.number().min(1).max(100).default(20),
            cursor: z.string().optional()
          }))
          .query(async ({ input }) => {
            const result = await storage.list.paginated({
              prefix: input.prefix,
              maxKeys: input.limit,
              continuationToken: input.cursor,
            });
            
            return {
              files: result.files,
              nextCursor: result.nextContinuationToken,
              hasMore: result.isTruncated,
            };
          }),

// Get file metadata
        getInfo: t.procedure
          .input(z.object({ key: z.string() }))
          .query(async ({ input }) => {
            const info = await storage.metadata.getInfo(input.key);
            if (!info.exists) {
              throw new TRPCError({ 
                code: 'NOT_FOUND', 
                message: 'File not found' 
              });
            }
            return info;
          }),

// Get multiple files info
        getBatch: t.procedure
          .input(z.object({ keys: z.array(z.string()) }))
          .query(async ({ input }) => {
            return await storage.metadata.getBatch(input.keys);
          }),

// Delete file
        delete: t.procedure
          .input(z.object({ key: z.string() }))
          .mutation(async ({ input }) => {
            const result = await storage.delete.file(input.key);
            return { success: result.success };
          }),

// Delete multiple files
        deleteBatch: t.procedure
          .input(z.object({ keys: z.array(z.string()) }))
          .mutation(async ({ input }) => {
            const result = await storage.delete.files(input.keys);
            return { 
              success: result.success,
              deleted: result.deleted,
              errors: result.errors,
            };
          }),

// Generate download URL
        getDownloadUrl: t.procedure
          .input(z.object({ 
            key: z.string(),
            expiresIn: z.number().optional()
          }))
          .query(async ({ input }) => {
            const result = await storage.download.presignedUrl(
              input.key, 
              input.expiresIn
            );
            return { url: result.url, expiresAt: result.expiresAt };
          }),

// Search files by extension
        searchByExtension: t.procedure
          .input(z.object({ 
            extension: z.string(),
            prefix: z.string().optional()
          }))
          .query(async ({ input }) => {
            return await storage.list.byExtension(
              input.extension, 
              input.prefix
            );
          }),

// Search files by size range
        searchBySize: t.procedure
          .input(z.object({
            minSize: z.number().optional(),
            maxSize: z.number().optional(),
            prefix: z.string().optional()
          }))
          .query(async ({ input }) => {
            return await storage.list.bySize(
              input.minSize,
              input.maxSize,
              input.prefix
            );
          }),

// Get storage statistics
        getStats: t.procedure
          .input(z.object({ prefix: z.string().optional() }))
          .query(async ({ input }) => {
            const files = await storage.list.files({ prefix: input.prefix });
            
            const stats = files.files.reduce((acc, file) => {
              acc.totalSize += file.size;
              acc.count += 1;
              
              const ext = file.key.split('.').pop()?.toLowerCase() || 'unknown';
              acc.byExtension[ext] = (acc.byExtension[ext] || 0) + 1;
              
              return acc;
            }, {
              totalSize: 0,
              count: 0,
              byExtension: {} as Record<string, number>
            });
            
            return stats;
          }),
      }),
    });

export type AppRouter = typeof appRouter;
    ```
  </Step>

<Step>
    **Create framework upload route**

<Tabs items={["Next.js", "Remix", "SvelteKit"]}>
      <Tab value="Next.js">
        ```typescript title="app/api/upload/[...path]/route.ts"
        import { uploadRouter } from '~/lib/storage';

// Handle file uploads through framework route
        export const { GET, POST } = uploadRouter.handlers;
        ```
      </Tab>

<Tab value="Remix">
        ```typescript title="app/routes/api.upload.$.tsx"
        import type { ActionFunctionArgs, LoaderFunctionArgs } from "@remix-run/node";
        import { uploadRouter } from "~/lib/storage";

export async function loader({ request }: LoaderFunctionArgs) {
          return uploadRouter.handlers(request);
        }

export async function action({ request }: ActionFunctionArgs) {
          return uploadRouter.handlers(request);
        }
        ```
      </Tab>

<Tab value="SvelteKit">
        ```typescript title="src/routes/api/upload/[...path]/+server.ts"
        import type { RequestHandler } from './$types';
        import { uploadRouter } from '$lib/storage';

export const GET: RequestHandler = async ({ request }) => {
          return uploadRouter.handlers(request);
        };

export const POST: RequestHandler = async ({ request }) => {
          return uploadRouter.handlers(request);
        };
        ```
      </Tab>
    </Tabs>
  </Step>

<Step>
    **Create tRPC API route**

<Tabs items={["Next.js", "Express", "Standalone"]}>
      <Tab value="Next.js">
        ```typescript title="app/api/trpc/[trpc]/route.ts"
        import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
        import { appRouter } from '~/server/trpc';

const handler = (req: Request) =>
          fetchRequestHandler({
            endpoint: '/api/trpc',
            req,
            router: appRouter,
            createContext: () => ({}),
          });

export { handler as GET, handler as POST };
        ```
      </Tab>

<Tab value="Express">
        ```typescript title="server/index.ts"
        import express from 'express';
        import * as trpcExpress from '@trpc/server/adapters';
        import { appRouter } from './trpc';
        import { uploadRouter } from './storage';
        import { toExpressHandler } from 'pushduck/adapters';

const app = express();

// tRPC for storage operations
        app.use('/api/trpc', trpcExpress.createExpressMiddleware({
          router: appRouter,
          createContext: () => ({}),
        }));

// pushduck for file uploads
        app.all('/api/upload/*', toExpressHandler(uploadRouter.handlers));

app.listen(3000);
        ```
      </Tab>

<Tab value="Standalone">
        ```typescript title="server/index.ts"
        import { createHTTPServer } from '@trpc/server/adapters/standalone';
        import { appRouter } from './trpc';

// tRPC server for storage operations
        const server = createHTTPServer({
          router: appRouter,
          createContext: () => ({}),
        });

server.listen(3001); // Different port for tRPC
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Client-Side Integration

### React with tRPC and pushduck

```tsx title="components/FileManager.tsx"
import { trpc } from '~/lib/trpc';
import { useUpload } from 'pushduck/client';
import type { AppUploadRouter } from '~/lib/storage';

// Upload hooks are from pushduck (framework-native)
const { UploadButton, UploadDropzone } = useUpload<AppUploadRouter>({
  endpoint: "/api/upload",
});

export function FileManager() {
  // Storage operations are from tRPC (type-safe)
  const { 
    data: files, 
    refetch,
    fetchNextPage,
    hasNextPage 
  } = trpc.files.list.useInfiniteQuery(
    { limit: 20 },
    {
      getNextPageParam: (lastPage) => lastPage.nextCursor,
    }
  );
  
  const deleteFile = trpc.files.delete.useMutation({
    onSuccess: () => refetch(),
  });
  
  const getDownloadUrl = trpc.files.getDownloadUrl.useMutation();
  const fileStats = trpc.files.getStats.useQuery({});

const handleUploadComplete = async (uploadedFiles: any[]) => {
    // Files are uploaded, refresh the list
    await refetch();
    console.log('Upload completed:', uploadedFiles);
  };

const handleDelete = async (key: string) => {
    if (confirm('Are you sure you want to delete this file?')) {
      await deleteFile.mutateAsync({ key });
    }
  };

const handleDownload = async (key: string) => {
    const result = await getDownloadUrl.mutateAsync({ key });
    window.open(result.url, '_blank');
  };

return (
    <div className="space-y-6">
      {/* Upload Section - Uses pushduck hooks */}
      <div>
        <h2 className="text-2xl font-bold mb-4">Upload Files</h2>
        
        <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
          <div>
            <h3 className="text-lg font-semibold mb-2">Images</h3>
            <UploadButton
              endpoint="imageUpload"
              onClientUploadComplete={handleUploadComplete}
              onUploadError={(error) => alert(`Upload failed: ${error.message}`)}
            />
          </div>
          
          <div>
            <h3 className="text-lg font-semibold mb-2">Documents</h3>
            <UploadDropzone
              endpoint="documentUpload"
              onClientUploadComplete={handleUploadComplete}
              onUploadError={(error) => alert(`Upload failed: ${error.message}`)}
            />
          </div>
        </div>
      </div>

{/* Stats Section - Uses tRPC */}
      <div className="bg-gray-50 p-4 rounded-lg">
        <h3 className="text-lg font-semibold mb-2">Storage Statistics</h3>
        {fileStats.data && (
          <div className="grid grid-cols-3 gap-4 text-sm">
            <div>
              <span className="font-medium">Total Files:</span> {fileStats.data.count}
            </div>
            <div>
              <span className="font-medium">Total Size:</span> {formatFileSize(fileStats.data.totalSize)}
            </div>
            <div>
              <span className="font-medium">Extensions:</span> {Object.keys(fileStats.data.byExtension).join(', ')}
            </div>
          </div>
        )}
      </div>

{/* File List Section - Uses tRPC */}
      <div>
        <h2 className="text-2xl font-bold mb-4">Your Files</h2>
        
        {files?.pages[0]?.files.length === 0 ? (
          <p className="text-gray-500">No files uploaded yet.</p>
        ) : (
          <div className="space-y-4">
            <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
              {files?.pages.flatMap(page => page.files).map((file) => (
                <div key={file.key} className="border rounded-lg p-4">
                  <h3 className="font-medium truncate" title={file.key}>
                    {file.key.split('/').pop()}
                  </h3>
                  <p className="text-sm text-gray-500">
                    {formatFileSize(file.size)}
                  </p>
                  <p className="text-sm text-gray-500">
                    {new Date(file.lastModified).toLocaleDateString()}
                  </p>
                  <div className="flex gap-2 mt-2">
                    <button
                      onClick={() => handleDownload(file.key)}
                      className="text-blue-500 hover:underline text-sm"
                      disabled={getDownloadUrl.isLoading}
                    >
                      Download
                    </button>
                    <button
                      onClick={() => handleDelete(file.key)}
                      className="text-red-500 hover:underline text-sm"
                      disabled={deleteFile.isLoading}
                    >
                      Delete
                    </button>
                  </div>
                </div>
              ))}
            </div>
            
            {hasNextPage && (
              <button
                onClick={() => fetchNextPage()}
                className="w-full bg-blue-500 text-white p-2 rounded hover:bg-blue-600"
              >
                Load More Files
              </button>
            )}
          </div>
        )}
      </div>
    </div>
  );
}

function formatFileSize(bytes: number): string {
  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
  if (bytes === 0) return '0 Bytes';
  const i = Math.floor(Math.log(bytes) / Math.log(1024));
  return Math.round(bytes / Math.pow(1024, i) * 100) / 100 + ' ' + sizes[i];
}
```

### Advanced File Search

```tsx title="components/FileSearch.tsx"
import { useState } from 'react';
import { trpc } from '~/lib/trpc';

export function FileSearch() {
  const [searchType, setSearchType] = useState<'extension' | 'size'>('extension');
  const [extension, setExtension] = useState('');
  const [minSize, setMinSize] = useState<number>();
  const [maxSize, setMaxSize] = useState<number>();

// Type-safe search operations via tRPC
  const searchByExtension = trpc.files.searchByExtension.useQuery(
    { extension },
    { enabled: searchType === 'extension' && !!extension }
  );

const searchBySize = trpc.files.searchBySize.useQuery(
    { minSize, maxSize },
    { enabled: searchType === 'size' && (!!minSize || !!maxSize) }
  );

const results = searchType === 'extension' ? searchByExtension.data : searchBySize.data;

return (
    <div className="space-y-4">
      <div className="flex gap-4">
        <select 
          value={searchType} 
          onChange={(e) => setSearchType(e.target.value as any)}
          className="border rounded px-3 py-2"
        >
          <option value="extension">By Extension</option>
          <option value="size">By Size</option>
        </select>

{searchType === 'extension' ? (
          <input
            type="text"
            placeholder="e.g., jpg, pdf, mp4"
            value={extension}
            onChange={(e) => setExtension(e.target.value)}
            className="border rounded px-3 py-2 flex-1"
          />
        ) : (
          <div className="flex gap-2 flex-1">
            <input
              type="number"
              placeholder="Min size (bytes)"
              value={minSize || ''}
              onChange={(e) => setMinSize(Number(e.target.value) || undefined)}
              className="border rounded px-3 py-2 flex-1"
            />
            <input
              type="number"
              placeholder="Max size (bytes)"
              value={maxSize || ''}
              onChange={(e) => setMaxSize(Number(e.target.value) || undefined)}
              className="border rounded px-3 py-2 flex-1"
            />
          </div>
        )}
      </div>

{results && (
        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
          {results.files.map((file) => (
            <div key={file.key} className="border rounded-lg p-4">
              <h3 className="font-medium truncate">{file.key}</h3>
              <p className="text-sm text-gray-500">{formatFileSize(file.size)}</p>
            </div>
          ))}
        </div>
      )}
    </div>
  );
}
```

## Authentication Integration

```typescript title="server/trpc.ts"
import { initTRPC, TRPCError } from '@trpc/server';
import { storage } from '~/lib/storage';

// Create context with user authentication
export const createContext = async ({ req }: { req: Request }) => {
  const authHeader = req.headers.get('authorization');
  
  if (!authHeader?.startsWith('Bearer ')) {
    return { user: null };
  }
  
  try {
    const token = authHeader.substring(7);
    const user = await validateToken(token); // Your auth logic
    return { user };
  } catch {
    return { user: null };
  }
};

type Context = Awaited<ReturnType<typeof createContext>>;
const t = initTRPC.context<Context>().create();

// Auth middleware
const isAuthenticated = t.middleware(({ next, ctx }) => {
  if (!ctx.user) {
    throw new TRPCError({ code: 'UNAUTHORIZED' });
  }
  return next({ ctx: { ...ctx, user: ctx.user } });
});

const protectedProcedure = t.procedure.use(isAuthenticated);

export const appRouter = t.router({
  files: t.router({
    // User's files only
    list: protectedProcedure
      .input(z.object({ prefix: z.string().optional() }))
      .query(async ({ input, ctx }) => {
        // Scope to user's folder
        const userPrefix = `users/${ctx.user.id}/${input.prefix || ''}`;
        return await storage.list.files({ prefix: userPrefix });
      }),

// User can only delete their own files
    delete: protectedProcedure
      .input(z.object({ key: z.string() }))
      .mutation(async ({ input, ctx }) => {
        // Ensure user owns the file
        if (!input.key.startsWith(`users/${ctx.user.id}/`)) {
          throw new TRPCError({ code: 'FORBIDDEN' });
        }
        
        return await storage.delete.file(input.key);
      }),
  }),
});
```

## Real-time Updates with Subscriptions

```typescript title="server/trpc.ts"
import { observable } from '@trpc/server/observable';
import { EventEmitter } from 'events';

const fileEventEmitter = new EventEmitter();

export const appRouter = t.router({
  files: t.router({
    // ... other procedures

// Real-time file updates
    onUpdate: protectedProcedure
      .subscription(({ ctx }) => {
        return observable<{ type: 'uploaded' | 'deleted'; file: any }>((emit) => {
          const onFileEvent = (data: any) => {
            // Only emit events for this user's files
            if (data.userId === ctx.user.id) {
              emit.next(data);
            }
          };
          
          fileEventEmitter.on('file:event', onFileEvent);
          
          return () => {
            fileEventEmitter.off('file:event', onFileEvent);
          };
        });
      }),
  }),
});

// Emit events from upload completion
export const emitFileEvent = (type: 'uploaded' | 'deleted', file: any, userId: string) => {
  fileEventEmitter.emit('file:event', { type, file, userId });
};
```

## Performance Benefits

## Key Advantages

### **Clear Separation**

* **Uploads**: Framework-native routes with pushduck handlers
* **Storage Operations**: Type-safe tRPC procedures with pushduck storage API
* **Client**: Framework upload hooks + tRPC queries/mutations

### **Best of Both Worlds**

* **Framework-optimized uploads** (progress, validation, middleware)
* **Type-safe storage management** (list, delete, search, metadata)
* **Unified developer experience** with consistent patterns

### **Scalable Architecture**

* **Independent scaling** of upload and API operations
* **Flexible deployment** (separate services if needed)
* **Framework agnostic** storage operations

## Troubleshooting

<Callout type="warn">
  **Common Issues**

1. **Mixed responsibilities**: Don't try to handle uploads in tRPC procedures - use framework routes
  2. **Type mismatches**: Ensure storage operations use the same config as upload routes
  3. **Authentication**: Sync auth between upload middleware and tRPC context
  4. **CORS**: Configure CORS for both `/api/trpc` and `/api/upload` endpoints
</Callout>

### Debug Mode

```typescript title="lib/debug.ts"
// Enable debug logging for both systems
export const debugConfig = {
  trpc: process.env.NODE_ENV === 'development',
  storage: process.env.NODE_ENV === 'development',
};

// Storage debug logging
export const storage = createStorage(config).middleware?.(async (operation, params) => {
  if (debugConfig.storage) {
    console.log("Storage operation:", operation, params);
  }
});

// Upload debug logging  
export const uploadRouter = createS3Router({
  // ... routes
}).middleware(async ({ req, file }) => {
  if (debugConfig.storage) {
    console.log("Upload request:", req.url);
    console.log("File:", file.name, file.size);
  }
  return {};
});
```

This architecture gives you **framework-native file uploads** with **type-safe storage management**, combining the strengths of both pushduck and tRPC for a superior developer experience.

# AWS S3 (/docs/providers/aws-s3)

import { Step, Steps } from "fumadocs-ui/components/steps";
import { Callout } from "fumadocs-ui/components/callout";
import { Tab, Tabs } from "fumadocs-ui/components/tabs";

## AWS S3 Setup

Get **AWS S3** configured for production file uploads in under 5 minutes. This guide covers everything from bucket creation to security best practices.

<Callout type="info">
  **Why AWS S3?** The most trusted object storage service with 99.999999999%
  durability, global CDN integration, and predictable pricing. Perfect for
  applications that need reliable, scalable file storage.
</Callout>

## What You'll Accomplish

By the end of this guide, you'll have:

* ✅ A secure S3 bucket configured for web uploads
* ✅ IAM user with minimal required permissions
* ✅ CORS configuration for your domain
* ✅ Environment variables ready for production
* ✅ Cost optimization settings enabled

<Steps>
  <Step>
    ## Create AWS Account & S3 Bucket

If you don't have an AWS account, [sign up for free](https://aws.amazon.com/free/) - you get 5GB of S3 storage free for 12 months.

1. **Open S3 Console**: Go to [S3 Console](https://console.aws.amazon.com/s3/)
    2. **Create Bucket**: Click "Create bucket"
    3. **Configure Basic Settings**:

```bash
    Bucket name: your-app-uploads-prod
    Region: us-east-1 (or closest to your users)
    ```

<Callout type="warn">
      **Bucket Naming**: Use a unique, descriptive name. Bucket names are global
      across all AWS accounts and cannot be changed later.
    </Callout>

4. **Block Public Access**: Keep all "Block public access" settings **enabled** (this is secure - we'll use presigned URLs)
    5. **Enable Versioning**: Recommended for data protection
    6. **Create Bucket**: Click "Create bucket"
  </Step>

<Step>
    ## Configure CORS for Web Access

<Callout type="info">
      **Comprehensive CORS Guide**: For detailed CORS configuration, testing, and troubleshooting, see the [CORS & ACL Configuration Guide](/docs/guides/security/cors-and-acl).
    </Callout>

Your web application needs permission to upload files directly to S3.

1. **Open Your Bucket**: Click on your newly created bucket
    2. **Go to Permissions Tab**: Click "Permissions"
    3. **Edit CORS Configuration**: Scroll to "Cross-origin resource sharing (CORS)" and click "Edit"
    4. **Add CORS Rules**:

<Tabs items={['Development', 'Production']}>
      <Tab value="Development">
        ```json
        [
          {
            "AllowedHeaders": ["*"],
            "AllowedMethods": ["GET", "PUT", "POST", "DELETE"],
            "AllowedOrigins": [
              "http://localhost:3000",
              "http://localhost:3001",
              "https://localhost:3000"
            ],
            "ExposeHeaders": ["ETag"],
            "MaxAgeSeconds": 3000
          }
        ]
        ```
      </Tab>

<Tab value="Production">
        ```json
        [
          {
            "AllowedHeaders": ["*"],
            "AllowedMethods": ["GET", "PUT", "POST", "DELETE"],
            "AllowedOrigins": [
              "https://yourdomain.com",
              "https://www.yourdomain.com",
              "https://staging.yourdomain.com"
            ],
            "ExposeHeaders": ["ETag"],
            "MaxAgeSeconds": 86400
          }
        ]
        ```
      </Tab>
    </Tabs>

5. **Save Changes**: Click "Save changes"

<Callout type="info">
      **Security Note**: Only add origins you trust. Wildcards (`*`) should never be
      used in production - they allow any website to upload to your bucket.
    </Callout>
  </Step>

<Step>
    ## Create IAM User with Minimal Permissions

Create a dedicated user for your application with only the permissions it needs.

1. **Open IAM Console**: Go to [IAM Console](https://console.aws.amazon.com/iam/)
    2. **Create User**:
       * Click "Users" → "Create user"
       * Username: `your-app-s3-user`
       * Select "Programmatic access" only
    3. **Create Custom Policy**:
       * Click "Attach policies directly"
       * Click "Create policy"
       * Use JSON editor and paste:

```json
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"],
          "Resource": "arn:aws:s3:::your-app-uploads-prod/*"
        },
        {
          "Effect": "Allow",
          "Action": ["s3:ListBucket"],
          "Resource": "arn:aws:s3:::your-app-uploads-prod"
        }
      ]
    }
    ```

4. **Name the Policy**: `YourApp-S3-Upload-Policy`
    5. **Attach to User**: Go back to user creation and attach your new policy
    6. **Create User**: Complete the user creation

<Callout type="warn">
      **Replace Bucket Name**: Make sure to replace `your-app-uploads-prod` with
      your actual bucket name in the policy JSON.
    </Callout>
  </Step>

<Step>
    ## Get Access Keys

Your application needs these credentials to generate presigned URLs.

1. **Select Your User**: In IAM Users, click on your newly created user
    2. **Security Credentials Tab**: Click "Security credentials"
    3. **Create Access Key**:
       * Click "Create access key"
       * Select "Application running outside AWS"
       * Click "Next"
    4. **Copy Credentials**:
       * **Access Key ID**: Copy this value
       * **Secret Access Key**: Copy this value (you'll only see it once!)

<Callout type="error">
      **Security Alert**: Never commit these keys to version control or share them
      publicly. Use environment variables or secure key management services.
    </Callout>
  </Step>

<Step>
    ## Configure Environment Variables

Add your AWS credentials to your application.

<Tabs items={['Development', 'Production']}>
      <Tab value="Development">
        ```bash
        # .env.local
        AWS_ACCESS_KEY_ID=your_access_key_id
        AWS_SECRET_ACCESS_KEY=your_secret_access_key
        AWS_REGION=us-east-1
        AWS_S3_BUCKET_NAME=your-app-uploads-prod

# Optional: Custom domain for public files (CDN, CloudFront, etc.)
        S3_CUSTOM_DOMAIN=https://cdn.yourdomain.com

# Optional: Enable S3 debug logging
        DEBUG=aws-sdk:\*

```
      </Tab>

<Tab value="Production">
        ```bash
        # Use your hosting platform's environment variable system
        # Never store production keys in .env files

# Vercel:
        # vercel env add AWS_ACCESS_KEY_ID
        # vercel env add AWS_SECRET_ACCESS_KEY

# Netlify:
        # Add in Site settings > Environment variables

# Railway:
        # Add in Variables tab

AWS_ACCESS_KEY_ID=your_access_key_id
        AWS_SECRET_ACCESS_KEY=your_secret_access_key
        AWS_REGION=us-east-1
        AWS_S3_BUCKET_NAME=your-app-uploads-prod

# Optional: Custom domain for public files (CDN, CloudFront, etc.)
        S3_CUSTOM_DOMAIN=https://cdn.yourdomain.com
        ```
      </Tab>
    </Tabs>
  </Step>

<Step>
    ## Configure Custom Domain (Optional)

For better performance and branding, you can use a custom domain for your files.

### Option 1: CloudFront CDN (Recommended)

1. **Create CloudFront Distribution**:
       * Go to [CloudFront Console](https://console.aws.amazon.com/cloudfront/)
       * Click "Create Distribution"
       * Origin Domain: Select your S3 bucket
       * Origin Access: Use "Origin access control settings"
       * Default Cache Behavior: Allow all HTTP methods
       * Alternate Domain Names: Add your custom domain (e.g., `cdn.yourdomain.com`)
       * SSL Certificate: Request or import your certificate

2. **Add DNS Record**:
       ```bash
       # Add CNAME record in your DNS
       cdn.yourdomain.com -> your-cloudfront-distribution.cloudfront.net
       ```

3. **Update Environment Variables**:
       ```bash
       # Add to your .env.local
       S3_CUSTOM_DOMAIN=https://cdn.yourdomain.com
       ```

### Option 2: Public Bucket with Custom Domain

If your bucket is public (not recommended for production):

1. **Configure Bucket for Website Hosting**:
       * Go to your S3 bucket → Properties
       * Enable "Static website hosting"
       * Set index document to `index.html`
       * Note the website endpoint

2. **Add DNS Record**:
       ```bash
       # Add CNAME record in your DNS
       uploads.yourdomain.com -> your-bucket.s3-website-region.amazonaws.com
       ```

3. **Update Environment Variables**:
       ```bash
       # Add to your .env.local
       S3_CUSTOM_DOMAIN=https://uploads.yourdomain.com
       ```

<Callout type="warn">
      **Security Note**: Public buckets are not recommended for production. Use CloudFront with proper access controls instead.
    </Callout>
  </Step>

<Step>
    ## Configure Your App

Set up pushduck with your AWS S3 configuration:

```typescript
    // lib/upload.ts
    import { createUploadConfig } from "pushduck/server";

export const { s3, config } = createUploadConfig()
      .provider("aws", {
        accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
        region: process.env.AWS_REGION!,
        bucket: process.env.AWS_S3_BUCKET_NAME!,
        // Optional: Custom domain for public files
        customDomain: process.env.S3_CUSTOM_DOMAIN,
      })
      .defaults({
        maxFileSize: "10MB",
        acl: "private", // Use 'public-read' for public files
      })
      .build();

export { s3 };
    ```

<Callout type="info">
      **Custom Domain**: When `customDomain` is configured, public URLs will use your custom domain instead of the S3 URL. Internal operations (upload, delete) still use S3 endpoints.
    </Callout>
  </Step>

<Step>
    ## Test Your Configuration

Verify everything works by testing an upload.

1. **Start Your App**: Run your development server
    2. **Test Upload**: Try uploading a file using your upload component
    3. **Check S3**: Verify the file appears in your S3 bucket
    4. **Check Access**: Verify you can access the uploaded file via its URL

If something's not working:

* ✅ Check CORS configuration matches your domain
    * ✅ Verify IAM policy has correct bucket name
    * ✅ Confirm environment variables are loaded
    * ✅ Check browser console for specific error messages
  </Step>
</Steps>

## Setup Complete

Your AWS S3 bucket is now ready for production! Here's what you've accomplished:

* **Secure Storage**: Files are stored in AWS's infrastructure
* **Cost Efficient**: Pay only for what you use, with free tier coverage
* **Globally Accessible**: Files available worldwide with low latency
* **Scalable**: Handles millions of files without configuration changes
* **Secure Access**: Minimal IAM permissions and proper CORS setup

## Cost Optimization

Keep your AWS bills low with these optimization tips:

### Storage Classes

```bash
# Standard: $0.023 per GB/month - for frequently accessed files
# Standard-IA: $0.0125 per GB/month - for infrequently accessed files
# Glacier: $0.004 per GB/month - for archival (retrieval takes hours)
```

### Lifecycle Policies

Set up automatic transitions to save money:

1. **Go to Your Bucket** → Management → Lifecycle rules
2. **Create Rule**:
   * Transition to Standard-IA after 30 days
   * Transition to Glacier after 90 days
   * Delete incomplete multipart uploads after 1 day

### Request Optimization

* **Use CloudFront**: Cache files globally to reduce S3 requests
* **Batch Operations**: Group multiple operations when possible
* **Monitor Usage**: Set up billing alerts for unexpected costs

## Security Best Practices

### Access Control

```json
// Example: User-specific upload paths
{
  "prefix": "users/${user.id}/*",
  "maxFileSize": "10MB",
      "types": ["image/jpeg", "image/png"]
}
```

### Monitoring

1. **Enable CloudTrail**: Track all S3 API calls
2. **Set Up Alerts**: Monitor unusual access patterns
3. **Regular Audits**: Review IAM permissions quarterly

### Backup Strategy

```bash
# Cross-region replication for critical data
Source Bucket: us-east-1
Replica Bucket: us-west-2
Replication: Real-time
```

## What's Next?

Now that AWS S3 is configured, explore these advanced features:

<div className="grid grid-cols-1 md:grid-cols-2 gap-4 mt-8">
  <div className="p-4 border rounded-lg">
    <h3 className="font-semibold mb-2">
      🖼️ Image Uploads
    </h3>

<p className="text-sm text-gray-600 mb-3">
      Handle image uploads with optimization and validation
    </p>

<a href="/docs/guides/image-uploads" className="text-blue-600 text-sm hover:underline">
      Image Guide →
    </a>
  </div>

<div className="p-4 border rounded-lg">
    <h3 className="font-semibold mb-2">
      🔐 Authentication
    </h3>

<p className="text-sm text-gray-600 mb-3">
      Secure your uploads with proper authentication
    </p>

<a href="/docs/guides/security/authentication" className="text-blue-600 text-sm hover:underline">
      Security Guide →
    </a>
  </div>

<div className="p-4 border rounded-lg">
    <h3 className="font-semibold mb-2">
      🚀 Production Deploy
    </h3>

<p className="text-sm text-gray-600 mb-3">
      Essential checklist for production deployment
    </p>

<a href="/docs/guides/production-checklist" className="text-blue-600 text-sm hover:underline">
      Production Guide →
    </a>
  </div>

<div className="p-4 border rounded-lg">
    <h3 className="font-semibold mb-2">
      🛠️ API Reference
    </h3>

<p className="text-sm text-gray-600 mb-3">
      Complete API documentation and examples
    </p>

## Pro Tips

<Callout type="info">
  **Naming Convention**: Use consistent bucket naming like `{company}-{app}-   {environment}-uploads` for easy management across multiple projects.
</Callout>

<Callout type="warn">
  **Cost Alert**: Set up AWS billing alerts at $5, $20, and $50 to avoid
  surprise charges during development.
</Callout>

<Callout type="success">
  **Performance**: Place your S3 bucket in the same region as your application
  server for fastest presigned URL generation.
</Callout>

***

**Need help with AWS S3 setup?** Join our [Discord community](https://pushduck.dev/discord) or check out the [troubleshooting guide](/docs/api/troubleshooting) for common issues.

# Cloudflare R2 (/docs/providers/cloudflare-r2)

## Using Cloudflare R2

Set up Cloudflare R2 for lightning-fast file uploads with zero egress fees.

## Why Choose Cloudflare R2?

* **Global Performance**: Cloudflare's edge network for fast uploads worldwide
* **Cost Effective**: 10x cheaper than S3 with zero egress fees
* **S3 Compatible**: Works with existing S3 tools and libraries
* **Built-in CDN**: Automatic content distribution via Cloudflare's network

## 1. Create an R2 Bucket

1. Go to [Cloudflare Dashboard](https://dash.cloudflare.com/)
2. Click **"R2 Object Storage"** in the sidebar
3. Click **"Create bucket"**
4. Choose a unique bucket name (e.g., `my-app-uploads`)
5. Select your preferred location (Auto for global performance)
6. Click **"Create bucket"**

## 2. Configure Public Access (Optional)

### For Public Files (Images, Documents)

1. Go to your bucket settings
2. Click **"Settings"** tab
3. Under **"Public access"**, click **"Allow Access"**
4. Choose **"Custom domain"** or use the R2.dev subdomain

**Custom Domain Setup:**

```bash
# Add a CNAME record in your DNS:
# uploads.yourdomain.com -> your-bucket.r2.cloudflarestorage.com
```

### For Private Files

Keep public access disabled - files will only be accessible via presigned URLs.

## 3. Generate API Token

1. Go to **"Manage R2 API tokens"**
2. Click **"Create API token"**
3. Set permissions:
   * **Object:Read** ✅
   * **Object:Write** ✅
   * **Bucket:Read** ✅
4. Choose **"Specify bucket"** and select your bucket
5. Click **"Create API token"**
6. **Save your Access Key ID and Secret Access Key**

## 4. Configure CORS (If Using Custom Domain)

<Callout type="info">
  **Comprehensive CORS Guide**: For detailed CORS configuration, testing, and troubleshooting, see the [CORS & ACL Configuration Guide](/docs/guides/security/cors-and-acl).
</Callout>

In your R2 bucket settings, add this CORS policy:

```json
[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
    "AllowedOrigins": ["http://localhost:3000", "https://yourdomain.com"],
    "ExposeHeaders": ["ETag", "Content-Length"]
  }
]
```

## 5. Configure Your App

### Environment Variables

Add to your `.env.local`:

```bash
# Cloudflare R2 Configuration
AWS_ACCESS_KEY_ID=your_r2_access_key_id
AWS_SECRET_ACCESS_KEY=your_r2_secret_access_key
AWS_ENDPOINT_URL=https://account-id.r2.cloudflarestorage.com
AWS_REGION=auto
S3_BUCKET_NAME=your-bucket-name

# Optional: Custom domain for public files
CLOUDFLARE_R2_CUSTOM_DOMAIN=https://uploads.yourdomain.com
```

### Custom Domain Setup (Optional)

For better performance and branding, you can use a custom domain:

1. **Add Custom Domain in R2 Dashboard**:
   * Go to your R2 bucket → Settings
   * Click "Add Custom Domain"
   * Enter your domain (e.g., `uploads.yourdomain.com`)
   * Cloudflare will provide DNS records to add

2. **Add DNS Records**:
   ```bash
   # Add CNAME record in your DNS
   uploads.yourdomain.com -> your-bucket.r2.cloudflarestorage.com
   ```

3. **SSL Certificate**: Cloudflare automatically provides SSL certificates for custom domains

4. **Update Environment Variables**:
   ```bash
   # Add to your .env.local
   CLOUDFLARE_R2_CUSTOM_DOMAIN=https://uploads.yourdomain.com
   ```

<Callout type="info">
  **Built-in CDN**: Cloudflare R2 custom domains automatically include global CDN acceleration with 250+ locations worldwide.
</Callout>

## 6. Update Your Upload Configuration

```typescript
// lib/upload.ts
import { createUploadConfig } from "pushduck/server";

export const { s3,  } = createUploadConfig()
  .provider("cloudflareR2",{
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    accountId: process.env.R2_ACCOUNT_ID!, // Found in R2 dashboard
    bucket: process.env.S3_BUCKET_NAME!,
    // Optional: Custom domain for faster access
    customDomain: process.env.CLOUDFLARE_R2_CUSTOM_DOMAIN,
  })
  .defaults({
    maxFileSize: "10MB",
    acl: "public-read", // For public access
  })
  .build();
```

## 7. Test Your Setup

```bash
npx @pushduck/cli@latest test --provider r2
```

This will verify your R2 connection and upload a test file.

## You're Ready!

Your Cloudflare R2 is now configured! Files will be:

* **Uploaded globally** via Cloudflare's edge network
* **Served fast** with built-in CDN
* **Cost effective** with zero egress fees

## Performance Benefits

### Global Upload Acceleration

R2 automatically routes uploads to the nearest Cloudflare data center:

```typescript
// Automatic performance optimization
const { uploadFiles } = upload.imageUpload();

// Uploads are automatically optimized for:
// - Nearest edge location
// - Fastest route to storage
// - Automatic retry on connection issues
```

### Built-in CDN

Your uploaded files are automatically cached globally:

```typescript
// Files are served from 250+ locations worldwide
const imageUrl = file.url; // Automatically CDN-accelerated
```

## Advanced Configuration

### Worker Integration

Integrate with Cloudflare Workers for server-side processing:

```typescript
// Advanced R2 setup with Workers
export const { s3,  } = createUploadConfig()
  .provider("cloudflareR2",{
    // ... basic config
    workerScript: "image-transform", // Optional: Transform images on upload
    webhookUrl: "https://api.yourdomain.com/webhook", // Optional: Post-upload webhook
  })
  .build();
```

### Analytics & Monitoring

Track upload performance:

```typescript
.hooks({
  onUploadComplete: async ({ file, metadata }) => {
    // Track successful uploads
    await analytics.track("file_uploaded", {
      provider: "cloudflare-r2",
      size: file.size,
      type: file.type,
      location: metadata.cfRay, // Cloudflare location
    });
  }
})
```

## Security Best Practices

* **Use scoped API tokens** - Only grant permissions to specific buckets
* **Enable custom domain** - Better security than r2.dev subdomain
* **Set up WAF rules** - Protect against abuse via Cloudflare dashboard
* **Monitor usage** - Set up billing alerts for unexpected usage

## 🆘 Common Issues

**CORS errors?** → Check your domain is in AllowedOrigins and verify custom domain setup. For detailed CORS configuration, see the [CORS & ACL Configuration Guide](/docs/guides/security/cors-and-acl).\
**Access denied?** → Verify API token has Object:Read and Object:Write permissions\
**Slow uploads?** → Ensure you're using the correct endpoint URL with your account ID\
**Custom domain not working?** → Verify CNAME record and bucket public access settings

## Cost Comparison

| Provider          | Storage      | Egress        | Requests      |
| ----------------- | ------------ | ------------- | ------------- |
| **Cloudflare R2** | $0.015/GB    | **FREE**      | $0.36/million |
| AWS S3            | $0.023/GB    | $0.09/GB      | $0.40/million |
| **Savings**       | **35% less** | **100% less** | **10% less**  |

***

**Next:** [Upload Your First Image](/docs/guides/image-uploads) or try [DigitalOcean Spaces](/docs/providers/digitalocean-spaces)

# DigitalOcean Spaces (/docs/providers/digitalocean-spaces)

## Using DigitalOcean Spaces

Set up DigitalOcean Spaces for fast, affordable file uploads with built-in CDN.

## Why Choose DigitalOcean Spaces?

* **Predictable Pricing**: Simple pricing with generous free tier
* **Built-in CDN**: Free CDN with all Spaces for global performance
* **S3 Compatible**: Works with S3 tools and libraries
* **Easy Setup**: Simple configuration with great developer experience

## 1. Create a Space

1. Go to [DigitalOcean Cloud Panel](https://cloud.digitalocean.com/spaces)
2. Click **"Create a Space"**
3. Choose a datacenter region (closest to your users)
4. Enter a unique Space name (e.g., `my-app-uploads`)
5. Choose **"Restrict File Listing"** for security
6. Enable **"CDN"** for global distribution
7. Click **"Create a Space"**

## 2. Configure CDN (Recommended)

DigitalOcean automatically creates a CDN endpoint:

* **Space URL**: `https://my-app-uploads.nyc3.digitaloceanspaces.com`
* **CDN URL**: `https://my-app-uploads.nyc3.cdn.digitaloceanspaces.com`

### Custom Domain (Optional)

Set up your own domain for branded URLs:

1. Go to **"Settings"** in your Space
2. Click **"Add Custom Domain"**
3. Enter your domain (e.g., `uploads.yourdomain.com`)
4. Add a CNAME record in your DNS:
   ```bash
   # DNS Record:
   uploads.yourdomain.com -> my-app-uploads.nyc3.cdn.digitaloceanspaces.com
   ```

## 3. Generate API Keys

1. Go to **"API"** in your DigitalOcean dashboard
2. Click **"Spaces access keys"**
3. Click **"Generate New Key"**
4. Enter a name (e.g., "My App Uploads")
5. **Save your Access Key and Secret Key**

## 4. Configure CORS

<Callout type="info">
  **Comprehensive CORS Guide**: For detailed CORS configuration, testing, and troubleshooting, see the [CORS & ACL Configuration Guide](/docs/guides/security/cors-and-acl).
</Callout>

In your Space settings, add this CORS configuration:

## 5. Configure Your App

Add to your `.env.local`:

```bash
# DigitalOcean Spaces Configuration
AWS_ACCESS_KEY_ID=your_spaces_access_key
AWS_SECRET_ACCESS_KEY=your_spaces_secret_key
AWS_ENDPOINT_URL=https://nyc3.digitaloceanspaces.com
AWS_REGION=nyc3
S3_BUCKET_NAME=your-space-name

# CDN Configuration (recommended)
DO_SPACES_CUSTOM_DOMAIN=https://your-space-name.nyc3.cdn.digitaloceanspaces.com
# Or your custom domain:
# DO_SPACES_CUSTOM_DOMAIN=https://uploads.yourdomain.com
```

## 6. Update Your Upload Configuration

```typescript
// lib/upload.ts
import { createUploadConfig } from "pushduck/server";

export const { s3,  } = createUploadConfig()
  .provider("digitalOceanSpaces",{
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    region: process.env.AWS_REGION!, // e.g., 'nyc3', 'sfo3', 'ams3'
    bucket: process.env.S3_BUCKET_NAME!,
    // Use CDN for faster file serving
    customDomain: process.env.DO_SPACES_CUSTOM_DOMAIN,
  })
  .defaults({
    maxFileSize: "50MB", // Spaces supports larger files
    acl: "public-read",
  })
  .build();
```

## 7. Test Your Setup

```bash
npx @pushduck/cli@latest test --provider digitalocean
```

This will verify your Spaces connection and upload a test file.

## You're Ready!

Your DigitalOcean Space is configured! Benefits:

* **Global CDN** - Files served from 12+ locations worldwide
* **Affordable pricing** - $5/month for 250GB + 1TB transfer
* **High performance** - Built-in CDN acceleration

## 🌐 CDN Benefits

### Automatic Global Distribution

Your files are automatically cached worldwide:

```typescript
// Files are served from the nearest CDN location
const imageUrl = file.url; // Automatically CDN-accelerated

// CDN locations include:
// - North America: NYC, SF, Toronto
// - Europe: Amsterdam, London, Frankfurt
// - Asia: Singapore, Bangalore
```

### Cache Control

Optimize caching for different file types:

```typescript
// Configure caching per upload type
const imageUpload = s3
  .image()
  .maxFileSize("10MB")
  .onUploadComplete(async ({ file, key }) => {
    // Set cache headers for images (long cache)
    await setObjectMetadata(key, {
      "Cache-Control": "public, max-age=31536000", // 1 year
      "Content-Type": file.type,
    });
  });

const documentUpload = s3
  .file()
  .accept(["application/pdf", "application/vnd.openxmlformats-officedocument.wordprocessingml.document"])
  .onUploadComplete(async ({ file, key }) => {
    // Shorter cache for documents
    await setObjectMetadata(key, {
      "Cache-Control": "public, max-age=86400", // 1 day
    });
  });
```

## Advanced Configuration

### Multiple Regions

Deploy across multiple regions for redundancy:

```typescript
// Primary region (closest to users)
const primarySpaces = createUploadConfig().provider("digitalOceanSpaces",{
  region: "nyc3", // New York
  bucket: "my-app-uploads-us",
});

// Backup region
const backupSpaces = createUploadConfig().provider("digitalOceanSpaces",{
  region: "ams3", // Amsterdam
  bucket: "my-app-uploads-eu",
});
```

### Lifecycle Policies

Automatically manage old files:

```typescript
// Configure automatic cleanup
.hooks({
  onUploadComplete: async ({ file, metadata }) => {
    // Schedule deletion of temporary files
    if (metadata.category === 'temp') {
      await scheduleCleanup(file.key, { days: 7 });
    }
  }
})
```

## Pricing Breakdown

| Resource     | Included  | Overage  |
| ------------ | --------- | -------- |
| **Storage**  | 250 GB    | $0.02/GB |
| **Transfer** | 1 TB      | $0.01/GB |
| **CDN**      | Included  | Free     |
| **Requests** | Unlimited | Free     |

**Total**: $5/month for most small-medium apps

## Security Features

### Private Spaces

For sensitive files:

```typescript
// Configure private access
export const { s3,  } = createUploadConfig()
  .provider("digitalOceanSpaces",{
    // ... config
    acl: "private", // Files not publicly accessible
  })
  .defaults({
    generatePresignedUrl: true, // Generate secure URLs
    urlExpirationHours: 1, // URLs expire after 1 hour
  })
  .build();
```

### File Access Control

Control who can access what:

```typescript
.middleware(async ({ req, file }) => {
  const user = await authenticate(req);

// Only allow users to upload to their own folder
  const userPrefix = `users/${user.id}/`;

return {
    userId: user.id,
    keyPrefix: userPrefix,
  };
})
```

## Monitoring & Analytics

### Usage Monitoring

Track your Space usage:

```typescript
// Monitor uploads in real-time
.hooks({
  onUploadStart: async ({ file }) => {
    await analytics.track("upload_started", {
      provider: "digitalocean-spaces",
      fileSize: file.size,
      fileType: file.type,
    });
  },
  onUploadComplete: async ({ file, metadata }) => {
    await analytics.track("upload_completed", {
      provider: "digitalocean-spaces",
      duration: metadata.uploadTime,
      cdnEnabled: true,
    });
  }
})
```

## 🆘 Common Issues

**CORS errors?** → Verify your domain is in AllowedOrigins and CORS is enabled. For detailed CORS configuration, see the [CORS & ACL Configuration Guide](/docs/guides/security/cors-and-acl).\
**Slow uploads?** → Check you're using the correct regional endpoint\
**CDN not working?** → Verify CDN is enabled and using the cdn.digitaloceanspaces.com endpoint\
**Access denied?** → Check your API keys have Spaces read/write permissions\
**File not found?** → Ensure you're using the CDN endpoint for file access

## Performance Tips

1. **Use CDN endpoints** for all file access (not direct Space URLs)
2. **Choose closest region** to your primary user base
3. **Enable gzip compression** for text files
4. **Set proper cache headers** for different file types
5. **Use progressive image formats** (WebP, AVIF) when possible

***

**Next:** [Upload Your First Image](/docs/guides/image-uploads) or try [MinIO Setup](/docs/providers/minio)

# Google Cloud Storage (/docs/providers/google-cloud)

## Using Google Cloud Storage

Set up Google Cloud Storage (GCS) for scalable, global file uploads with Google's infrastructure.

## Why Choose Google Cloud Storage?

* **Global Infrastructure**: Google's worldwide network for fast access
* **S3 Compatible**: Works with S3-compatible libraries via XML API
* **Competitive Pricing**: Cost-effective with multiple storage classes
* **Security**: Google-grade security and compliance
* **High Performance**: Optimized for speed and reliability

## 1. Create a GCS Bucket

### Using Google Cloud Console

1. Go to [Google Cloud Console](https://console.cloud.google.com/storage)
2. Select or create a project
3. Click **"Create bucket"**
4. Configure your bucket:
   * **Name**: Choose a globally unique name (e.g., `my-app-uploads-bucket`)
   * **Location**: Choose region closest to your users
   * **Storage class**: Standard (for frequently accessed files)
   * **Access control**: Fine-grained (recommended)
5. Click **"Create"**

### Using gcloud CLI

```bash
# Install gcloud CLI (if not already installed)
curl https://sdk.cloud.google.com | bash
exec -l $SHELL
gcloud init

# Create bucket
gsutil mb -p your-project-id -c STANDARD -l us-central1 gs://my-app-uploads-bucket
```

## 2. Configure Public Access (Optional)

### For Public Files (Images, Documents)

```bash
# Make bucket publicly readable
gsutil iam ch allUsers:objectViewer gs://my-app-uploads-bucket

# Or using Console:
# Storage → Bucket → Permissions → Add → "allUsers" → "Storage Object Viewer"
```

### For Private Files

Keep default settings - files will only be accessible via signed URLs.

## 3. Create Service Account

1. Go to [IAM & Admin](https://console.cloud.google.com/iam-admin/serviceaccounts)
2. Click **"Create Service Account"**
3. Enter details:
   * **Name**: `upload-service`
   * **Description**: "Service account for file uploads"
4. Click **"Create and Continue"**
5. Grant roles:
   * **Storage Admin** (or **Storage Object Admin** for bucket-specific access)
6. Click **"Continue"** → **"Done"**

## 4. Generate Service Account Key

1. Click on your service account
2. Go to **"Keys"** tab
3. Click **"Add Key"** → **"Create new key"**
4. Choose **"JSON"** format
5. **Download and securely store the JSON file**

## 5. Configure CORS

<Callout type="info">
  **Comprehensive CORS Guide**: For detailed CORS configuration, testing, and troubleshooting, see the [CORS & ACL Configuration Guide](/docs/guides/security/cors-and-acl).
</Callout>

```bash
# Create cors.json file
cat > cors.json << EOF
[
  {
    "origin": ["http://localhost:3000", "https://yourdomain.com"],
    "method": ["GET", "PUT", "POST", "DELETE", "HEAD"],
    "responseHeader": ["Content-Type", "ETag", "Content-Length"],
    "maxAgeSeconds": 3600
  }
]
EOF

# Apply CORS configuration
gsutil cors set cors.json gs://my-app-uploads-bucket
```

## 6. Configure Your App

Add to your `.env.local`:

```bash
# Google Cloud Storage Configuration
GOOGLE_APPLICATION_CREDENTIALS=./path/to/service-account-key.json
GCS_PROJECT_ID=your-project-id
GCS_BUCKET_NAME=my-app-uploads-bucket

# Optional: Custom domain for public files
GCS_CUSTOM_DOMAIN=https://storage.googleapis.com/my-app-uploads-bucket
# Or with custom domain: GCS_CUSTOM_DOMAIN=https://uploads.yourdomain.com
```

## 7. Update Your Upload Configuration

```typescript
// lib/upload.ts
import { createUploadConfig } from "pushduck/server";

export const { s3,  } = createUploadConfig()
  .provider("gcs",{
    projectId: process.env.GCS_PROJECT_ID!,
    keyFilename: process.env.GOOGLE_APPLICATION_CREDENTIALS!,
    bucket: process.env.GCS_BUCKET_NAME!,
    // Optional: Custom domain for public files
    customDomain: process.env.GCS_CUSTOM_DOMAIN,
  })
  .defaults({
    maxFileSize: "100MB", // GCS supports large files
    acl: "publicRead", // For public access
  })
  .build();
```

## 8. Test Your Setup

```bash
npx @pushduck/cli@latest test --provider gcs
```

This will verify your GCS connection and upload a test file.

## You're Ready!

Your Google Cloud Storage is configured! Benefits:

* **Global performance** via Google's network
* **Automatic scaling** to handle any load
* **Enterprise-grade security** and compliance
* **Multiple storage classes** for cost optimization

## 🌐 Advanced Features

### Multi-Regional Storage

```typescript
// Configure multi-regional bucket for global performance
export const { s3,  } = createUploadConfig()
  .provider("gcs",{
    // ... basic config
    bucket: process.env.GCS_BUCKET_NAME!,
    // Multi-regional configuration
    location: "US", // or "EU", "ASIA"
    storageClass: "MULTI_REGIONAL",
  })
  .build();
```

### Storage Classes

Optimize costs with different storage classes:

```typescript
// Configure lifecycle policies for cost optimization
.hooks({
  onUploadComplete: async ({ file, key, metadata }) => {
    // Move old files to cheaper storage classes
    if (metadata.category === 'archive') {
      await moveToStorageClass(key, 'COLDLINE');
    } else if (metadata.category === 'backup') {
      await moveToStorageClass(key, 'ARCHIVE');
    }
  }
})
```

### CDN Integration

```typescript
// Use Cloud CDN for faster global delivery
export const { s3,  } = createUploadConfig()
  .provider("gcs",{
    // ... config
    // Configure CDN endpoint
    cdnUrl: "https://your-cdn-domain.com",
    // Cache control headers
    defaultCacheControl: "public, max-age=31536000",
  })
  .build();
```

## Security Best Practices

### Bucket-Level IAM

```bash
# Create custom role with minimal permissions
gcloud iam roles create upload_service_role \
  --project=your-project-id \
  --title="Upload Service Role" \
  --permissions="storage.objects.create,storage.objects.get"

# Bind role to service account
gcloud projects add-iam-policy-binding your-project-id \
  --member="serviceAccount:upload-service@your-project-id.iam.gserviceaccount.com" \
  --role="projects/your-project-id/roles/upload_service_role"
```

### Object-Level Security

```typescript
// Implement user-based access control
.middleware(async ({ req, file }) => {
  const user = await authenticate(req);

// Generate user-specific path
  const userPath = `users/${user.id}/${file.name}`;

return {
    userId: user.id,
    keyPrefix: `users/${user.id}/`,
    metadata: {
      uploadedBy: user.id,
      uploadedAt: new Date().toISOString(),
    }
  };
})
```

### Signed URLs for Private Access

```typescript
// Generate time-limited access URLs
.hooks({
  onUploadComplete: async ({ file, key }) => {
    if (file.private) {
      // Generate signed URL valid for 1 hour
      const signedUrl = await generateSignedUrl(key, {
        action: 'read',
        expires: Date.now() + 60 * 60 * 1000, // 1 hour
      });

return { ...file, url: signedUrl };
    }
    return file;
  }
})
```

## Cost Optimization

### Storage Class Strategy

| Use Case         | Storage Class | Cost   | Access Pattern   |
| ---------------- | ------------- | ------ | ---------------- |
| **Active files** | Standard      | Higher | Frequent access  |
| **Backups**      | Nearline      | Medium | Monthly access   |
| **Archives**     | Coldline      | Lower  | Quarterly access |
| **Long-term**    | Archive       | Lowest | Yearly access    |

### Lifecycle Management

```typescript
// Automatic lifecycle transitions
const lifecyclePolicy = {
  rule: [
    {
      action: { type: "SetStorageClass", storageClass: "NEARLINE" },
      condition: { age: 30 }, // Move to Nearline after 30 days
    },
    {
      action: { type: "SetStorageClass", storageClass: "COLDLINE" },
      condition: { age: 90 }, // Move to Coldline after 90 days
    },
    {
      action: { type: "Delete" },
      condition: { age: 365 }, // Delete after 1 year
    },
  ],
};
```

## Monitoring & Analytics

### Cloud Monitoring Integration

```typescript
// Track upload metrics
.hooks({
  onUploadStart: async ({ file }) => {
    await cloudMonitoring.createTimeSeries({
      name: 'custom.googleapis.com/upload/started',
      value: 1,
      labels: {
        file_type: file.type,
        file_size_mb: Math.round(file.size / 1024 / 1024),
      }
    });
  },
  onUploadComplete: async ({ file, metadata }) => {
    await cloudMonitoring.createTimeSeries({
      name: 'custom.googleapis.com/upload/completed',
      value: metadata.uploadDuration,
      labels: {
        success: 'true',
        provider: 'gcs',
      }
    });
  }
})
```

### Usage Analytics

```typescript
// Track storage usage and costs
const getStorageMetrics = async () => {
  const bucket = storage.bucket(process.env.GCS_BUCKET_NAME!);
  const [metadata] = await bucket.getMetadata();

return {
    totalSize: metadata.storageClass?.totalBytes,
    objectCount: metadata.storageClass?.objectCount,
    storageClass: metadata.storageClass?.name,
    location: metadata.location,
  };
};
```

## 🌐 Custom Domain Setup

### 1. Verify Domain Ownership

```bash
# Add verification record to DNS
# TXT record: google-site-verification=your-verification-code

# Verify domain
gcloud domains verify yourdomain.com
```

### 2. Configure CNAME

```bash
# Add CNAME record to DNS
# uploads.yourdomain.com -> c.storage.googleapis.com
```

### 3. Update Configuration

```typescript
// Use custom domain for file URLs
export const { s3,  } = createUploadConfig()
  .provider("gcs",{
    // ... config
    customDomain: "https://uploads.yourdomain.com",
  })
  .build();
```

## 🆘 Common Issues

**Authentication errors?** → Check service account key path and permissions\
**CORS errors?** → Verify CORS configuration and allowed origins. For detailed CORS configuration, see the [CORS & ACL Configuration Guide](/docs/guides/security/cors-and-acl).\
**Access denied?** → Check IAM roles and bucket permissions\
**Slow uploads?** → Choose region closer to your users\
**Quota exceeded?** → Check project quotas and billing account

## Performance Tips

1. **Choose the right region** - closest to your users
2. **Use multi-regional** for global applications
3. **Enable CDN** for frequently accessed files
4. **Optimize image sizes** before upload
5. **Use parallel uploads** for multiple files
6. **Implement proper caching** headers

***

**Next:** [Upload Your First Image](/docs/guides/image-uploads) or check out our [Examples](/docs/examples)

# Storage Providers (/docs/providers)

import { Card, Cards } from "fumadocs-ui/components/card";
import { Callout } from "fumadocs-ui/components/callout";

## Supported Storage Providers

Pushduck supports multiple cloud storage providers through a unified S3-compatible API. Choose the provider that best fits your needs, budget, and infrastructure requirements.

<Callout type="info">
  **Universal S3 API**: All providers use the same configuration pattern, making it easy to switch between them or use multiple providers in the same project.
</Callout>

## Supported Providers

<Cards>
  <Card title="AWS S3" description="The original cloud storage service with global availability and advanced features" href="/docs/providers/aws-s3">
    **Best for**: Enterprise applications, complex workflows, global scale

• Global edge locations\
    • Advanced security features\
    • Comprehensive ecosystem\
    • Trusted by millions
  </Card>

<Card title="Cloudflare R2" description="Zero egress fees with global edge network performance" href="/docs/providers/cloudflare-r2">
    **Best for**: High-traffic applications, cost optimization

• No egress fees\
    • Global edge network\
    • Fast performance\
    • Simple pricing
  </Card>

<Card title="DigitalOcean Spaces" description="Simple, predictable pricing with built-in CDN" href="/docs/providers/digitalocean-spaces">
    **Best for**: Small to medium applications, predictable costs

• Flat-rate pricing\
    • Built-in CDN\
    • Simple setup\
    • Developer-friendly
  </Card>

<Card title="Google Cloud Storage" description="AI-powered insights with global infrastructure" href="/docs/providers/google-cloud">
    **Best for**: AI/ML workloads, Google ecosystem integration

• AI integration\
    • Global network\
    • Strong consistency\
    • Advanced analytics
  </Card>

<Card title="MinIO" description="Self-hosted S3-compatible storage for complete control" href="/docs/providers/minio">
    **Best for**: Self-hosted deployments, data sovereignty

• Self-hosted\
    • Full control\
    • High performance\
    • Open source
  </Card>

<Card title="S3-Compatible (Generic)" description="Use any S3-compatible storage service" href="/docs/providers/s3-compatible">
    **Best for**: Custom deployments, other S3-compatible services

• Universal compatibility\
    • Custom endpoints\
    • Flexible configuration\
    • Vendor independence
  </Card>
</Cards>

## Quick Setup

All providers follow the same configuration pattern:

```typescript
import { createS3Router, s3 } from 'pushduck/server';

const uploadRouter = createS3Router({
  // Configure your storage provider
  storage: {
    provider: 'aws-s3', // or 'cloudflare-r2', 'digitalocean-spaces', etc.
    region: 'us-east-1',
    bucket: 'your-bucket-name',
    credentials: {
      accessKeyId: process.env.ACCESS_KEY_ID!,
      secretAccessKey: process.env.SECRET_ACCESS_KEY!,
    },
  },
  
  // Define your upload routes
  routes: {
    imageUpload: s3.image().maxFileSize("5MB"),
    documentUpload: s3.file().maxFileSize("10MB"),
  },
});
```

## Provider Comparison

| Provider                | Pricing Model | Egress Fees    | CDN Included     | Best For                     |
| ----------------------- | ------------- | -------------- | ---------------- | ---------------------------- |
| **AWS S3**              | Pay-per-use   | Yes            | Separate service | Enterprise, global scale     |
| **Cloudflare R2**       | Pay-per-use   | **No**         | Yes              | High-traffic, cost-sensitive |
| **DigitalOcean Spaces** | Flat-rate     | Included quota | Yes              | Predictable costs            |
| **Google Cloud**        | Pay-per-use   | Yes            | Separate service | AI/ML integration            |
| **MinIO**               | Self-hosted   | None           | Self-managed     | Data sovereignty             |

## Need Help Choosing?

<Callout type="tip">
  **Quick Recommendation**:

* **Starting out?** → DigitalOcean Spaces (simple, predictable)
  * **High traffic?** → Cloudflare R2 (no egress fees)
  * **Enterprise?** → AWS S3 (full ecosystem)
  * **Self-hosted?** → MinIO (complete control)
</Callout>

## Next Steps

1. Choose your provider from the cards above
2. Follow the provider-specific setup guide
3. Configure your upload routes
4. Start uploading files!

Each provider guide includes:

* Step-by-step setup instructions
* Environment variable configuration
* Production deployment tips
* Troubleshooting common issues

# MinIO (/docs/providers/minio)

## Using MinIO

Set up MinIO for self-hosted, S3-compatible object storage with full control and privacy.

## Why Choose MinIO?

* **🏠 Self-Hosted**: Complete control over your data and infrastructure
* **🔗 S3 Compatible**: Drop-in replacement for AWS S3 API
* **Cost Effective**: No cloud provider fees - just your server costs
* **Private**: Keep sensitive data on your own infrastructure
* **High Performance**: Optimized for speed and throughput

## Quick Start with Docker

### 1. Start MinIO Server

```bash
# Create data directory
mkdir -p ~/minio/data

# Start MinIO server
docker run -d \
  --name minio \
  -p 9000:9000 \
  -p 9001:9001 \
  -v ~/minio/data:/data \
  -e "MINIO_ROOT_USER=minioadmin" \
  -e "MINIO_ROOT_PASSWORD=minioadmin123" \
  quay.io/minio/minio server /data --console-address ":9001"
```

### 2. Access MinIO Console

1. Open `http://localhost:9001` in your browser
2. Login with:
   * **Username**: `minioadmin`
   * **Password**: `minioadmin123`

### 3. Create a Bucket

1. Click **"Create Bucket"**
2. Enter bucket name (e.g., `my-app-uploads`)
3. Click **"Create Bucket"**

### 4. Create Access Keys

1. Go to **"Identity"** → **"Service Accounts"**
2. Click **"Create service account"**
3. Enter a name (e.g., "Upload Service")
4. Click **"Create"**
5. **Save your Access Key and Secret Key**

## 🏭 Production Docker Setup

### Docker Compose Configuration

```yaml
# docker-compose.yml
version: "3.8"

services:
  minio:
    image: quay.io/minio/minio:latest
    container_name: minio
    ports:
      - "9000:9000" # API
      - "9001:9001" # Console
    volumes:
      - minio_data:/data
    environment:
      MINIO_ROOT_USER: ${MINIO_ROOT_USER}
      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
    command: server /data --console-address ":9001"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 30s
      timeout: 20s
      retries: 3

volumes:
  minio_data:
```

### Environment Variables

```bash
# .env
MINIO_ROOT_USER=your-admin-username
MINIO_ROOT_PASSWORD=your-secure-password-min-8-chars
```

### Start Production Server

```bash
docker-compose up -d
```

## 🌐 Production Deployment

### 1. Reverse Proxy Setup (Nginx)

```nginx
# /etc/nginx/sites-available/minio
server {
    listen 80;
    server_name uploads.yourdomain.com;

location / {
        proxy_pass http://localhost:9000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

# Handle large uploads
        client_max_body_size 100M;
    }
}

# Console (optional - for admin access)
server {
    listen 80;
    server_name minio-console.yourdomain.com;

location / {
        proxy_pass http://localhost:9001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

### 2. SSL/TLS Setup

```bash
# Install Certbot
sudo apt install certbot python3-certbot-nginx

# Get SSL certificates
sudo certbot --nginx -d uploads.yourdomain.com
sudo certbot --nginx -d minio-console.yourdomain.com
```

## Configure Your App

### Environment Variables

Add to your `.env.local`:

```bash
# MinIO Configuration
AWS_ACCESS_KEY_ID=your_minio_access_key
AWS_SECRET_ACCESS_KEY=your_minio_secret_key
AWS_ENDPOINT_URL=http://localhost:9000
# For production: AWS_ENDPOINT_URL=https://uploads.yourdomain.com
AWS_REGION=us-east-1
S3_BUCKET_NAME=my-app-uploads

# Optional: Custom domain for public files
MINIO_CUSTOM_DOMAIN=https://uploads.yourdomain.com
```

### Custom Domain Setup (Optional)

For production deployments, you can use a custom domain:

1. **Configure Reverse Proxy** (Nginx/Apache):
   ```nginx
   server {
       listen 80;
       server_name uploads.yourdomain.com;
       
       location / {
           proxy_pass http://localhost:9000;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
       }
   }
   ```

2. **Add DNS Record**:
   ```bash
   # Add A record in your DNS
   uploads.yourdomain.com -> your-server-ip
   ```

3. **SSL Certificate** (Recommended):
   ```bash
   # Using Let's Encrypt
   certbot --nginx -d uploads.yourdomain.com
   ```

## Update Your Upload Configuration

```typescript
// lib/upload.ts
import { createUploadConfig } from "pushduck/server";

export const { s3,  } = createUploadConfig()
  .provider("minio",{
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    endpoint: process.env.AWS_ENDPOINT_URL!,
    region: process.env.AWS_REGION!,
    bucket: process.env.S3_BUCKET_NAME!,
    // Force path-style URLs for MinIO
    forcePathStyle: true,
    // Optional: Custom domain for public files
    customDomain: process.env.MINIO_CUSTOM_DOMAIN,
  })
  .defaults({
    maxFileSize: "100MB", // MinIO handles large files well
    acl: "public-read",
  })
  .build();
```

## 🧪 Test Your Setup

```bash
npx @pushduck/cli@latest test --provider minio
```

This will verify your MinIO connection and upload a test file.

## You're Ready!

Your MinIO server is configured! Benefits:

* **Full control** over your data
* **No cloud fees** - just server costs
* **High performance** for local/regional traffic
* **Complete privacy** for sensitive files

## Security Configuration

### 1. Bucket Policies

Set up access control for your bucket:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "*"
      },
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::my-app-uploads/*"
    }
  ]
}
```

### 2. Access Key Management

Create restricted access keys:

```typescript
// Service account with limited permissions
const uploadOnlyPolicy = {
  Version: "2012-10-17",
  Statement: [
    {
      Effect: "Allow",
      Action: ["s3:PutObject", "s3:PutObjectAcl", "s3:GetObject"],
      Resource: "arn:aws:s3:::my-app-uploads/*",
    },
  ],
};
```

### 3. Network Security

```yaml
# docker-compose.yml with network isolation
version: "3.8"

services:
  minio:
    # ... other config
    networks:
      - minio-network
    ports:
      # Only expose what's needed
      - "127.0.0.1:9000:9000" # Bind to localhost only
      - "127.0.0.1:9001:9001"

networks:
  minio-network:
    driver: bridge
```

## Monitoring & Maintenance

### Health Checks

```typescript
// Add health monitoring
.hooks({
  onUploadStart: async () => {
    // Check MinIO connectivity
    const isHealthy = await checkMinIOHealth();
    if (!isHealthy) {
      throw new Error("MinIO server unavailable");
    }
  }
})

async function checkMinIOHealth() {
  try {
    const response = await fetch(`${process.env.AWS_ENDPOINT_URL}/minio/health/live`);
    return response.ok;
  } catch {
    return false;
  }
}
```

### Backup Strategy

```bash
# Regular data backups
#!/bin/bash
# backup-minio.sh

BACKUP_DIR="/backups/minio/$(date +%Y-%m-%d)"
mkdir -p $BACKUP_DIR

# Backup MinIO data
docker run --rm \
  -v minio_data:/source:ro \
  -v $BACKUP_DIR:/backup \
  alpine tar czf /backup/minio-data.tar.gz -C /source .

# Backup configuration
docker exec minio mc admin config export /backup/
```

## Performance Optimization

### 1. Storage Configuration

```yaml
# Optimized for performance
services:
  minio:
    # ... other config
    environment:
      # Performance tuning
      MINIO_CACHE: "on"
      MINIO_CACHE_DRIVES: "/tmp/cache"
      MINIO_CACHE_QUOTA: "90"
    volumes:
      - minio_data:/data
      - /tmp/minio-cache:/tmp/cache # Fast SSD cache
```

### 2. Connection Optimization

```typescript
// Optimize for high throughput
export const { s3,  } = createUploadConfig()
  .provider("minio",{
    // ... config
    maxRetries: 3,
    retryDelayOptions: {
      base: 300,
      customBackoff: (retryCount) => Math.pow(2, retryCount) * 100,
    },
    // Connection pooling
    maxSockets: 25,
    timeout: 120000,
  })
  .build();
```

## Advanced Features

### Multi-Tenant Setup

```typescript
// Different buckets per tenant
const createTenantConfig = (tenantId: string) =>
  createUploadConfig()
    .provider("minio",{
      // ... base config
      bucket: `tenant-${tenantId}-uploads`,
    })
    .middleware(async ({ req }) => {
      const tenant = await getTenantFromRequest(req);
      return { tenantId: tenant.id };
    })
    .build();
```

### Distributed Setup

```yaml
# Multi-node MinIO cluster
version: "3.8"

services:
  minio1:
    image: quay.io/minio/minio:latest
    command: server http://minio{1...4}/data{1...2} --console-address ":9001"
    # ... configuration

minio2:
    image: quay.io/minio/minio:latest
    command: server http://minio{1...4}/data{1...2} --console-address ":9001"
    # ... configuration

# minio3, minio4...
```

## 🆘 Common Issues

**Connection refused?** → Check MinIO is running and port 9000 is accessible\
**Access denied?** → Verify access keys and bucket permissions\
**CORS errors?** → Set bucket policy to allow your domain. For detailed CORS configuration, see the [CORS & ACL Configuration Guide](/docs/guides/security/cors-and-acl).\
**Slow uploads?** → Check network connection and server resources\
**SSL errors?** → Verify certificate configuration for custom domains

## Use Cases

### Development Environment

* **Local testing** without cloud dependency
* **Offline development** for air-gapped environments
* **Cost-free** development and testing

### Production Scenarios

* **Data sovereignty** requirements
* **High-security** environments
* **Edge computing** deployments
* **Hybrid cloud** strategies

***

**Next:** [Upload Your First Image](/docs/guides/image-uploads) or explore [Google Cloud Storage](/docs/providers/google-cloud)

# S3-Compatible (/docs/providers/s3-compatible)

import { Step, Steps } from "fumadocs-ui/components/steps";
import { Callout } from "fumadocs-ui/components/callout";
import { Tab, Tabs } from "fumadocs-ui/components/tabs";

## S3-Compatible Storage

Connect to any S3-compatible storage service for flexible, vendor-agnostic file uploads with full type safety.

## Why Choose S3-Compatible?

* **Vendor Flexibility**: Works with any S3-compatible service
* **🏠 Self-Hosted Options**: Perfect for custom or self-hosted solutions
* **🔗 Standard API**: Uses the familiar S3 API across all providers
* **Cost Control**: Choose providers based on your budget needs
* **Data Sovereignty**: Keep data where you need it geographically

<Callout type="info">
  **Perfect for**: Self-hosted MinIO, SeaweedFS, Garage, custom storage solutions, or any S3-compatible service not explicitly supported by dedicated providers.
</Callout>

## Common S3-Compatible Services

| Service              | Use Case            | Best For                         |
| -------------------- | ------------------- | -------------------------------- |
| **SeaweedFS**        | Distributed storage | High-performance clusters        |
| **Garage**           | Lightweight storage | Self-hosted, minimal resources   |
| **Ceph RadosGW**     | Enterprise storage  | Large-scale deployments          |
| **Wasabi**           | Cloud storage       | Cost-effective cloud alternative |
| **Backblaze B2**     | Backup storage      | Archive and backup scenarios     |
| **Custom Solutions** | Specialized needs   | Custom implementations           |

<Steps>
  <Step>
    ## Identify Your S3-Compatible Service

First, gather the required information from your storage provider:

### Required Information

* **Endpoint URL**: The API endpoint for your service
    * **Access Key ID**: Your access key or username
    * **Secret Access Key**: Your secret key or password
    * **Bucket Name**: The bucket/container where files will be stored

### Common Endpoint Patterns

```bash
    # Self-hosted MinIO
    https://minio.yourdomain.com

# SeaweedFS
    https://seaweedfs.yourdomain.com:8333

# Wasabi (if not using dedicated provider)
    https://s3.wasabisys.com

# Backblaze B2 (S3-compatible endpoint)
    https://s3.us-west-000.backblazeb2.com

# Custom deployment
    https://storage.yourcompany.com
    ```
  </Step>

<Step>
    ## Verify S3 API Compatibility

Ensure your service supports the required S3 operations:

### Required Operations

* `PutObject` - Upload files
    * `GetObject` - Download files
    * `DeleteObject` - Delete files
    * `ListObjects` - List bucket contents
    * `CreateMultipartUpload` - Large file uploads

### Test API Access

<Tabs items={['curl', 'AWS CLI']}>
      <Tab value="curl">
        ```bash
        # Test basic connectivity
        curl -X GET "https://your-endpoint.com" \
          -H "Authorization: AWS ACCESS_KEY:SECRET_KEY"

# Test bucket access
        curl -X GET "https://your-endpoint.com/your-bucket" \
          -H "Authorization: AWS ACCESS_KEY:SECRET_KEY"
        ```
      </Tab>

<Tab value="AWS CLI">
        ```bash
        # Configure AWS CLI for testing
        aws configure set aws_access_key_id YOUR_ACCESS_KEY
        aws configure set aws_secret_access_key YOUR_SECRET_KEY
        aws configure set default.region us-east-1

# Test with custom endpoint
        aws s3 ls s3://your-bucket --endpoint-url https://your-endpoint.com
        ```
      </Tab>
    </Tabs>
  </Step>

<Step>
    ## Configure CORS (If Required)

Many S3-compatible services require CORS configuration for web uploads:

### Standard CORS Configuration

<Tabs items={['Generic JSON', 'MinIO/SeaweedFS' ]}>
      <Tab value="MinIO/SeaweedFS">
        ```bash
        # Using MinIO client (mc)
        mc cors set your-bucket --rule "effect=Allow&origin=*&methods=GET,PUT,POST,DELETE&headers=*"

# For production, restrict origins:
        mc cors set your-bucket --rule "effect=Allow&origin=https://yourdomain.com&methods=GET,PUT,POST,DELETE&headers=*"
        ```
      </Tab>

<Tab value="Generic JSON">
        ```json
        [
          {
            "AllowedHeaders": ["*"],
            "AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
            "AllowedOrigins": [
              "http://localhost:3000",
              "https://yourdomain.com"
            ],
            "ExposeHeaders": ["ETag", "Content-Length"],
            "MaxAgeSeconds": 3600
          }
        ]
        ```
      </Tab>
    </Tabs>
  </Step>

<Step>
    ## Configure Environment Variables

Set up your environment variables for the S3-compatible service:

<Tabs items={['Development', 'Production']}>
      <Tab value="Development">
        ```bash
        # .env.local
        S3_ENDPOINT=https://your-storage-service.com
        S3_BUCKET_NAME=your-bucket-name
        S3_ACCESS_KEY_ID=your_access_key
        S3_SECRET_ACCESS_KEY=your_secret_key
        S3_REGION=us-east-1

# Optional: Force path-style URLs (required for most self-hosted)
        S3_FORCE_PATH_STYLE=true

# Optional: Custom domain for public files
        S3_CUSTOM_DOMAIN=https://files.yourdomain.com
        ```
      </Tab>

<Tab value="Production">
        ```bash
        # Use your hosting platform's environment system
        # Never store production keys in .env files

S3_ENDPOINT=https://your-storage-service.com
        S3_BUCKET_NAME=your-bucket-name
        S3_ACCESS_KEY_ID=your_access_key
        S3_SECRET_ACCESS_KEY=your_secret_key
        S3_REGION=us-east-1
        S3_FORCE_PATH_STYLE=true
        S3_CUSTOM_DOMAIN=https://files.yourdomain.com
        ```
      </Tab>
    </Tabs>
  </Step>

<Step>
    ## Configure Custom Domain (Optional)

For better performance and branding, you can use a custom domain for your files.

### Option 1: CDN/Reverse Proxy

1. **Set up a CDN or reverse proxy** (Nginx, Cloudflare, etc.):
       ```nginx
       # Nginx configuration example
       server {
           listen 80;
           server_name files.yourdomain.com;
           
           location / {
               proxy_pass https://your-storage-service.com;
               proxy_set_header Host $host;
               proxy_set_header X-Real-IP $remote_addr;
           }
       }
       ```

2. **Add DNS Record**:
       ```bash
       # Add CNAME record in your DNS
       files.yourdomain.com -> your-cdn-or-proxy-domain.com
       ```

3. **Update Environment Variables**:
       ```bash
       # Add to your .env.local
       S3_CUSTOM_DOMAIN=https://files.yourdomain.com
       ```

### Option 2: Public Bucket with Custom Domain

If your S3-compatible service supports public buckets:

1. **Configure public access** in your storage service
    2. **Set up DNS** to point to your storage endpoint
    3. **Update environment variables** with your custom domain

<Callout type="warn">
      **Security Note**: Public buckets should only be used for non-sensitive files. Consider using presigned URLs for private content.
    </Callout>
  </Step>

<Step>
    ## Update Your Upload Configuration

Configure pushduck to use your S3-compatible service:

```typescript
    // lib/upload.ts
    import { createUploadConfig } from "pushduck/server";

export const { s3, config } = createUploadConfig()
      .provider("s3Compatible", {
        endpoint: process.env.S3_ENDPOINT!,
        bucket: process.env.S3_BUCKET_NAME!,
        accessKeyId: process.env.S3_ACCESS_KEY_ID!,
        secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
        region: process.env.S3_REGION || "us-east-1",
        // Most S3-compatible services need path-style URLs
        forcePathStyle: process.env.S3_FORCE_PATH_STYLE === "true",
        // Optional: Custom domain for file access
        customDomain: process.env.S3_CUSTOM_DOMAIN,
      })
      .defaults({
        maxFileSize: "50MB",
        acl: "public-read", // Adjust based on your needs
      })
      .build();

export { s3 };
    ```

### Advanced Configuration

```typescript
    // For services with specific requirements
    export const { s3, config } = createUploadConfig()
      .provider("s3Compatible", {
        endpoint: process.env.S3_ENDPOINT!,
        bucket: process.env.S3_BUCKET_NAME!,
        accessKeyId: process.env.S3_ACCESS_KEY_ID!,
        secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
        region: process.env.S3_REGION || "us-east-1",
        forcePathStyle: true,
      })
      .paths({
        // Organize files by service type
        prefix: "uploads",
        generateKey: (file, metadata) => {
          const date = new Date().toISOString().split('T')[0];
          const random = Math.random().toString(36).substring(2, 8);
          return `${date}/${random}/${file.name}`;
        },
      })
      .security({
        allowedOrigins: [
          process.env.FRONTEND_URL!,
          "http://localhost:3000",
        ],
      })
      .build();
    ```
  </Step>

<Step>
    ## Test Your Configuration

Verify everything works correctly:

```bash
    # Test with pushduck CLI
    npx @pushduck/cli@latest test --provider s3-compatible

# Or test manually in your app
    npm run dev
    ```

### Manual Testing

```typescript
    // Create a simple test route
    // pages/api/test-upload.ts or app/api/test-upload/route.ts

import { s3 } from '@/lib/upload';

export async function POST() {
      try {
        // Test creating an upload route
        const imageUpload = s3.image().maxFileSize("5MB");
        
        return Response.json({ 
          success: true, 
          message: "S3-compatible storage configured correctly" 
        });
      } catch (error) {
        return Response.json({ 
          success: false, 
          error: error.message 
        }, { status: 500 });
      }
    }
    ```
  </Step>
</Steps>

## You're Ready!

Your S3-compatible storage is now configured! You can now:

* ✅ **Upload files** to your custom storage service
* ✅ **Generate secure URLs** for file access
* ✅ **Use familiar S3 APIs** with any compatible service
* ✅ **Maintain vendor independence** with standard protocols

## Service-Specific Configurations

### SeaweedFS

```typescript
export const { s3, config } = createUploadConfig()
  .provider("s3Compatible", {
    endpoint: "https://seaweedfs.yourdomain.com:8333",
    bucket: "uploads",
    accessKeyId: process.env.SEAWEEDFS_ACCESS_KEY!,
    secretAccessKey: process.env.SEAWEEDFS_SECRET_KEY!,
    region: "us-east-1",
    forcePathStyle: true, // Required for SeaweedFS
  })
  .build();
```

### Garage

```typescript
export const { s3, config } = createUploadConfig()
  .provider("s3Compatible", {
    endpoint: "https://garage.yourdomain.com",
    bucket: "my-app-files",
    accessKeyId: process.env.GARAGE_ACCESS_KEY!,
    secretAccessKey: process.env.GARAGE_SECRET_KEY!,
    region: "garage", // Garage-specific region
    forcePathStyle: true,
  })
  .build();
```

### Wasabi (Alternative to dedicated provider)

```typescript
export const { s3, config } = createUploadConfig()
  .provider("s3Compatible", {
    endpoint: "https://s3.wasabisys.com",
    bucket: "my-wasabi-bucket",
    accessKeyId: process.env.WASABI_ACCESS_KEY!,
    secretAccessKey: process.env.WASABI_SECRET_KEY!,
    region: "us-east-1",
    forcePathStyle: false, // Wasabi supports virtual-hosted style
  })
  .build();
```

### Backblaze B2 (S3-Compatible API)

```typescript
export const { s3, config } = createUploadConfig()
  .provider("s3Compatible", {
    endpoint: "https://s3.us-west-000.backblazeb2.com",
    bucket: "my-b2-bucket",
    accessKeyId: process.env.B2_ACCESS_KEY!,
    secretAccessKey: process.env.B2_SECRET_KEY!,
    region: "us-west-000",
    forcePathStyle: false,
  })
  .build();
```

## Security Best Practices

### Access Control

```typescript
// Implement user-based access control
.middleware(async ({ req, file }) => {
  const user = await authenticate(req);
  
  // Create user-specific paths
  const userPath = `users/${user.id}`;
  
  return {
    userId: user.id,
    keyPrefix: userPath,
    metadata: {
      uploadedBy: user.id,
      uploadedAt: new Date().toISOString(),
    }
  };
})
```

### Bucket Policies

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::your-bucket/public/*"
    },
    {
      "Effect": "Deny",
      "Principal": "*",
      "Action": "s3:GetObject", 
      "Resource": "arn:aws:s3:::your-bucket/private/*"
    }
  ]
}
```

### Environment Security

```typescript
// Validate configuration at startup
const validateConfig = () => {
  const required = [
    'S3_ENDPOINT',
    'S3_BUCKET_NAME', 
    'S3_ACCESS_KEY_ID',
    'S3_SECRET_ACCESS_KEY'
  ];
  
  for (const key of required) {
    if (!process.env[key]) {
      throw new Error(`Missing required environment variable: ${key}`);
    }
  }
};

validateConfig();
```

## Monitoring & Analytics

### Health Monitoring

```typescript
// Monitor storage service health
.hooks({
  onUploadStart: async ({ file }) => {
    // Check service availability
    const isHealthy = await checkStorageHealth();
    if (!isHealthy) {
      throw new Error("Storage service unavailable");
    }
  },
  onUploadComplete: async ({ file, metadata }) => {
    // Track successful uploads
    await analytics.track("upload_completed", {
      provider: "s3-compatible",
      service: process.env.S3_ENDPOINT,
      fileSize: file.size,
      duration: metadata.uploadTime,
    });
  }
})

async function checkStorageHealth(): Promise<boolean> {
  try {
    const response = await fetch(`${process.env.S3_ENDPOINT}/health`);
    return response.ok;
  } catch {
    return false;
  }
}
```

### Usage Analytics

```typescript
// Track storage usage patterns
const getStorageMetrics = async () => {
  try {
    // Use your service's API to get metrics
    const metrics = await fetch(`${process.env.S3_ENDPOINT}/metrics`, {
      headers: {
        'Authorization': `Bearer ${process.env.S3_ACCESS_KEY_ID}`,
      }
    });
    
    return await metrics.json();
  } catch (error) {
    console.error("Failed to fetch storage metrics:", error);
    return null;
  }
};
```

## Performance Optimization

### Connection Pooling

```typescript
// Optimize for high throughput
export const { s3, config } = createUploadConfig()
  .provider("s3Compatible", {
    // ... config
    maxRetries: 3,
    retryDelayOptions: {
      base: 300,
      customBackoff: (retryCount) => Math.pow(2, retryCount) * 100,
    },
    timeout: 60000,
  })
  .build();
```

### Parallel Uploads

```typescript
// Enable multipart uploads for large files
.defaults({
  maxFileSize: "100MB",
  // Configure multipart threshold
  multipartUploadThreshold: "25MB",
  multipartUploadSize: "5MB",
})
```

## 🆘 Common Issues

### Connection Issues

**Certificate errors?** → Add SSL certificate or use `NODE_TLS_REJECT_UNAUTHORIZED=0` for development\
**Connection refused?** → Verify endpoint URL and port are correct\
**Timeout errors?** → Increase timeout settings or check network connectivity

### Authentication Issues

**Access denied?** → Verify access keys and bucket permissions\
**Invalid signature?** → Check secret key and ensure clock synchronization\
**Region mismatch?** → Verify the region setting matches your service

### Upload Issues

**CORS errors?** → Configure CORS policy on your storage service. For detailed CORS configuration, see the [CORS & ACL Configuration Guide](/docs/guides/security/cors-and-acl).\
**File size errors?** → Check service limits and adjust `maxFileSize`\
**Path errors?** → Enable `forcePathStyle: true` for most self-hosted services

### Debugging Commands

```bash
# Test connectivity
curl -v "https://your-endpoint.com/your-bucket"

# Check bucket contents
aws s3 ls s3://your-bucket --endpoint-url https://your-endpoint.com

# Test upload
aws s3 cp test.txt s3://your-bucket/ --endpoint-url https://your-endpoint.com
```

## Use Cases

### Self-Hosted Solutions

* **Data sovereignty** requirements
* **Air-gapped** environments
* **Custom compliance** needs
* **Cost optimization** for high usage

### Hybrid Cloud

* **Multi-cloud** strategies
* **Disaster recovery** setups
* **Geographic distribution**
* **Vendor diversification**

### Development & Testing

* **Local development** without cloud dependencies
* **CI/CD pipelines** with custom storage
* **Testing environments** with controlled data

***

**Next:** [Upload Your First Image](/docs/guides/image-uploads) or explore [Configuration Options](/docs/api/configuration/upload-config)

# createUploadClient (/docs/api/client/create-upload-client)

import { Callout } from "fumadocs-ui/components/callout";
import { Card, Cards } from "fumadocs-ui/components/card";
import { Tab, Tabs } from "fumadocs-ui/components/tabs";
import { Steps, Step } from "fumadocs-ui/components/steps";
import { TypeTable } from "fumadocs-ui/components/type-table";

## createUploadClient Function

Create a type-safe upload client with **property-based access** and optional **per-route configuration**. This is the recommended approach for most projects.

<Callout type="success">
  **Enhanced in v2.0**: Now supports per-route callbacks, progress tracking, and error handling while maintaining superior type safety.
</Callout>

## Why Use This Approach?

* 🏆 **Superior Type Safety** - Route names validated at compile time
* 🎯 **Property-Based Access** - No string literals, full IntelliSense
* ⚡ **Per-Route Configuration** - Callbacks, endpoints, and options per route
* 🔄 **Centralized Setup** - Single configuration for all routes
* 🛡️ **Refactoring Safety** - Rename routes safely across codebase

This utility function provides property-based access to your upload routes. You can also use the `useUploadRoute<AppRouter>()` hook if you prefer traditional React patterns.

## Basic Setup

<Steps>
  <Step>
    **Create the upload client**

```typescript title="lib/upload-client.ts"
    import { createUploadClient } from 'pushduck/client'
    import type { AppRouter } from './upload'

export const upload = createUploadClient<AppRouter>({
      endpoint: '/api/upload' // [!code highlight]
    })
    ```
  </Step>

<Step>
    **Use in components**

```typescript title="components/upload-form.tsx"
    import { upload } from '@/lib/upload-client'

export function UploadForm() {
      const { uploadFiles, files, isUploading } = upload.imageUpload() // [!code highlight]
      
      return (
        <input 
          type="file" 
          onChange={(e) => uploadFiles(Array.from(e.target.files || []))} // [!code highlight]
          disabled={isUploading}
        />
      )
    }
    ```
  </Step>
</Steps>

## Configuration Options

<TypeTable
  type={{
  endpoint: {
    description: "Base API endpoint for upload routes",
    type: "string",
    required: true,
  },
  defaultOptions: {
    description: "Global default options applied to all routes",
    type: "RouteUploadOptions",
  },
  fetcher: {
    description: "Custom fetch function for requests",
    type: "(input: RequestInfo, init?: RequestInit) => Promise<Response>",
  },
}}
/>

## Per-Route Configuration

Each route method now accepts optional configuration:

<TypeTable
  type={{
  onSuccess: {
    description: "Callback when uploads complete successfully",
    type: "(results: UploadResult[]) => void",
  },
  onError: {
    description: "Callback when upload fails",
    type: "(error: Error) => void",
  },
  onProgress: {
    description: "Callback for progress updates",
    type: "(progress: number) => void",
  },
  endpoint: {
    description: "Override endpoint for this specific route",
    type: "string",
  },
}}
/>

## Examples

<CodeBlockTabs defaultValue="Basic Usage">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Basic Usage">
      Basic Usage
    </CodeBlockTabsTrigger>

<CodeBlockTabsTrigger value="With Metadata">
      With Metadata
    </CodeBlockTabsTrigger>

<CodeBlockTabsTrigger value="With Callbacks">
      With Callbacks
    </CodeBlockTabsTrigger>

<CodeBlockTabsTrigger value="Multiple Routes">
      Multiple Routes
    </CodeBlockTabsTrigger>

<CodeBlockTabsTrigger value="Global + Per-Route">
      Global + Per-Route
    </CodeBlockTabsTrigger>

<CodeBlockTabsTrigger value="Advanced Config">
      Advanced Config
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

<CodeBlockTab value="Basic Usage">
    ```typescript
    import { upload } from '@/lib/upload-client'

export function BasicUpload() {
      // Simple usage - no configuration needed
      const { uploadFiles, files, isUploading, reset } = upload.imageUpload()

return (
        <div>
          <input 
            type="file"
            accept="image/*"
            onChange={(e) => uploadFiles(Array.from(e.target.files || []))}
            disabled={isUploading}
          />
          
          {files.map(file => (
            <div key={file.id}>
              <span>{file.name}</span>
              <progress value={file.progress} max={100} />
              {file.status === 'success' && <span>✅</span>}
            </div>
          ))}
          
          <button onClick={reset}>Reset</button>
        </div>
      )
    }
    ```
  </CodeBlockTab>

<CodeBlockTab value="With Metadata">
    ```typescript
    import { upload } from '@/lib/upload-client'
    import { useState } from 'react'

export function MetadataUpload() {
      const [selectedAlbum, setSelectedAlbum] = useState('vacation-2025');
      const [tags, setTags] = useState<string[]>([]);
      
      const { uploadFiles, files } = upload.imageUpload({
        onSuccess: (results) => {
          console.log(`Uploaded ${results.length} images to album:`, selectedAlbum);
        }
      });
      
      const handleUpload = (e: React.ChangeEvent<HTMLInputElement>) => {
        const selectedFiles = Array.from(e.target.files || []);
        
        // Pass client-side context as metadata
        uploadFiles(selectedFiles, {
          albumId: selectedAlbum,
          tags: tags,
          visibility: 'private',
          uploadSource: 'web-app',
          timestamp: Date.now()
        });
      };
      
      return (
        <div>
          <div className="controls">
            <select 
              value={selectedAlbum} 
              onChange={(e) => setSelectedAlbum(e.target.value)}
            >
              <option value="vacation-2025">Vacation 2025</option>
              <option value="family">Family Photos</option>
              <option value="work">Work Events</option>
            </select>
            
            <input
              type="text"
              placeholder="Add tags (comma separated)"
              onChange={(e) => setTags(e.target.value.split(',').map(t => t.trim()))}
            />
          </div>
          
          <input
            type="file"
            multiple
            accept="image/*"
            onChange={handleUpload}
          />
          
          {files.map(file => (
            <div key={file.id}>
              <span>{file.name}</span>
              <progress value={file.progress} max={100} />
              {file.status === 'success' && <span>✅</span>}
            </div>
          ))}
        </div>
      );
    }
    ```
  </CodeBlockTab>

<CodeBlockTab value="With Callbacks">
    ```typescript
    import { upload } from '@/lib/upload-client'
    import { toast } from 'sonner'

export function CallbackUpload() {
      const [progress, setProgress] = useState(0)
      
      const { uploadFiles, files, isUploading } = upload.imageUpload({
        onSuccess: (results) => {
          toast.success(`✅ Uploaded ${results.length} images!`)
          console.log('Upload results:', results)
        },
        onError: (error) => {
          toast.error(`❌ Upload failed: ${error.message}`)
          console.error('Upload error:', error)
        },
        onProgress: (progress) => {
          setProgress(progress)
          console.log(`📊 Progress: ${progress}%`)
        }
      })

return (
        <div>
          <input 
            type="file"
            multiple
            accept="image/*"
            onChange={(e) => uploadFiles(Array.from(e.target.files || []))}
          />
          
          {progress > 0 && (
            <div>
              <progress value={progress} max={100} />
              <span>{progress}% complete</span>
            </div>
          )}
        </div>
      )
    }
    ```
  </CodeBlockTab>

<CodeBlockTab value="Multiple Routes">
    ```typescript
    import { upload } from '@/lib/upload-client'

export function MultiUploadForm() {
      // Different configuration for each upload type
      const images = upload.imageUpload({
        onSuccess: (results) => {
          // Store images with both permanent and temporary URLs
          updateImageGallery(results.map(file => ({
            id: file.id,
            url: file.url,                    // Permanent access URL
            downloadUrl: file.presignedUrl,   // Temporary download URL (1 hour)
            name: file.name,
            key: file.key
          })));
        }
      })
      
      const documents = upload.documentUpload({
        onSuccess: (results) => {
          // Store documents with metadata
          updateDocumentLibrary(results.map(file => ({
            id: file.id,
            url: file.url,
            name: file.name,
            size: file.size,
            uploadedAt: new Date().toISOString()
          })));
        }
      })

return (
        <div>
          <section>
            <h3>Images</h3>
            <FileUploadSection {...images} accept="image/*" />
          </section>
          
          <section>
            <h3>Documents</h3>
            <FileUploadSection {...documents} accept=".pdf,.doc,.docx" />
          </section>
        </div>
      )
    }
    ```
  </CodeBlockTab>

<CodeBlockTab value="Global + Per-Route">
    ```typescript
    // Global configuration with per-route overrides
    const upload = createUploadClient<AppRouter>({
      endpoint: '/api/upload',
      
      // These apply to all routes by default
      defaultOptions: {
        onProgress: (progress) => updateGlobalProgress(progress),
        onError: (error) => logError(error)
      }
    })

export function MixedConfigUpload() {
      // Inherits global onProgress and onError
      const basic = upload.imageUpload()
      
      // Overrides global settings + adds success handler
      const premium = upload.documentUpload({
        endpoint: '/api/premium-upload', // Different endpoint
        onSuccess: (results) => {
          // This overrides global behavior
          handlePremiumUpload(results)
        }
        // Still inherits global onProgress and onError
      })

return (
        <div>
          <FileUploader {...basic} label="Basic Images" />
          <FileUploader {...premium} label="Premium Documents" />
        </div>
      )
    }
    ```
  </CodeBlockTab>

<CodeBlockTab value="Advanced Config">
    ```typescript
    const upload = createUploadClient<AppRouter>({
      endpoint: '/api/upload',
      
      // Custom fetch function
      fetcher: async (input, init) => {
        const token = await getAuthToken()
        return fetch(input, {
          ...init,
          headers: {
            ...init?.headers,
            'Authorization': `Bearer ${token}`
          }
        })
      },
      
      defaultOptions: {
        onError: (error) => {
          // Global error tracking
          analytics.track('upload_error', { error: error.message })
          toast.error('Upload failed. Please try again.')
        }
      }
    })

export function AdvancedUpload() {
      const { uploadFiles, files } = upload.secureUpload({
        endpoint: '/api/secure-upload',
        onSuccess: (results) => {
          // Audit log for secure uploads
          auditLog('secure_upload_success', {
            files: results.length,
            user: user.id
          })
        }
      })
      
      // Handle permissions in component logic
      const handleUpload = (files: File[]) => {
        if (user.hasPermission('upload')) {
          uploadFiles(files)
        } else {
          toast.error('You don\'t have permission to upload files')
        }
      }

return <SecureFileUploader {...{ uploadFiles, files }} />
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Type Safety Benefits

The structured client provides superior TypeScript integration:

```typescript
const upload = createUploadClient<AppRouter>({ endpoint: '/api/upload' })

// ✅ IntelliSense shows available routes
upload.imageUpload()      // Autocomplete suggests this
upload.documentUpload()   // And this
upload.videoUpload()      // And this

// ❌ TypeScript error for non-existent routes
upload.invalidRoute()     // Error: Property 'invalidRoute' does not exist

// ✅ Route rename safety
// If you rename 'imageUpload' to 'photoUpload' in your router,
// TypeScript will show errors everywhere it's used, making refactoring safe

// ✅ Callback type inference
upload.imageUpload({
  onSuccess: (results) => {
    // `results` is fully typed based on your router configuration
    results.forEach(result => {
      console.log(result.url)  // TypeScript knows this exists
      console.log(result.key)  // And this
    })
  }
})
```

## Comparison with Hooks

| Feature          | Enhanced Structured Client        | Hook-Based             |
| ---------------- | --------------------------------- | ---------------------- |
| Type Safety      | ✅ **Superior** - Property-based   | ✅ Good - Generic types |
| IntelliSense     | ✅ **Full route autocomplete**     | ⚠️ String-based routes |
| Refactoring      | ✅ **Safe rename across codebase** | ⚠️ Manual find/replace |
| Callbacks        | ✅ **Full support**                | ✅ Full support         |
| Per-route Config | ✅ **Full support**                | ✅ Full support         |
| Bundle Size      | ✅ **Same**                        | ✅ Same                 |
| Performance      | ✅ **Identical**                   | ✅ Identical            |

## Migration from Hooks

Easy migration from hook-based approach:

```typescript
// Before: Hook-based
import { useUploadRoute } from 'pushduck/client'

const { uploadFiles, files } = useUploadRoute<AppRouter>('imageUpload', {
  onSuccess: handleSuccess,
  onError: handleError
})

// After: Enhanced structured client
import { upload } from '@/lib/upload-client'

const { uploadFiles, files } = upload.imageUpload({
  onSuccess: handleSuccess,
  onError: handleError
})
```

Benefits of migration:

* 🎯 **Better type safety** - Route names validated at compile time
* 🔍 **Enhanced IntelliSense** - Autocomplete for all routes
* 🏗️ **Centralized config** - Single place for endpoint and defaults
* 🛡️ **Refactoring safety** - Rename routes safely
* ⚡ **Same performance** - Zero runtime overhead

***

<Callout type="success">
  **Recommended Approach**: Use `createUploadClient` for the best developer experience with full flexibility and type safety.
</Callout>

# Client API (/docs/api/client)

import { Card, Cards } from "fumadocs-ui/components/card";
import { Callout } from "fumadocs-ui/components/callout";

## Client API Overview

Pushduck provides two powerful client-side approaches for handling file uploads: **useUploadRoute hook** for reactive state management and **Property-Based Client** for enhanced type safety and modern developer experience.

<Callout type="info">
  All hooks follow React's rules of hooks - call them only from React function components or custom hooks, not from regular JavaScript functions.
</Callout>

## Available APIs

<Cards>
  <Card title="createUploadClient (Property-Based)" description="Modern property-based client with enhanced type safety and developer experience" href="/docs/api/client/create-upload-client">
    * Enhanced type safety with IntelliSense
    * Property-based access (`client.imageUpload()` returns hook)
    * Built-in progress tracking and error handling
    * Modern developer experience

**Perfect for**: New projects, enhanced type safety, modern React patterns
  </Card>

<Card title="useUploadRoute" description="Route-specific uploads with enhanced validation and type safety" href="/docs/api/client/use-upload-route">
    * Route-specific validation
    * Enhanced type inference
    * Multi-file support with progress tracking
    * Advanced configuration and callbacks
    * Reactive state management

**Perfect for**: All upload scenarios, the main React hook for uploads
  </Card>
</Cards>

## Quick Comparison

| Feature                  | `createUploadClient`             | `useUploadRoute`        |
| ------------------------ | -------------------------------- | ----------------------- |
| **Approach**             | 🔧 Property-based                | ⚛️ React Hook           |
| **Type Safety**          | ✅ Excellent (IntelliSense)       | ✅ Excellent             |
| **Developer Experience** | ✅ Modern                         | ✅ Advanced              |
| **Simplicity**           | ✅ Intuitive                      | ✅ Straightforward       |
| **Validation**           | ✅ Enhanced                       | ✅ Advanced              |
| **Multi-route**          | ✅ Multiple routes                | ✅ Single route per hook |
| **Progress Tracking**    | ✅ Built-in                       | ✅ Built-in              |
| **Error Handling**       | ✅ Enhanced                       | ✅ Comprehensive         |
| **Best For**             | 🆕 New projects, modern patterns | 🔧 All upload scenarios |

## Basic Usage Examples

### createUploadClient (Property-Based)

```typescript
import { createUploadClient } from 'pushduck/client';

const client = createUploadClient<AppRouter>({
  endpoint: '/api/upload',
});

### useUploadRoute Hook

```typescript
import { useUploadRoute } from 'pushduck/client';

function AdvancedUpload() {
  const { 
    uploadFiles, 
    files, 
    isUploading, 
    progress, 
    errors 
  } = useUploadRoute('imageUpload', {
    endpoint: '/api/upload',
    onSuccess: (results) => console.log('Upload successful!', results),
    onError: (error) => console.error('Upload failed:', error),
  });

const handleFileSelect = async (selectedFiles: File[]) => {
    await uploadFiles(selectedFiles);
  };

return (
    <div>
      <input 
        type="file" 
        multiple
        onChange={(e) => e.target.files && handleFileSelect(Array.from(e.target.files))}
        disabled={isUploading}
      />
      {isUploading && <div>Progress: {progress}%</div>}
      {errors.length > 0 && <div>Errors: {errors.join(', ')}</div>}
      <div>Uploaded files: {files.filter(f => f.status === 'success').length}</div>
    </div>
  );
}
```

## Hook Features

### State Management

Both approaches provide reactive state management:

```typescript
// useUploadRoute returns:
const { 
  uploadFiles,  // Function to start upload
  files,        // Array of uploaded files with status
  isUploading,  // Boolean: upload in progress
  progress,     // Number: overall progress (0-100)
  errors,       // Array of error messages
  reset,        // Function to reset state
  uploadSpeed,  // Current upload speed (bytes/sec)
  eta           // Estimated time remaining (seconds)
} = useUploadRoute('routeName', config);
```

### Progress Tracking

Real-time progress updates during file uploads:

```typescript
// Progress updates automatically during upload
{isUploading && (
  <div className="progress-bar">
    <div 
      className="progress-fill" 
      style={{ width: `${progress}%` }}
    />
    <span>{progress}% uploaded</span>
    <span>Speed: {formatUploadSpeed(uploadSpeed)}</span>
    <span>ETA: {formatETA(eta)}</span>
  </div>
)}
```

### Error Handling

Comprehensive error handling with detailed messages:

```typescript
{errors.length > 0 && (
  <div className="error-messages">
    {errors.map((error, index) => (
      <div key={index} className="error-message">
        {error}
      </div>
    ))}
  </div>
)}
```

## Configuration Options

### Common Options

Both approaches support these configuration options:

```typescript
const config = {
  endpoint: '/api/upload',           // Upload endpoint (default: '/api/s3-upload')
  onStart: (files) => {},            // Called when upload starts
  onProgress: (progress) => {},      // Progress callback (0-100)
  onSuccess: (results) => {},        // Success callback with file results
  onError: (error) => {},            // Error callback
};
```

### useUploadRoute Specific Options

```typescript
const routeConfig = {
  // All common options plus:
  endpoint: '/api/upload',           // Route-specific endpoint
  metadata: { userId: '123' },       // Upload metadata
};
```

## Best Practices

<Callout type="tip">
  **Performance**: Use `createUploadClient` for multiple upload types in the same component. Use `useUploadRoute` directly for single-purpose upload components.
</Callout>

<Callout type="warn">
  **File Validation**: Always validate files on both client and server. Client validation provides immediate feedback, server validation ensures security.
</Callout>

<Callout type="info">
  **Error Recovery**: Both approaches include built-in retry logic for network errors and provide clear error messages for validation failures.
</Callout>

## Next Steps

1. **Property-based client?** → Start with [createUploadClient](/docs/api/client/create-upload-client)
2. **Direct hook usage?** → Use [useUploadRoute](/docs/api/client/use-upload-route)
3. **Complete examples?** → Check [examples documentation](/docs/examples)
4. **Server setup?** → See [server configuration](/docs/api/s3-router)

# useUploadRoute (/docs/api/client/use-upload-route)

import { Callout } from "fumadocs-ui/components/callout";
import { TypeTable } from "fumadocs-ui/components/type-table";
import { Tab, Tabs } from "fumadocs-ui/components/tabs";
import { formatETA, formatUploadSpeed } from "pushduck";

## useUploadRoute Hook

A React hook that provides reactive state management for file uploads with progress tracking and error handling.

<Callout type="info">
  This hook follows familiar React patterns and is perfect for teams that prefer
  the traditional hook-based approach. Both this and `createUploadClient` are equally valid ways to handle uploads.
</Callout>

## When to Use This Hook

Use `useUploadRoute` when:

* 🪝 **Prefer React hooks** - familiar pattern for React developers
* 🧩 **Granular control** needed over individual upload state
* 🔄 **Component-level state** management preferred
* 👥 **Team preference** for hook-based patterns

## Alternative Approach

You can also use the structured client approach:

```typescript title="Hook-based approach"
// Hook-based approach
import { useUploadRoute } from 'pushduck/client'

const { uploadFiles, files } = useUploadRoute<AppRouter>('imageUpload') // [!code highlight]
```

```typescript title="Structured client approach"
// Structured client approach
import { createUploadClient } from 'pushduck/client'

const upload = createUploadClient<AppRouter>({
  endpoint: '/api/upload' // [!code highlight]
})

const { uploadFiles, files } = upload.imageUpload() // [!code highlight]
```

Both approaches provide the same functionality and type safety - choose what feels more natural for your team.

## Basic Usage

```typescript title="Basic Usage Example"
import { useUploadRoute } from "pushduck/client";
import { formatETA, formatUploadSpeed } from "pushduck";
import type { AppRouter } from "@/lib/upload";

export function ImageUploader() {
  // With type parameter (recommended for better type safety)
  const { uploadFiles, files, isUploading, error, reset, progress, uploadSpeed, eta } =
    useUploadRoute<AppRouter>("imageUpload"); // [!code highlight]

const handleFileSelect = (e: React.ChangeEvent<HTMLInputElement>) => {
    const selectedFiles = Array.from(e.target.files || []);
    uploadFiles(selectedFiles); // [!code highlight]
  };

return (
    <div>
      <input
        type="file"
        multiple
        accept="image/*"
        onChange={handleFileSelect}
      />

{/* Overall Progress Tracking */}
      {isUploading && files.length > 1 && progress !== undefined && (
        <div className="overall-progress">
          <h3>Overall Progress: {Math.round(progress)}%</h3>
          <progress value={progress} max={100} />
          <div>
            <span>Speed: {uploadSpeed ? formatUploadSpeed(uploadSpeed) : '0 B/s'}</span>
            <span>ETA: {eta ? formatETA(eta) : '--'}</span>
          </div>
        </div>
      )}

{/* Individual File Progress */}
      {files.map((file) => (
        <div key={file.id}>
          <span>{file.name}</span>
          <progress value={file.progress} max={100} />
          {file.status === "success" && <a href={file.url}>View</a>} // [!code highlight]
        </div>
      ))}

{error && <div className="error">{error.message}</div>}
      <button onClick={reset}>Reset</button>
    </div>
  );
}
```

## Overall Progress Tracking

The hook provides real-time overall progress metrics when uploading multiple files:

<Callout type="info">
  Overall progress tracking is especially useful for batch uploads and provides a better user experience when uploading multiple files simultaneously.
</Callout>

```typescript
const { progress, uploadSpeed, eta } = useUploadRoute("imageUpload");

// Progress: 0-100 percentage across all files
console.log(`Overall progress: ${progress}%`);

// Upload speed: Combined transfer rate in bytes/second
console.log(`Transfer rate: ${formatUploadSpeed(uploadSpeed)}`);

// ETA: Time remaining in seconds
console.log(`Time remaining: ${formatETA(eta)}`);
```

### Progress Calculation

* **progress**: Weighted by file sizes, not just file count
* **uploadSpeed**: Sum of all active file upload speeds
* **eta**: Calculated based on remaining bytes and current speed
* Values are `undefined` when no uploads are active

## Hook Signature

```typescript
// With type parameter (recommended)
function useUploadRoute<TRouter>(
  route: keyof TRouter,
  options?: UseUploadOptions
): UseUploadReturn;

// Without type parameter (also works)
function useUploadRoute(
  route: string,
  options?: UseUploadOptions
): UseUploadReturn;
```

## Parameters

### Type Parameter Benefits

```typescript
// ✅ With type parameter - better type safety
const { uploadFiles } = useUploadRoute<AppRouter>("imageUpload");
// - Route names are validated at compile time
// - IntelliSense shows available routes
// - Typos caught during development

// ✅ Without type parameter - still works
const { uploadFiles } = useUploadRoute("imageUpload");
// - Works with any string
// - Less type safety but more flexible
// - Good for dynamic route names
```

## Options

<TypeTable
  type={{
  onStart: {
    description: "Callback when upload process begins (after validation)",
    type: "(files: S3FileMetadata[]) => void",
  },
  onSuccess: {
    description: "Callback when uploads complete successfully",
    type: "(results: UploadResult[]) => void",
  },
  onError: {
    description: "Callback when upload fails",
    type: "(error: UploadError) => void",
  },
  onProgress: {
    description: "Callback for progress updates",
    type: "(progress: number) => void",
  },
}}
/>

## Return Value

<TypeTable
  type={{
  uploadFiles: {
    description: "Function to upload files",
    type: "(files: File[]) => Promise<UploadResult[]>",
  },
  files: {
    description: "Array of files with upload status",
    type: "UploadFile[]",
  },
  isUploading: {
    description: "Whether any upload is in progress",
    type: "boolean",
  },
  uploadedFiles: {
    description: "Successfully uploaded files",
    type: "UploadResult[]",
  },
  error: {
    description: "Upload error if any",
    type: "UploadError | null",
  },
  reset: {
    description: "Reset upload state",
    type: "() => void",
  },
  progress: {
    description: "Overall progress across all files (0-100)",
    type: "number | undefined",
  },
  uploadSpeed: {
    description: "Combined transfer rate in bytes per second",
    type: "number | undefined",
  },
  eta: {
    description: "Overall time remaining in seconds",
    type: "number | undefined",
  },
}}
/>

## Callback Execution Order

The callbacks follow a predictable order to provide clear upload lifecycle management:

<Callout type="info">
  **Proper Callback Sequence:** `onStart` → `onProgress(0)` → `onProgress(n)` → `onSuccess/onError`
</Callout>

```typescript
const { uploadFiles } = useUploadRoute<AppRouter>('imageUpload', {
  // 1. Called first after validation passes
  onStart: (files) => {
    console.log('Upload starting for', files.length, 'files');
    setUploading(true);
  },
  
  // 2. Called with progress updates (0-100)
  onProgress: (progress) => {
    console.log('📊 Progress:', progress + '%');
    setProgress(progress);
  },
  
  // 3. Called on completion
  onSuccess: (results) => {
    console.log('✅ Upload complete!');
    results.forEach(file => {
      console.log('File URL:', file.url);                // Permanent URL
      console.log('Download URL:', file.presignedUrl);   // Temporary access (1 hour)
    });
    setUploading(false);
  },
  
  // OR 3. Called on error (no progress callbacks for validation errors)
  onError: (error) => {
    console.log('❌ Upload failed:', error.message);
    setUploading(false);
  }
});
```

### Validation Errors vs Upload Errors

* **Validation errors** (size limits, file types): Only `onError` is called
* **Upload errors** (network issues): `onStart` → `onProgress(0)` → `onError`

## Upload Result Structure

Each successfully uploaded file includes the following properties:

### URL Usage Examples

```typescript
const { uploadFiles } = useUploadRoute('fileUpload', {
  onSuccess: (results) => {
    results.forEach(file => {
      // Use permanent URL for public files
      if (file.url) {
        console.log('Public URL:', file.url);
      }
      
      // Use presigned URL for private files or temporary access
      if (file.presignedUrl) {
        console.log('Download URL:', file.presignedUrl);
        // This URL expires in 1 hour and can be used for secure downloads
      }
    });
  }
});
```

## Advanced Examples

<CodeBlockTabs defaultValue="With All Callbacks">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="With All Callbacks">
      With All Callbacks
    </CodeBlockTabsTrigger>

<CodeBlockTabsTrigger value="With Metadata">
      With Metadata
    </CodeBlockTabsTrigger>

<CodeBlockTabsTrigger value="Multiple Routes">
      Multiple Routes
    </CodeBlockTabsTrigger>

<CodeBlockTabsTrigger value="Form Integration">
      Form Integration
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

<CodeBlockTab value="With All Callbacks">
    ```typescript
    const { uploadFiles, files } = useUploadRoute<AppRouter>('documentUpload', {
      onStart: (files) => {
        toast.info(`Starting upload of ${files.length} files...`);
        setUploadStarted(true);
      },
      onSuccess: (results) => {
        toast.success(`Uploaded ${results.length} files`);
        // Store both permanent and temporary URLs
        updateDocuments(results.map(file => ({
          url: file.url,                    // Permanent access
          downloadUrl: file.presignedUrl,   // Temporary access (1 hour)
          name: file.name,
          key: file.key
        })));
        setUploadStarted(false);
      },
      onError: (error) => {
        toast.error(`Upload failed: ${error.message}`);
        setUploadStarted(false);
      },
      onProgress: (progress) => {
        setGlobalProgress(progress);
      }
    })
    ```
  </CodeBlockTab>

<CodeBlockTab value="With Metadata">
    ```typescript
    import { useUploadRoute } from 'pushduck/client'
    import type { AppRouter } from '@/lib/upload'
    import { useState } from 'react'

export function ProductImageUpload({ productId }: { productId: string }) {
      const [imageType, setImageType] = useState<'main' | 'gallery' | 'thumbnail'>('gallery');
      const [sortOrder, setSortOrder] = useState(1);
      
      const { uploadFiles, files, isUploading } = useUploadRoute<AppRouter>('productImages', {
        onSuccess: (results) => {
          toast.success(`Uploaded ${results.length} ${imageType} images for product`);
          // Update product in database with new image URLs
          updateProduct(productId, results);
        }
      });
      
      const handleUpload = (selectedFiles: File[]) => {
        // Send product context to server via metadata
        uploadFiles(selectedFiles, {
          productId: productId,
          imageType: imageType,
          sortOrder: sortOrder,
          category: 'product-media',
          uploadedFrom: 'admin-dashboard'
        });
      };
      
      return (
        <div>
          <div className="metadata-controls">
            <label>
              Image Type:
              <select 
                value={imageType} 
                onChange={(e) => setImageType(e.target.value as any)}
              >
                <option value="main">Main Product Image</option>
                <option value="gallery">Gallery Image</option>
                <option value="thumbnail">Thumbnail</option>
              </select>
            </label>
            
            <label>
              Sort Order:
              <input
                type="number"
                value={sortOrder}
                onChange={(e) => setSortOrder(parseInt(e.target.value))}
                min="1"
              />
            </label>
          </div>
          
          <input
            type="file"
            multiple
            accept="image/*"
            onChange={(e) => e.target.files && handleUpload(Array.from(e.target.files))}
            disabled={isUploading}
          />
          
          {files.map(file => (
            <div key={file.id}>
              <span>{file.name}</span>
              <span>Type: {imageType}</span>
              <span>Order: {sortOrder}</span>
              {file.status === 'success' && <img src={file.url} alt={file.name} width={100} />}
            </div>
          ))}
        </div>
      );
    }
    ```
  </CodeBlockTab>

<CodeBlockTab value="Multiple Routes">
    ```typescript
    const images = useUploadRoute<AppRouter>('imageUpload')
    const documents = useUploadRoute<AppRouter>('documentUpload')

return (
      <div>
        <FileUploadSection {...images} accept="image/*" />
        <FileUploadSection {...documents} accept=".pdf,.doc" />
      </div>
    )
    ```
  </CodeBlockTab>

<CodeBlockTab value="Form Integration">
    ```typescript
    const { uploadFiles, uploadedFiles } = useUploadRoute<AppRouter>('attachments', {
      onSuccess: (results) => {
        setValue('attachments', results.map(r => r.url))
      }
    })

const onSubmit = (data) => {
      // Form data includes uploaded file URLs
      console.log(data.attachments)
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

***

<Callout type="success">
  **Flexible API:** Use this hook when you prefer React's familiar hook patterns
  or need more granular control over upload state.
</Callout>

# Client Configuration (/docs/api/configuration/client-options)

## Client Setup Options

The upload client provides multiple APIs to suit different needs: **property-based access** for enhanced type safety, and **hook-based access** for familiar React patterns.

<Callout type="info">
  This guide focuses on the **enhanced client API** with property-based access.
  This provides the best developer experience with full TypeScript inference and
  eliminates string literals.
</Callout>

## Client Setup Structure

Organize your client configuration for maximum reusability:

## Basic Client Configuration

<Steps>
  <Step>
    **Import your router types**

Start by importing the router type from your server configuration:

```typescript title="lib/upload-client.ts"
    import { createUploadClient } from 'pushduck/client'
    import type { AppRouter } from './upload'

export const upload = createUploadClient<AppRouter>({
      endpoint: '/api/upload'
    })
    ```
  </Step>

<Step>
    **Use property-based access**

Access your upload endpoints as properties with full type safety:

```typescript title="components/upload-form.tsx"
    import { upload } from '@/lib/upload-client'

export function ImageUploadForm() {
      const { uploadFiles, files, isUploading, error } = upload.imageUpload
      //           ^ Full TypeScript inference from your server router

const handleUpload = async (selectedFiles: File[]) => {
        await uploadFiles(selectedFiles)
      }

return (
        <div>
          <input type="file" onChange={(e) => handleUpload(Array.from(e.target.files || []))} />
          {files.map(file => (
            <div key={file.id}>
              <span>{file.name}</span>
              <span>{file.status}</span> {/* 'pending' | 'uploading' | 'success' | 'error' */}
              <progress value={file.progress} max={100} />
              {file.url && <a href={file.url}>View</a>}
            </div>
          ))}
        </div>
      )
    }
    ```
  </Step>

<Step>
    **Handle upload results**

Process upload results with full type safety:

```typescript
    const { uploadFiles, files, reset } = upload.documentUpload

const handleDocumentUpload = async (files: File[]) => {
      try {
        const results = await uploadFiles(files)
        // results is fully typed based on your router configuration

console.log('Upload successful:', results.map(r => r.url))

// Reset the upload state
        reset()
      } catch (error) {
        console.error('Upload failed:', error)
      }
    }
    ```
  </Step>
</Steps>

## Client Configuration Options

<TypeTable
  type={{
  endpoint: {
    description: "API endpoint URL for your upload router",
    type: "string",
    required: true,
  },
  headers: {
    description: "Custom headers to include with upload requests",
    type: "Record<string, string>",
  },
  timeout: {
    description: "Request timeout in milliseconds",
    type: "number",
    default: "30000",
  },
  retries: {
    description: "Number of retry attempts for failed uploads",
    type: "number",
    default: "3",
  },
  onProgress: {
    description: "Global progress callback for all uploads",
    type: "(progress: UploadProgress) => void",
  },
  onError: {
    description: "Global error handler for upload failures",
    type: "(error: UploadError) => void",
  },
}}
/>

### Advanced Client Configuration

```typescript title="lib/upload-client.ts"
import { createUploadClient } from "pushduck/client";
import type { AppRouter } from "./upload";

export const upload = createUploadClient<AppRouter>({
  endpoint: "/api/upload",

// Custom headers (e.g., authentication)
  headers: {
    Authorization: `Bearer ${getAuthToken()}`,
    "X-Client-Version": "1.0.0",
  },

// Upload timeout (30 seconds)
  timeout: 30000,

// Retry failed uploads
  retries: 3,

// Global progress tracking
  onProgress: (progress) => {
    console.log(`Upload progress: ${progress.percentage}%`);
  },

// Global error handling
  onError: (error) => {
    console.error("Upload error:", error);
    // Send to error tracking service
    trackError(error);
  },
});
```

## Upload Method Options

Each upload method accepts configuration options:

<TypeTable
  type={{
  onProgress: {
    description: "Progress callback for this specific upload",
    type: "(progress: UploadProgress) => void",
  },
  onSuccess: {
    description: "Success callback when upload completes",
    type: "(results: UploadResult[]) => void",
  },
  onError: {
    description: "Error callback for this upload",
    type: "(error: UploadError) => void",
  },
  metadata: {
    description: "Custom metadata to include with upload",
    type: "Record<string, any>",
  },
  abortSignal: {
    description: "AbortSignal to cancel the upload",
    type: "AbortSignal",
  },
}}
/>

### Upload Method Examples

<Tabs items={["Basic Upload", "With Callbacks", "With Metadata", "Cancellable Upload"]} groupId="upload-methods">
  <Tab value="Basic Upload">
    ```typescript
    const { uploadFiles } = upload.imageUpload

// Simple upload
    const results = await uploadFiles(selectedFiles)
    console.log('Uploaded files:', results)
    ```
  </Tab>

<Tab value="With Callbacks">
    ```typescript
    const { uploadFiles } = upload.imageUpload

await uploadFiles(selectedFiles, {
      onProgress: (progress) => {
        console.log(`Upload ${progress.percentage}% complete`)
        updateProgressBar(progress.percentage)
      },

onSuccess: (results) => {
        console.log('Upload successful!', results)
        showSuccessNotification()
      },

onError: (error) => {
        console.error('Upload failed:', error)
        showErrorNotification(error.message)
      }
    })
    ```
  </Tab>

<Tab value="With Metadata">
    ```typescript
    const { uploadFiles } = upload.documentUpload

// Pass metadata as second parameter (not in options)
    await uploadFiles(selectedFiles, {
      category: 'contracts',
      department: 'legal',
      priority: 'high',
      tags: ['confidential', 'urgent'],
      projectId: currentProject.id,
      uploadedBy: currentUser.email
    })
    ```
  </Tab>

<Tab value="Cancellable Upload">
    ```typescript
    const { uploadFiles } = upload.videoUpload
    const abortController = new AbortController()

// Start upload
    const uploadPromise = uploadFiles(selectedFiles, {
      abortSignal: abortController.signal,
      onProgress: (progress) => {
        if (progress.percentage > 50 && shouldCancel) {
          abortController.abort()
        }
      }
    })

// Cancel upload after 10 seconds
    setTimeout(() => abortController.abort(), 10000)

try {
      await uploadPromise
    } catch (error) {
      if (error.name === 'AbortError') {
        console.log('Upload was cancelled')
      }
    }
    ```
  </Tab>
</Tabs>

## Hook-Based API (Alternative)

For teams that prefer React hooks, the hook-based API provides a familiar pattern:

<TypeTable
  type={{
  endpoint: {
    description: "Upload endpoint name from your router",
    type: "keyof AppRouter",
    required: true,
  },
  onSuccess: {
    description: "Success callback when upload completes",
    type: "(results: UploadResult[]) => void",
  },
  onError: {
    description: "Error callback for upload failures",
    type: "(error: UploadError) => void",
  },
}}
/>

### Hook Usage Examples

<Tabs items={["useUpload Hook", "Multiple Endpoints", "Custom Hook"]} groupId="hook-api">
  <Tab value="useUpload Hook">
    ```typescript
    import { useUpload } from 'pushduck/client'
    import type { AppRouter } from '@/lib/upload'

export function ImageUploadComponent() {
      const { uploadFiles, files, isUploading, error, reset } = useUpload<AppRouter>('imageUpload', {
        onSuccess: (results) => {
          console.log('Upload completed:', results)
        },
        onError: (error) => {
          console.error('Upload failed:', error)
        }
      })

return (
        <div>
          <input
            type="file"
            multiple
            onChange={(e) => uploadFiles(Array.from(e.target.files || []))}
            disabled={isUploading}
          />

{files.map(file => (
            <div key={file.id}>
              <span>{file.name}</span>
              <progress value={file.progress} max={100} />
              {file.status === 'error' && <span>Failed: {file.error}</span>}
              {file.status === 'success' && <a href={file.url}>View</a>}
            </div>
          ))}

<button onClick={reset} disabled={isUploading}>
            Reset
          </button>
        </div>
      )
    }
    ```
  </Tab>

<Tab value="Multiple Endpoints">
    ```typescript
    export function MultiUploadComponent() {
      const images = useUpload<AppRouter>('imageUpload')
      const documents = useUpload<AppRouter>('documentUpload')

return (
        <div>
          <div>
            <h3>Images</h3>
            <input
              type="file"
              accept="image/*"
              multiple
              onChange={(e) => images.uploadFiles(Array.from(e.target.files || []))}
            />
            {/* Render images.files */}
          </div>

<div>
            <h3>Documents</h3>
            <input
              type="file"
              accept=".pdf,.doc,.docx"
              onChange={(e) => documents.uploadFiles(Array.from(e.target.files || []))}
            />
            {/* Render documents.files */}
          </div>
        </div>
      )
    }
    ```
  </Tab>

<Tab value="Custom Hook">
    ```typescript
    import { useUpload } from 'pushduck/client'
    import { useCallback } from 'react'
    import type { AppRouter } from '@/lib/upload'

export function useImageUpload() {
      const upload = useUpload<AppRouter>('imageUpload', {
        onSuccess: (results) => {
          // Show success toast
          toast.success(`Uploaded ${results.length} images`)
        },
        onError: (error) => {
          // Show error toast
          toast.error(`Upload failed: ${error.message}`)
        }
      })

const uploadImages = useCallback(async (files: File[]) => {
        // Validate files before upload
        const validFiles = files.filter(file => {
          if (file.size > 5 * 1024 * 1024) { // 5MB
            toast.error(`${file.name} is too large`)
            return false
          }
          return true
        })

if (validFiles.length > 0) {
          await upload.uploadFiles(validFiles)
        }
      }, [upload.uploadFiles])

return {
        ...upload,
        uploadImages
      }
    }
    ```
  </Tab>
</Tabs>

## Property-Based Client Access

The property-based client provides enhanced type inference and eliminates string literals:

### Type Safety Benefits

<Cards>
  <Card title="Compile-Time Validation" description="Catch errors before runtime">
    ```typescript
    const { uploadFiles } = upload.imageUpload
    //                            ^ TypeScript knows this exists

const { uploadFiles: docUpload } = upload.nonExistentEndpoint
    //                                        ^ TypeScript error!
    ```
  </Card>

<Card title="IntelliSense Support" description="Full autocomplete for all endpoints">
    ```typescript
    upload. // IntelliSense shows: imageUpload, documentUpload, videoUpload
    //   ^ All your router endpoints are available with autocomplete
    ```
  </Card>

<Card title="Refactoring Safety" description="Rename endpoints safely across your codebase">
    ```typescript
    // If you rename 'imageUpload' to 'images' in your router,
    // TypeScript will show errors everywhere it's used,
    // making refactoring safe and easy
    ```
  </Card>
</Cards>

### Enhanced Type Inference

The property-based client provides complete type inference from your server router:

```typescript
// Server router definition
export const router = createUploadRouter({
  profilePictures: uploadSchema({
    image: { maxSize: "2MB", maxCount: 1 },
  }).middleware(async ({ req }) => {
    const userId = await getUserId(req);
    return { userId, category: "profile" };
  }),

// ... other endpoints
});

// Client usage with full type inference
const { uploadFiles, files, isUploading } = upload.profilePictures;
//      ^ uploadFiles knows it accepts File[]
//                   ^ files has type UploadFile[]
//                           ^ isUploading is boolean

// Upload files with inferred return type
const results = await uploadFiles(selectedFiles);
//    ^ results is UploadResult[] with your specific metadata shape
```

## Framework-Specific Configuration

<Tabs items={["Next.js", "React", "Vue", "Svelte"]} groupId="frameworks">
  <Tab value="Next.js">
    ```typescript
    // app/lib/upload-client.ts
    import { createUploadClient } from 'pushduck/client'
    import type { AppRouter } from './upload'

export const upload = createUploadClient<AppRouter>({
      endpoint: '/api/upload',
      headers: {
        // Next.js specific headers
        'x-requested-with': 'pushduck'
      }
    })

// app/components/upload-form.tsx
    'use client'

import { upload } from '@/lib/upload-client'

export function UploadForm() {
      const { uploadFiles, files, isUploading } = upload.imageUpload

// Component implementation...
    }
    ```
  </Tab>

<Tab value="React">
    ```typescript
    // src/lib/upload-client.ts
    import { createUploadClient } from 'pushduck/client'
    import type { AppRouter } from './upload'

export const upload = createUploadClient<AppRouter>({
      endpoint: process.env.REACT_APP_UPLOAD_ENDPOINT || '/api/upload'
    })

// src/components/UploadForm.tsx
    import React from 'react'
    import { upload } from '../lib/upload-client'

export function UploadForm() {
      const { uploadFiles, files, isUploading } = upload.imageUpload

// Component implementation...
    }
    ```
  </Tab>

<Tab value="Vue">
    ```typescript
    // lib/upload-client.ts
    import { createUploadClient } from '@pushduck/vue'
    import type { AppRouter } from './upload'

export const upload = createUploadClient<AppRouter>({
      endpoint: '/api/upload'
    })

// components/UploadForm.vue
    <script setup lang="ts">
    import { upload } from '@/lib/upload-client'

const { uploadFiles, files, isUploading } = upload.imageUpload
    // Vue 3 Composition API with full type safety
    </script>
    ```
  </Tab>

<Tab value="Svelte">
    ```typescript
    // lib/upload-client.ts
    import { uploadStore } from '@pushduck/svelte'
    import type { AppRouter } from './upload'

export const upload = uploadStore<AppRouter>('/api/upload')

// components/UploadForm.svelte
    <script lang="ts">
    import { upload } from '../lib/upload-client'

// Reactive stores
    $: ({ files, isUploading } = $upload.imageUpload)
    </script>
    ```
  </Tab>
</Tabs>

## Error Handling Configuration

Configure comprehensive error handling for robust applications:

<TypeTable
  type={{
  retryDelays: {
    description: "Delay between retry attempts in milliseconds",
    type: "number[]",
    default: "[1000, 2000, 4000]",
  },
  retryCondition: {
    description: "Custom function to determine if upload should be retried",
    type: "(error: UploadError, attemptNumber: number) => boolean",
  },
  maxConcurrentUploads: {
    description: "Maximum number of concurrent file uploads",
    type: "number",
    default: "3",
  },
  chunkSize: {
    description: "Size of upload chunks for large files",
    type: "number",
    default: "5242880",
  },
}}
/>

### Advanced Error Handling

```typescript
export const upload = createUploadClient<AppRouter>({
  endpoint: "/api/upload",

// Custom retry configuration
  retries: 3,
  retryDelays: [1000, 2000, 4000], // 1s, 2s, 4s

// Custom retry logic
  retryCondition: (error, attemptNumber) => {
    // Don't retry client errors (4xx)
    if (error.status >= 400 && error.status < 500) {
      return false;
    }

// Retry server errors up to 3 times
    return attemptNumber < 3;
  },

// Concurrent upload limits
  maxConcurrentUploads: 2,

// Large file chunking
  chunkSize: 10 * 1024 * 1024, // 10MB chunks

// Global error handler
  onError: (error) => {
    // Log to error tracking service
    if (error.status >= 500) {
      logError("Server error during upload", error);
    }

// Show user-friendly message
    if (error.code === "FILE_TOO_LARGE") {
      showToast("File is too large. Please choose a smaller file.");
    } else if (error.code === "NETWORK_ERROR") {
      showToast("Network error. Please check your connection.");
    } else {
      showToast("Upload failed. Please try again.");
    }
  },
});
```

## Performance Optimization

Configure the client for optimal performance:

### Upload Performance

```typescript
export const upload = createUploadClient<AppRouter>({
  endpoint: "/api/upload",

// Optimize for performance
  maxConcurrentUploads: 3, // Balance between speed and resource usage
  chunkSize: 5 * 1024 * 1024, // 5MB chunks for large files
  timeout: 60000, // 60 second timeout for large files

// Compression for images
  compressImages: {
    enabled: true,
    quality: 0.8, // 80% quality
    maxWidth: 1920, // Resize large images
    maxHeight: 1080,
  },

// Connection pooling
  keepAlive: true,
  maxSockets: 5,

// Progress throttling to avoid UI updates spam
  progressThrottle: 100, // Update progress every 100ms
});
```

## Real-World Configuration Examples

### E-commerce Application

```typescript
export const ecommerceUpload = createUploadClient<EcommerceRouter>({
  endpoint: "/api/upload",

headers: {
    Authorization: `Bearer ${getAuthToken()}`,
    "X-Store-ID": getStoreId(),
  },

onProgress: (progress) => {
    // Update global upload progress indicator
    updateGlobalProgress(progress);
  },

onError: (error) => {
    // Track upload failures for analytics
    analytics.track("upload_failed", {
      error_code: error.code,
      file_type: error.metadata?.fileType,
      store_id: getStoreId(),
    });
  },

// E-commerce specific settings
  retries: 2, // Quick retries for better UX
  maxConcurrentUploads: 5, // Allow multiple product images
  compressImages: {
    enabled: true,
    quality: 0.9, // High quality for product images
  },
});

// Usage in product form
export function ProductImageUpload() {
  const { uploadFiles, files, isUploading } = ecommerceUpload.productImages;

return (
    // Upload component implementation
    <div>{/* Upload UI */}</div>
  );
}
```

### Content Management System

```typescript
export const cmsUpload = createUploadClient<CMSRouter>({
  endpoint: "/api/upload",

headers: {
    Authorization: `Bearer ${getAuthToken()}`,
    "X-Workspace": getCurrentWorkspace(),
  },

// CMS-specific configuration
  timeout: 120000, // 2 minutes for large documents
  retries: 3,
  maxConcurrentUploads: 2, // Conservative for large files

onError: (error) => {
    // Show contextual error messages
    if (error.code === "QUOTA_EXCEEDED") {
      showUpgradeModal();
    } else if (error.code === "UNAUTHORIZED") {
      redirectToLogin();
    }
  },
});

// Usage in content editor
export function MediaLibrary() {
  const images = cmsUpload.images;
  const documents = cmsUpload.documents;
  const videos = cmsUpload.videos;

return (
    <div>
      <MediaUploadTabs>
        <Tab name="Images">
          <UploadZone {...images} accept="image/*" />
        </Tab>
        <Tab name="Documents">
          <UploadZone {...documents} accept=".pdf,.doc,.docx" />
        </Tab>
        <Tab name="Videos">
          <UploadZone {...videos} accept="video/*" />
        </Tab>
      </MediaUploadTabs>
    </div>
  );
}
```

***

<Callout type="success">
  **Ready to upload?** Check out our [complete examples](/docs/examples) to see
  these configurations in action, or explore our [provider setup
  guides](/docs/providers/aws-s3) to configure your storage backend.
</Callout>

# Configuration (/docs/api/configuration)

import { Cards, Card } from "fumadocs-ui/components/card";
import { Callout } from "fumadocs-ui/components/callout";

## Configuration Overview

Configure pushduck to match your application's specific needs. From basic upload settings to advanced path generation and middleware, pushduck provides flexible configuration options for every use case.

## Configuration Categories

<Cards>
  <Card title="📁 Upload Configuration" description="Basic upload settings, file validation, and schema definitions" href="/docs/api/configuration/upload-config">
    **Core upload settings** for your application.

* File size and type validation
    * Schema definitions (image, file, object)
    * Default configurations
    * Environment-based settings

**Start here** for basic pushduck setup.
  </Card>

<Card title="🎯 Client Options" description="Client-side configuration for upload behavior and UI integration" href="/docs/api/configuration/client-options">
    **Enhanced client configuration** with property-based access.

* Property-based vs hook-based clients
    * Upload callbacks and progress tracking
    * Error handling and retry logic
    * TypeScript integration

**Perfect for** modern React applications.
  </Card>

<Card title="🌐 Server Router" description="Server-side route configuration and API endpoint setup" href="/docs/api/configuration/server-router">
    **Server route configuration** for API endpoints.

* Router setup and handlers
    * Middleware integration
    * Lifecycle hooks (onStart, onComplete, onError)
    * Multi-route configurations

**Essential for** API route setup.
  </Card>

<Card title="📂 Path Configuration" description="Custom file paths, naming patterns, and storage organization" href="/docs/api/configuration/path-configuration">
    **Advanced path management** for organized storage.

* Custom path generation
    * Dynamic naming patterns
    * Hierarchical organization
    * User-based separation

**Great for** complex applications.
  </Card>
</Cards>

## Quick Configuration Examples

### Basic Setup

```typescript
// lib/upload.ts
import { createUploadConfig } from 'pushduck/server'

export const { s3, storage } = createUploadConfig()
  .provider("cloudflareR2", {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    accountId: process.env.R2_ACCOUNT_ID,
    bucket: process.env.S3_BUCKET_NAME,
  })
  .defaults({
    maxFileSize: '10MB',
    acl: 'public-read',
  })
  .build()
```

### Advanced Configuration

```typescript
// lib/upload.ts - Advanced setup
export const { s3, storage } = createUploadConfig()
  .provider("aws", { /* credentials */ })
  .defaults({
    maxFileSize: '100MB',
    acl: 'private',
  })
  .paths({
    prefix: 'uploads',
    generateKey: (file, metadata) => {
      const userId = metadata.userId || 'anonymous'
      const timestamp = Date.now()
      return `${userId}/${timestamp}/${file.name}`
    },
  })
  .hooks({
    onUploadStart: async ({ file, metadata }) => {
      console.log(`Starting upload: ${file.name}`)
    },
    onUploadComplete: async ({ file, url, metadata }) => {
      await saveToDatabase({ file, url, userId: metadata.userId })
    },
  })
  .build()
```

## Configuration Flow

The configuration system follows a builder pattern:

1. **Provider Setup** → Choose your storage provider
2. **Defaults** → Set global upload settings
3. **Paths** → Configure file organization
4. **Hooks** → Add lifecycle callbacks
5. **Build** → Generate final configuration

<Callout type="tip">
  **Best Practice**: Start with basic configuration and gradually add advanced features as your application grows.
</Callout>

## Environment Variables

Common environment variables across all configurations:

```bash
# Storage Provider
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=us-east-1
S3_BUCKET_NAME=your-bucket

# Optional: Custom endpoints
AWS_ENDPOINT_URL=https://your-custom-endpoint.com
```

## TypeScript Integration

All configuration options are fully typed:

```typescript
import type { UploadConfig, S3ProviderConfig } from 'pushduck/server'

// Full type safety throughout configuration
const config: UploadConfig = createUploadConfig()
  .provider("aws", providerConfig as S3ProviderConfig)
  .build()
```

***

## Next Steps

* **New to pushduck?** Start with [Upload Configuration](/docs/api/configuration/upload-config)
* **Building a client?** See [Client Options](/docs/api/configuration/client-options)
* **Setting up routes?** Check [Server Router](/docs/api/configuration/server-router)
* **Need custom paths?** Explore [Path Configuration](/docs/api/configuration/path-configuration)

# Path Configuration (/docs/api/configuration/path-configuration)

## Custom Route Paths

Organize your uploads with hierarchical path structures that provide clean file organization, prevent conflicts, and enable scalable storage patterns.

<Callout type="warning">
  **Default Behavior:** By default, files are uploaded with just the sanitized filename (e.g., `photo.jpg`). No automatic paths, prefixes, or organization are added. You must explicitly configure paths if you want file organization.
</Callout>

<Callout type="info">
  **New in v2.0:** The hierarchical path system allows global configuration to provide the foundation while route-level paths extend and nest within it - **no more overrides that lose configuration!**
</Callout>

## How Hierarchical Paths Work

The path system works in **layers** that build upon each other:

**Path Structure:** `{globalPrefix}/{routePrefix}/{globalGenerated}`

* **Global prefix:** `uploads` (foundation for all files)
* **Route prefix:** `images`, `documents` (category organization)
* **Global generated:** `{userId}/{timestamp}/{randomId}/{filename}` (file structure)

## Default Behavior

**Without any path configuration**, files are uploaded with just the sanitized filename:

```typescript
// No path configuration
const { s3 } = createUploadConfig()
  .provider("aws", { /* config */ })
  .build();

const router = s3.createRouter({
  imageUpload: s3.image().maxFileSize("5MB"),
});
```

**Result:** Files are stored as `photo.jpg`, `document.pdf`, etc. (just the filename)

## Basic Path Configuration

### Global Foundation

To organize files, explicitly configure the base structure that all uploads will use:

```typescript title="lib/upload.ts"
import { createUploadConfig } from "pushduck/server";

const { s3 } = createUploadConfig()
  .provider("cloudflareR2",{
    // ... provider config
  })
  .paths({
    // Global prefix - foundation for ALL uploads
    prefix: "uploads",
    
    // Global structure - used when routes don't override
    // Use whatever metadata structure fits your app
    generateKey: (file, metadata) => {
      // Example: Using organizationId from your metadata
      const orgId = (metadata as any)?.organizationId || "default";
      
      // Add timestamp if you want chronological organization
      const timestamp = Date.now();
      
      // Add random ID if you want to prevent filename conflicts
      const randomId = Math.random().toString(36).substring(2, 8);
      
      // Sanitize filename
      const sanitizedName = file.name.replace(/[^a-zA-Z0-9.-]/g, "_");

// Return ONLY the file path part (no prefix)
      // You control what goes in the path - timestamps, random IDs, etc.
      return `${orgId}/${timestamp}/${randomId}/${sanitizedName}`;
    },
  })
  .build();
```

### Route-Level Extensions

Extend the global foundation with route-specific organization:

```typescript title="app/api/upload/route.ts"
import { s3 } from "@/lib/upload";

const s3Router = s3.createRouter({
  // Images: uploads/images/{orgId}/{timestamp}/{randomId}/photo.jpg
  imageUpload: s3
    .image()
    .maxFileSize("5MB")
    .paths({
      prefix: "images", // Nests under global prefix
    }),

// Documents: uploads/documents/{orgId}/{timestamp}/{randomId}/report.pdf  
  documentUpload: s3
    .file()
    .maxFileSize("10MB")
    .paths({
      prefix: "documents", // Nests under global prefix
    }),

// General: uploads/{orgId}/{timestamp}/{randomId}/file.ext
  generalUpload: s3
    .file()
    .maxFileSize("20MB")
    // No .paths() - uses pure global configuration
});
```

<Callout type="success">
  **✨ Result:** Clean, predictable paths that scale with your application. Global config provides consistency while routes add organization.
</Callout>

## Advanced Path Patterns

### Custom Route Generation

Override the default structure for specific use cases:

<Tabs items={["Date-Based", "Category-Based", "Project-Based"]} groupId="path-patterns">
  <Tab value="Date-Based">
    ```typescript
    galleryUpload: s3
      .image()
      .maxFileSize("5MB")
      .middleware(async ({ req }) => {
        // Your metadata structure - could be organizationId, projectId, etc.
        return { organizationId: await getOrgId(req) };
      })
      .paths({
        generateKey: (ctx) => {
          const { file, metadata, globalConfig } = ctx;
          const globalPrefix = globalConfig.prefix || "uploads";
          const date = new Date();
          const year = date.getFullYear();
          const month = String(date.getMonth() + 1).padStart(2, "0");
          const orgId = (metadata as any)?.organizationId || "default";
          
          // Custom path: uploads/gallery/2024/06/org-123/photo.jpg
          return `${globalPrefix}/gallery/${year}/${month}/${orgId}/${file.name}`;
        },
      })
    ```

**Result:** `uploads/gallery/2024/06/org-123/photo.jpg`
  </Tab>

<Tab value="Category-Based">
    ```typescript
    productUpload: s3
      .image()
      .maxFileSize("8MB")
      .paths({
        generateKey: (ctx) => {
          const { file, metadata, globalConfig } = ctx;
          const globalPrefix = globalConfig.prefix || "uploads";
          const category = metadata.category || "general";
          const productId = metadata.productId || "unknown";
          const timestamp = Date.now();
          
          // Custom path: uploads/products/electronics/prod-123/1234567890/image.jpg
          return `${globalPrefix}/products/${category}/${productId}/${timestamp}/${file.name}`;
        },
      })
    ```

**Result:** `uploads/products/electronics/prod-123/1234567890/image.jpg`
  </Tab>

<Tab value="Project-Based">
    ```typescript
    projectAssets: s3
      .image()
      .maxFileSize("2MB")
      .middleware(async ({ req }) => {
        // Your metadata - could be projectId, teamId, workspaceId, etc.
        return { projectId: await getProjectId(req) };
      })
      .paths({
        generateKey: (ctx) => {
          const { file, metadata, globalConfig } = ctx;
          const globalPrefix = globalConfig.prefix || "uploads";
          const projectId = (metadata as any)?.projectId || "default";
          const fileType = file.type.split('/')[0]; // image, video, etc.
          
          // Custom path: uploads/projects/proj-123/assets/image/logo.jpg
          return `${globalPrefix}/projects/${projectId}/assets/${fileType}/${file.name}`;
        },
      })
    ```

**Result:** `uploads/projects/proj-123/assets/image/logo.jpg`
  </Tab>
</Tabs>

### Environment-Based Paths

Organize files by environment for clean separation:

```typescript title="lib/upload.ts"
const { s3 } = createUploadConfig()
  .provider("cloudflareR2",{
    // ... provider config
  })
  .paths({
    // Environment-aware global prefix
    prefix: process.env.NODE_ENV === "production" ? "prod" : "dev",
    
    generateKey: (file, metadata) => {
      // Use whatever identifier fits your app - organizationId, teamId, etc.
      const orgId = (metadata as any)?.organizationId || "default";
      
      // Add timestamp and random ID yourself if you want them
      const timestamp = Date.now();
      const randomId = Math.random().toString(36).substring(2, 8);
      
      return `${orgId}/${timestamp}/${randomId}/${file.name}`;
    },
  })
  .build();
```

**Result Paths:**

* **Development:** `dev/images/org123/1234567890/abc123/photo.jpg`
* **Production:** `prod/images/org123/1234567890/abc123/photo.jpg`

## Path Configuration API

### Global Configuration

<TypeTable
  type={{
  prefix: {
    description: "Base prefix for all uploaded files (optional - no default)",
    type: "string",
    default: "undefined (no prefix by default)",
  },
  generateKey: {
    description: "Function to generate the file path structure (optional - defaults to just filename)",
    type: "(file, metadata) => string",
  },
}}
/>

```typescript
.paths({
  prefix: "uploads",
  generateKey: (file, metadata) => {
    // Return the file path structure (without prefix)
    // Use whatever metadata structure fits your app
    const identifier = (metadata as any)?.organizationId || "default";
    return `${identifier}/${Date.now()}/${file.name}`;
  }
})
```

### Route Configuration

<TypeTable
  type={{
  prefix: {
    description: "Route-specific prefix, nested under global prefix",
    type: "string",
  },
  generateKey: {
    description: "Custom path generation with access to global config",
    type: "(ctx: PathContext) => string",
  },
}}
/>

```typescript
.paths({
  prefix: "images", // Nested under global prefix
  generateKey: (ctx) => {
    const { file, metadata, globalConfig, routeName } = ctx;
    // Full control with access to global configuration
    return `${globalConfig.prefix}/custom/${file.name}`;
  }
})
```

### PathContext Reference

When using custom `generateKey` functions at the route level, you receive a context object:

## Real-World Examples

### E-commerce Platform

```typescript title="app/api/upload/route.ts"
const s3Router = s3.createRouter({
  // Product images: uploads/products/{category}/{productId}/images/photo.jpg
  productImages: s3
    .image()
    .maxFileSize("8MB")
    .accept(["image/jpeg", "image/png", "image/webp"])
    .middleware(async ({ req }) => {
      const { productId, category } = await getProductContext(req);
      return { productId, category, userId: await getUserId(req) };
    })
    .paths({
      generateKey: (ctx) => {
        const { file, metadata, globalConfig } = ctx;
        const { productId, category } = metadata;
        return `${globalConfig.prefix}/products/${category}/${productId}/images/${file.name}`;
      },
    }),

// User avatars: uploads/users/{userId}/avatar/profile.jpg
  // Note: This example uses userId, but you can use any metadata structure
  userAvatar: s3
    .image()
    .maxFileSize("2MB")
    .accept(["image/jpeg", "image/png", "image/webp"])
    .middleware(async ({ req }) => {
      // Your metadata structure - could be userId, accountId, memberId, etc.
      const userId = await getUserId(req);
      return { userId, type: "avatar" };
    })
    .paths({
      generateKey: (ctx) => {
        const { file, metadata, globalConfig } = ctx;
        const userId = (metadata as any)?.userId;
        return `${globalConfig.prefix}/users/${userId}/avatar/${file.name}`;
      },
    }),

// Order documents: uploads/orders/{orderId}/documents/{timestamp}/receipt.pdf
  orderDocuments: s3
    .file()
    .maxFileSize("10MB")
    .accept(["application/pdf", "image/*"])
    .middleware(async ({ req }) => {
      const { orderId } = await getOrderContext(req);
      return { orderId, uploadedAt: new Date().toISOString() };
    })
    .paths({
      generateKey: (ctx) => {
        const { file, metadata, globalConfig } = ctx;
        const timestamp = Date.now();
        return `${globalConfig.prefix}/orders/${metadata.orderId}/documents/${timestamp}/${file.name}`;
      },
    }),
});
```

### Content Management System

```typescript title="app/api/upload/route.ts"
const s3Router = s3.createRouter({
  // Media library: uploads/media/{year}/{month}/{type}/filename.ext
  mediaLibrary: s3
    .file()
    .maxFileSize("50MB")
    .middleware(async ({ req, file }) => {
      const userId = await getUserId(req);
      const mediaType = file.type.split('/')[0]; // image, video, audio
      return { userId, mediaType };
    })
    .paths({
      generateKey: (ctx) => {
        const { file, metadata, globalConfig } = ctx;
        const date = new Date();
        const year = date.getFullYear();
        const month = String(date.getMonth() + 1).padStart(2, "0");
        const randomId = Math.random().toString(36).substring(2, 8);
        
        return `${globalConfig.prefix}/media/${year}/${month}/${metadata.mediaType}/${randomId}-${file.name}`;
      },
    }),

// Page assets: uploads/pages/{pageSlug}/assets/image.jpg
  pageAssets: s3
    .image()
    .maxFileSize("10MB")
    .middleware(async ({ req }) => {
      const { pageSlug } = await getPageContext(req);
      return { pageSlug, userId: await getUserId(req) };
    })
    .paths({
      generateKey: (ctx) => {
        const { file, metadata, globalConfig } = ctx;
        return `${globalConfig.prefix}/pages/${metadata.pageSlug}/assets/${file.name}`;
      },
    }),

// Temp uploads: uploads/temp/{userId}/{sessionId}/file.ext
  tempUploads: s3
    .file()
    .maxFileSize("20MB")
    .middleware(async ({ req }) => {
      const userId = await getUserId(req);
      const sessionId = req.headers.get('x-session-id') || 'unknown';
      return { userId, sessionId, temporary: true };
    })
    .paths({
      prefix: "temp", // Simple prefix approach
    }),
});
```

## Best Practices

### Path Organization

<Cards>
  <Card title="Use Descriptive Prefixes" description="Make paths self-documenting">
    ```typescript
    // ✅ Good
    .paths({ prefix: "user-avatars" })
    .paths({ prefix: "product-images" })

// ❌ Avoid
    .paths({ prefix: "imgs" })
    .paths({ prefix: "files" })
    ```
  </Card>

<Card title="Include Identifiers" description="Make files traceable">
    ```typescript
    // ✅ Good - includes user and timestamp
    return `${prefix}/users/${userId}/${timestamp}/${file.name}`;

// ❌ Avoid - no traceability
    return `${prefix}/${file.name}`;
    ```
  </Card>

<Card title="Prevent Conflicts" description="Use unique identifiers when needed">
    ```typescript
    // ✅ Good - add timestamp and random ID yourself if you want them
    const timestamp = Date.now();
    const randomId = Math.random().toString(36).substring(2, 8);
    const identifier = metadata.organizationId || "default";
    return `${prefix}/${identifier}/${timestamp}/${randomId}/${file.name}`;

// ✅ Also valid - simple path if conflicts aren't a concern
    return `${prefix}/${identifier}/${file.name}`;
    ```
  </Card>
</Cards>

### Performance Tips

<Callout type="warn">
  **Path Length Limits:** Most S3-compatible services have a 1024-character limit for object keys. Keep your paths reasonable!
</Callout>

* **Use short, meaningful prefixes** instead of long descriptive names
* **Avoid deep nesting** beyond 5-6 levels for better performance
* **Add timestamps yourself** if you want chronological ordering (e.g., `Date.now()`)
* **Add random IDs yourself** if you need to prevent filename conflicts (e.g., `Math.random().toString(36).substring(2, 8)`)
* **Sanitize filenames** to prevent special character issues

### Security Considerations

```typescript
// ✅ Sanitize user input in paths
const sanitizePathSegment = (input: string) => {
  return input.replace(/[^a-zA-Z0-9.-]/g, "_").substring(0, 50);
};

.paths({
  generateKey: (ctx) => {
    const { file, metadata, globalConfig } = ctx;
    // Sanitize whatever identifier you use from metadata
    const identifier = (metadata as any)?.organizationId || "default";
    const safeIdentifier = sanitizePathSegment(identifier);
    const safeFilename = sanitizePathSegment(file.name);
    
    return `${globalConfig.prefix}/orgs/${safeIdentifier}/${Date.now()}/${safeFilename}`;
  }
})
```

## Migration from Legacy Paths

<Callout type="info">
  **Upgrading from v1.x?** The old `pathPrefix` option still works but is deprecated. Use the new hierarchical system for better organization.
</Callout>

### Before (Legacy)

```typescript
// Old way - simple prefix only
export const { POST, GET } = s3Router.handlers;
```

### After (Hierarchical)

```typescript
// New way - hierarchical configuration
const { s3 } = createUploadConfig()
  .provider("cloudflareR2",{ /* config */ })
  .paths({
    prefix: "uploads",
    generateKey: (file, metadata) => {
      // Use whatever metadata structure fits your app
      const identifier = (metadata as any)?.organizationId || "default";
      return `${identifier}/${Date.now()}/${file.name}`;
    }
  })
  .build();

const s3Router = s3.createRouter({
  images: s3.image().paths({ prefix: "images" }),
  documents: s3.file().paths({ prefix: "documents" })
});
```

**Benefits of upgrading:**

* ✅ **Better organization** with route-specific prefixes
* ✅ **No configuration loss** - global settings are preserved
* ✅ **More flexibility** with custom generation functions
* ✅ **Type safety** with PathContext
* ✅ **Scalable patterns** for growing applications

<Callout type="success">
  **🎉 You're ready!** Your uploads now have clean, organized, and scalable path structures that will grow with your application.
</Callout>

# Server Router (/docs/api/configuration/server-router)

## Setting Up Server Routes

The server router is the heart of pushduck. It defines your upload endpoints with complete type safety and validates all uploads against your schema.

<Callout type="info">
  This guide covers the **enhanced router API** with property-based client
  access. Looking for the legacy API? Check our [migration
  guide](/docs/guides/migrate-to-enhanced-client).
</Callout>

## Project Structure

A typical Next.js project with pushduck follows this structure:

## Basic Router Setup

<Steps>
  <Step>
    **Create your upload route**

Start by creating the API route that will handle your uploads:

```typescript title="app/api/upload/route.ts"
    import { s3 } from '@/lib/upload'

const s3Router = s3.createRouter({
      imageUpload: s3
        .image()
        .maxFileSize('4MB')
        .maxFiles(10)
        .middleware(async ({ req }) => {
        // Add your authentication logic here
        return { userId: "user_123" }
      }),

documentUpload: s3
        .file()
        .maxFileSize('10MB')
        .accept(['application/pdf'])
        .maxFiles(1)
    })

export const { POST, GET } = s3Router.handlers
    ```
  </Step>

<Step>
    **Export router types**

Create a separate file to export your router types for client-side usage:

```typescript title="lib/upload.ts"
    import { createUploadConfig } from 'pushduck/server'

// Configure upload with provider and settings
    const { s3, storage } = createUploadConfig()
      .provider("cloudflareR2",{
        accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
        region: 'auto',
        endpoint: process.env.AWS_ENDPOINT_URL!,
        bucket: process.env.S3_BUCKET_NAME!,
        accountId: process.env.R2_ACCOUNT_ID!,
      })
      .build()

// Define your router
    const s3Router = s3.createRouter({
      imageUpload: s3.image().maxFileSize('4MB').maxFiles(10),
      documentUpload: s3.file().maxFileSize('10MB').accept(['application/pdf']).maxFiles(1)
    })

// Export for use in API routes and client
    export { s3, storage }
    export type AppS3Router = typeof s3Router
    ```
  </Step>

<Step>
    **Create typed client**

Set up your client-side upload client with full type safety:

```typescript title="lib/upload-client.ts"
    import { createUploadClient } from 'pushduck/client'
    import type { AppS3Router } from './upload'

export const upload = createUploadClient<AppS3Router>({
      endpoint: '/api/upload'
    })
    ```
  </Step>
</Steps>

## Schema Builder Reference

The `s3` schema builders provide a fluent API for defining your upload requirements:

### FileConfig Options

## Advanced Configuration

### Multiple File Types

You can define schemas that accept multiple file types:

<Tabs items={["Images & Documents", "Mixed Media", "Any Files"]} groupId="file-types">
  <Tab value="Images & Documents">
    ```typescript
    const s3Router = s3.createRouter({
      mixedUpload: s3.object({
        images: s3.image().maxFileSize('4MB').maxFiles(5),
        pdfs: s3.file().maxFileSize('10MB').accept(['application/pdf']).maxFiles(2),
        documents: s3.file().maxFileSize('5MB').accept(['application/vnd.openxmlformats-officedocument.wordprocessingml.document']).maxFiles(3)
      })
    })
    ```
  </Tab>

<Tab value="Mixed Media">
    ```typescript
    const s3Router = s3.createRouter({
      mediaUpload: s3.object({
        images: s3.image()
          .maxFileSize('4MB')
          .maxFiles(10)
          .accept(['image/jpeg', 'image/png', 'image/webp']),
        videos: s3.file()
          .maxFileSize('100MB')
          .maxFiles(2)
          .accept(['video/mp4', 'video/quicktime', 'video/avi'])
      })
    })
    ```
  </Tab>

<Tab value="Any Files">
    ```typescript
    const s3Router = s3.createRouter({
      genericUpload: s3.file()
        .maxFileSize('50MB')
        .maxFiles(20)
        .accept([
          'image/*', 'video/*', 'application/pdf',
          'application/msword', 'text/plain'
        ])
    })
    ```
  </Tab>
</Tabs>

### Global Configuration

Configure settings that apply to all upload endpoints:

<Callout type="warn">
  **Deprecated:** The `pathPrefix` option is deprecated. Use the new [**hierarchical path configuration**](/docs/api/configuration/path-configuration) for better organization and flexibility.
</Callout>

```typescript
// ❌ Deprecated approach - use modern createUploadConfig() instead
// This section is kept for reference only
```

**For new projects, use the [hierarchical path system](/docs/api/configuration/path-configuration) instead:**

```typescript
// ✅ Modern approach with hierarchical paths
const { s3 } = createUploadConfig()
  .provider("cloudflareR2",{ /* config */ })
  .paths({
    prefix: "uploads",
    generateKey: (file, metadata) => {
      return `${metadata.userId}/${Date.now()}/${file.name}`;
    }
  })
  .build();

const s3Router = s3.createRouter({
  images: s3.image().paths({ prefix: "images" }),
  documents: s3.file().paths({ prefix: "documents" })
});
```

### Multiple Providers

Support different storage providers for different upload types:

```typescript
// ✅ Modern approach with multiple provider configurations
import { createUploadConfig } from "pushduck/server";

const primaryConfig = createUploadConfig()
  .provider("cloudflareR2",{
    // Primary R2 config for production files
    accessKeyId: process.env.R2_ACCESS_KEY_ID!,
    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
    accountId: process.env.R2_ACCOUNT_ID!,
    bucket: process.env.R2_BUCKET!,
  })
  .build();

const backupConfig = createUploadConfig()
  .provider("aws",{
    // AWS S3 config for backups
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    region: process.env.AWS_REGION!,
    bucket: process.env.AWS_BACKUP_BUCKET!,
  })
  .build();

// Use primary config for main uploads
const s3Router = primaryConfig.s3.createRouter({
  productImages: primaryConfig.s3.image().maxFileSize("4MB").maxFiles(10),
  // Backup handling would be done in lifecycle hooks
});
```

## Middleware Integration

Add authentication, logging, and custom validation:

### Authentication Middleware

```typescript
const s3Router = s3.createRouter({
  privateUploads: s3.image()
    .maxFileSize("4MB")
    .maxFiles(5)
    .middleware(async ({ req, metadata }) => {
      const session = await getServerSession(req);

if (!session?.user?.id) {
        throw new Error("Unauthorized");
      }

return {
        ...metadata,
        userId: session.user.id,
        userRole: session.user.role,
      };
    }),

publicUploads: s3.image()
    .maxFileSize("1MB")
    .maxFiles(1), // No middleware = publicly accessible
});
```

### File Validation Middleware

```typescript
import { z } from "zod";

const s3Router = s3.createRouter({
  profilePicture: s3.image()
    .maxFileSize("2MB")
    .maxFiles(1)
    .middleware(async ({ req, file, metadata }) => {
      // Custom file validation
      if (file.name.includes("temp") || file.name.includes("test")) {
        throw new Error("Temporary files not allowed");
      }

const userId = await getUserId(req);
      return { ...metadata, userId };
    }),
});
```

### Metadata Enhancement

```typescript
const s3Router = s3.createRouter({
  documentUpload: s3.file()
    .maxFileSize("10MB")
    .maxFiles(1)
    .accept(["application/pdf"])
    .middleware(async ({ req, metadata }) => {
      const enrichedMetadata = {
        ...metadata,
        uploadedAt: new Date().toISOString(),
        userAgent: req.headers.get("user-agent"),
        ip: req.headers.get("x-forwarded-for") || "unknown",
      };

return enrichedMetadata;
    }),
});
```

## Lifecycle Hooks

Handle upload events for processing, notifications, and cleanup:

<TypeTable
  type={{
  onUploadStart: {
    description: "Called when upload begins",
    type: "(context) => void | Promise<void>",
  },
  onUploadProgress: {
    description: "Called during upload progress",
    type: "(context, progress) => void | Promise<void>",
  },
  onUploadComplete: {
    description: "Called when upload succeeds",
    type: "(context, result) => void | Promise<void>",
  },
  onUploadError: {
    description: "Called when upload fails",
    type: "(context, error) => void | Promise<void>",
  },
}}
/>

```typescript
const s3Router = s3.createRouter({
  imageUpload: s3.image()
    .maxFileSize("4MB")
    .maxFiles(10)
    .onUploadComplete(async ({ file, url, metadata }) => {
      // Process uploaded image - use permanent URL for processing
      await generateThumbnail(url);
      await updateDatabase({
        key: file.key,
        publicUrl: url,
        userId: metadata.userId
      });
    })
    .onUploadError(async ({ error, metadata }) => {
      // Log errors and notify admins
      console.error("Upload failed:", error);
      await notifyAdmins(`Upload failed for user ${metadata.userId}`);
    }),
});
```

## Type Safety Features

### Router Type Export

Export your router type for end-to-end type safety:

```typescript title="lib/upload.ts"
import { createUploadConfig } from "pushduck/server";

const { s3 } = createUploadConfig()
  .provider("cloudflareR2",{ /* your config */ })
  .build();

const s3Router = s3.createRouter({
  // ... your configuration
});

export { s3 };
export type AppS3Router = typeof s3Router;

// Extract individual endpoint types
export type ImageUploadType = AppS3Router["imageUpload"];
export type DocumentUploadType = AppS3Router["documentUpload"];
```

### Custom Context Types

Define custom context types for your middleware:

```typescript
interface CustomContext {
  userId: string;
  userRole: "admin" | "user" | "guest";
  organizationId?: string;
}

const s3Router = s3.createRouter({
  upload: s3.image()
    .maxFileSize('4MB')
    .maxFiles(5)
    .middleware(async ({ req }): Promise<CustomContext> => {
    // Your auth logic here
    return {
      userId: "user_123",
      userRole: "user",
    };
  }),
});
```

## Real-World Examples

### E-commerce Product Images

```typescript
const ecommerceRouter = s3.createRouter({
  productImages: s3.image()
    .maxFileSize('5MB')
    .maxFiles(8)
    .accept(['image/webp', 'image/jpeg'])
    .middleware(async ({ req }) => {
      const vendorId = await getVendorId(req);
      return { vendorId, category: "products" };
    })
    .onUploadComplete(async ({ files, metadata }) => {
      // Update product catalog
      await updateProductImages(metadata.vendorId, files);
    }),
});
```

### Document Management System

```typescript
const docsRouter = s3.createRouter({
  contracts: s3.file()
    .maxFileSize('25MB')
    .accept(['application/pdf'])
    .maxFiles(1)
    .middleware(async ({ req }) => {
    const { userId, companyId } = await validateContractUpload(req);
    return { userId, companyId, confidential: true };
  }),

proposals: s3.object({
    pdfs: s3.file().maxFileSize('50MB').accept(['application/pdf']).maxFiles(3),
    documents: s3.file().maxFileSize('25MB').accept(['application/vnd.openxmlformats-officedocument.wordprocessingml.document']).maxFiles(5),
  }).middleware(async ({ req }) => {
    const { userId, projectId } = await validateProposalUpload(req);
    return { userId, projectId };
  }),
});
```

### Social Media Platform

```typescript
export const socialRouter = createUploadRouter({
  profilePicture: uploadSchema({
    image: {
      maxSize: "2MB",
      maxCount: 1,
      processing: {
        resize: { width: 400, height: 400 },
        format: "webp",
      },
    },
  }),

postMedia: uploadSchema({
    image: { maxSize: "8MB", maxCount: 4 },
    video: { maxSize: "100MB", maxCount: 1 },
  }).middleware(async ({ req }) => {
    const userId = await authenticateUser(req);
    return { userId, postType: "media" };
  }),
});
```

## Security Best Practices

<Callout type="warning">
  **Important:** Always implement proper authentication and file validation in
  production environments.
</Callout>

### Content Type Validation

```typescript
export const router = createUploadRouter({
  secureUpload: uploadSchema({
    image: {
      maxSize: "4MB",
      maxCount: 5,
      mimeTypes: ["image/jpeg", "image/png", "image/webp"], // Explicit whitelist
    },
  }).middleware(async ({ req, files }) => {
    // Additional security checks
    for (const file of files) {
      // Validate file headers match content type
      const isValidImage = await validateImageFile(file);
      if (!isValidImage) {
        throw new Error("Invalid image file");
      }
    }

return { userId: await getUserId(req) };
  }),
});
```

### Rate Limiting

```typescript
import { ratelimit } from "@/lib/ratelimit";

export const router = createUploadRouter({
  upload: uploadSchema({
    any: { maxSize: "10MB", maxCount: 3 },
  }).middleware(async ({ req }) => {
    const ip = req.headers.get("x-forwarded-for") || "unknown";

const { success } = await ratelimit.limit(ip);
    if (!success) {
      throw new Error("Rate limit exceeded");
    }

return { ip };
  }),
});
```

***

<Callout type="success">
  **Next Steps:** Now that you have your router configured, learn how to
  [configure your client](/docs/api/configuration/client-options) for the best
  developer experience.
</Callout>

# Upload Configuration (/docs/api/configuration/upload-config)

## Router Configuration Options

The `createUploadConfig()` builder provides a fluent API for configuring your S3 uploads with providers, security, paths, and lifecycle hooks.

## Basic Setup

```typescript title="lib/upload.ts"
// lib/upload.ts
import { createUploadConfig } from 'pushduck/server'

const { storage, s3, config } = createUploadConfig() 
  .provider("cloudflareR2",{ // [!code highlight]
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    region: 'auto',
    endpoint: process.env.AWS_ENDPOINT_URL,
    bucket: process.env.S3_BUCKET_NAME,
    accountId: process.env.R2_ACCOUNT_ID, // [!code highlight]
  })
  .build()

export { storage, s3 }
```

## Provider Configuration

The `createUploadConfig().provider()` method provides full TypeScript type safety for provider configurations. When you specify a provider type, TypeScript will automatically infer the correct configuration interface and provide autocomplete and type checking.

### Features

* **Provider name autocomplete**: TypeScript suggests valid provider names
* **Configuration property validation**: Only valid properties for each provider are accepted
* **Required field checking**: TypeScript ensures all required fields are provided
* **Property type validation**: Each property must be the correct type

## Provider Configuration

### Cloudflare R2

```typescript title="Cloudflare R2 Configuration"
createUploadConfig().provider("cloudflareR2",{ // [!code highlight]
  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  region: 'auto', // Always 'auto' for R2
  endpoint: process.env.AWS_ENDPOINT_URL,
  bucket: process.env.S3_BUCKET_NAME,
  accountId: process.env.R2_ACCOUNT_ID, // Required for R2 // [!code highlight]
  // Optional: Custom domain for public files
  customDomain: process.env.R2_CUSTOM_DOMAIN,
})
```

### AWS S3

```typescript title="AWS S3 Configuration"
createUploadConfig().provider("aws",{ // [!code highlight]
  region: 'us-east-1',
  bucket: 'your-bucket', // [!code highlight]
  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  // Optional: Custom domain for public files (CDN, CloudFront, etc.)
  customDomain: process.env.S3_CUSTOM_DOMAIN,
})
```

### DigitalOcean Spaces

```typescript
createUploadConfig().provider("digitalOceanSpaces",{
  region: 'nyc3',
  bucket: 'your-space',
  accessKeyId: process.env.DO_SPACES_ACCESS_KEY_ID,
  secretAccessKey: process.env.DO_SPACES_SECRET_ACCESS_KEY,
  // Optional: Custom domain for public files (CDN endpoint)
  customDomain: process.env.DO_SPACES_CUSTOM_DOMAIN,
})
```

### MinIO

```typescript
createUploadConfig().provider("minio",{
  endpoint: 'localhost:9000',
  bucket: 'your-bucket',
  accessKeyId: process.env.MINIO_ACCESS_KEY_ID,
  secretAccessKey: process.env.MINIO_SECRET_ACCESS_KEY,
  useSSL: false,
  // Optional: Custom domain for public files
  customDomain: process.env.MINIO_CUSTOM_DOMAIN,
})
```

### S3-Compatible (Generic)

For any S3-compatible storage service not explicitly supported:

```typescript
createUploadConfig().provider("s3Compatible",{
  endpoint: 'https://your-s3-compatible-service.com',
  bucket: 'your-bucket',
  accessKeyId: process.env.S3_ACCESS_KEY_ID,
  secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
  region: 'us-east-1', // Optional, defaults to us-east-1
  forcePathStyle: true, // Optional, defaults to true for compatibility
  // Optional: Custom domain for public files
  customDomain: process.env.S3_CUSTOM_DOMAIN,
})
```

## Configuration Methods

### .defaults()

Set default file constraints and options:

```typescript
.defaults({
  maxFileSize: '10MB',
  allowedFileTypes: ['image/*', 'application/pdf', 'text/*'],
  acl: 'public-read', // or 'private'
  metadata: {
    uploadedBy: 'system',
    environment: process.env.NODE_ENV,
  },
})
```

### .paths()

Configure global path structure:

```typescript
.paths({
  // Global prefix for all uploads
  prefix: 'uploads',
  
  // Global key generation function
  generateKey: (file, metadata) => {
    const userId = metadata.userId || 'anonymous'
    const timestamp = Date.now()
    const randomId = Math.random().toString(36).substring(2, 8)
    const sanitizedName = file.name.replace(/[^a-zA-Z0-9.-]/g, '_')
    
    return `${userId}/${timestamp}/${randomId}/${sanitizedName}`
  },
})
```

### .security()

Configure security and access control:

```typescript
.security({
  requireAuth: true,
  allowedOrigins: [
    'http://localhost:3000',
    'https://your-domain.com',
  ],
  rateLimiting: {
    maxUploads: 10,
    windowMs: 60000, // 1 minute
  },
})
```

### .hooks()

Add lifecycle hooks for upload events:

```typescript
.hooks({
  onUploadStart: async ({ file, metadata }) => {
    console.log(`Upload started: ${file.name}`)
    // Log to analytics, validate user, etc.
  },
  
  onUploadComplete: async ({ file, url, metadata }) => {
    console.log(`✅ Upload completed: ${file.name} -> ${url}`)
    
    // Save to database
    await db.files.create({
      filename: file.name,
      url,
      userId: metadata.userId,
      size: file.size,
    })
    
    // Send notifications
    await notificationService.send({
      type: 'upload_complete',
      userId: metadata.userId,
      filename: file.name,
    })
  },
  
  onUploadError: async ({ file, error, metadata }) => {
    console.error(`❌ Upload failed: ${file.name}`, error)
    
    // Log to error tracking service
    await errorService.log({
      operation: 'file_upload',
      error: error.message,
      userId: metadata.userId,
      filename: file.name,
    })
  },
})
```

## Complete Example

```typescript
// lib/upload.ts
import { createUploadConfig } from 'pushduck/server'

const { storage, s3, config } = createUploadConfig()
  .provider("cloudflareR2",{
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    region: 'auto',
    endpoint: process.env.AWS_ENDPOINT_URL,
    bucket: process.env.S3_BUCKET_NAME,
    accountId: process.env.R2_ACCOUNT_ID,
  })
  .defaults({
    maxFileSize: '10MB',
    acl: 'public-read',
  })
  .paths({
    prefix: 'uploads',
    generateKey: (file, metadata) => {
      const userId = metadata.userId || 'anonymous'
      const date = new Date()
      const year = date.getFullYear()
      const month = String(date.getMonth() + 1).padStart(2, '0')
      const day = String(date.getDate()).padStart(2, '0')
      const randomId = Math.random().toString(36).substring(2, 8)
      
      return `${userId}/${year}/${month}/${day}/${randomId}/${file.name}`
    },
  })
  .security({
    allowedOrigins: [
      'http://localhost:3000',
      'https://your-domain.com',
    ],
    rateLimiting: {
      maxUploads: 20,
      windowMs: 60000,
    },
  })
  .hooks({
    onUploadComplete: async ({ file, url, metadata }) => {
      // Save to your database
      await saveFileRecord({
        filename: file.name,
        url,
        userId: metadata.userId,
        uploadedAt: new Date(),
      })
    },
  })
  .build()

export { storage, s3 }
```

## Environment Variables

The configuration automatically reads from environment variables:

```bash
# .env.local

# Cloudflare R2
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_ENDPOINT_URL=https://your-account-id.r2.cloudflarestorage.com
S3_BUCKET_NAME=your-bucket
R2_ACCOUNT_ID=your-account-id

# AWS S3 (alternative)
AWS_REGION=us-east-1
AWS_S3_BUCKET=your-s3-bucket

# DigitalOcean Spaces (alternative)
DO_SPACES_REGION=nyc3
DO_SPACES_BUCKET=your-space
DO_SPACES_ACCESS_KEY_ID=your_key
DO_SPACES_SECRET_ACCESS_KEY=your_secret

# Custom Domains (Optional)
S3_CUSTOM_DOMAIN=https://cdn.yourdomain.com
DO_SPACES_CUSTOM_DOMAIN=https://cdn.yourdomain.com
MINIO_CUSTOM_DOMAIN=https://uploads.yourdomain.com
GCS_CUSTOM_DOMAIN=https://storage.yourdomain.com
CLOUDFLARE_R2_CUSTOM_DOMAIN=https://uploads.yourdomain.com
```

## Custom Domain Configuration

When `customDomain` is configured, public URLs will use your custom domain instead of the storage provider's default URL. This is useful for:

* **CDN Integration**: Use CloudFront, Cloudflare, or other CDNs
* **Branding**: Serve files from your own domain
* **Performance**: Optimize file delivery with custom caching rules
* **Security**: Control access through your own domain

### How It Works

```typescript
// Without custom domain
file.url = "https://bucket.s3.region.amazonaws.com/path/file.jpg"

// With custom domain
file.url = "https://cdn.yourdomain.com/path/file.jpg"
```

**Note**: Internal operations (upload, delete) still use the storage provider's endpoints. Only public URLs are affected by the custom domain.

## Client Upload Results

After successful upload completion, clients receive file objects with both permanent and temporary URLs:

```typescript
// Client-side usage
const { uploadFiles } = useUploadRoute('fileUpload', {
  onSuccess: (results) => {
    results.forEach(file => {
      console.log('File:', file.name);
      console.log('Public URL:', file.url);           // Permanent access
      console.log('Download URL:', file.presignedUrl); // Temporary access (1 hour)
      console.log('S3 Key:', file.key);               // Object key/path
    });
  }
});
```

### URL Types

* **`url`** - Permanent URL for public file access, CDN caching, and embedding
* **`presignedUrl`** - Temporary download URL (expires in 1 hour) for secure access
* **`key`** - S3 object key/path for direct storage operations

Use the appropriate URL based on your access requirements:

* Public files: Use `url` for permanent access
* Private files: Use `presignedUrl` for time-limited access
* File operations: Use `key` with storage API

## Type Definitions

```typescript
interface UploadConfig {
  provider: ProviderConfig
  defaults?: {
    maxFileSize?: string | number
    allowedFileTypes?: string[]
    acl?: 'public-read' | 'private'
    metadata?: Record<string, any>
  }
  paths?: {
    prefix?: string
    generateKey?: (
      file: { name: string; type: string },
      metadata: any
    ) => string
  }
  security?: {
    requireAuth?: boolean
    allowedOrigins?: string[]
    rateLimiting?: {
      maxUploads?: number
      windowMs?: number
    }
  }
  hooks?: {
    onUploadStart?: (ctx: { file: any; metadata: any }) => Promise<void> | void
    onUploadComplete?: (ctx: {
      file: any
      url: string          // Permanent file URL
      metadata: any
    }) => Promise<void> | void
    onUploadError?: (ctx: {
      file: any
      error: Error
      metadata: any
    }) => Promise<void> | void
  }
}
```

# File Operations (/docs/api/storage/file-operations)

## File Management Operations

## List Operations

### Basic File Listing

```typescript
// List all files
const files = await storage.list.files()

// List with options
const files = await storage.list.files({
  prefix: 'uploads/',
  maxResults: 50,
  sortBy: 'lastModified',
  sortOrder: 'desc'
})
```

### Paginated Listing

```typescript
// Get first page
const result = await storage.list.paginated({
  maxResults: 20,
  prefix: 'images/'
})

console.log(result.files)        // FileInfo[]
console.log(result.hasMore)      // boolean
console.log(result.nextToken)    // string | undefined

// Get next page
if (result.hasMore) {
  const nextPage = await storage.list.paginated({
    maxResults: 20,
    prefix: 'images/',
    continuationToken: result.nextToken
  })
}
```

### Filtered Listing

```typescript
// By file extension
const images = await storage.list.byExtension('jpg', 'photos/')
const pdfs = await storage.list.byExtension('pdf')

// By file size (bytes)
const largeFiles = await storage.list.bySize(1024 * 1024) // > 1MB
const mediumFiles = await storage.list.bySize(100000, 1024 * 1024) // 100KB - 1MB

// By date range
const recent = await storage.list.byDate(
  new Date('2024-01-01'),
  new Date('2024-12-31')
)
```

### Directory Listing

```typescript
// List "directories" (common prefixes)
const dirs = await storage.list.directories('uploads/')
// Returns: ['uploads/images/', 'uploads/documents/', 'uploads/videos/']
```

### Async Generator (Large Datasets)

```typescript
// Process large datasets efficiently
for await (const batch of storage.list.paginatedGenerator({ maxResults: 100 })) {
  console.log(`Processing ${batch.files.length} files`)
  // Process batch...
}
```

## Metadata Operations

### Single File Info

```typescript
const info = await storage.metadata.getInfo('uploads/image.jpg')

console.log(info.key)           // 'uploads/image.jpg'
console.log(info.size)          // 1024000
console.log(info.contentType)   // 'image/jpeg'
console.log(info.lastModified)  // Date object
console.log(info.etag)          // '"abc123..."'
```

### Batch Metadata

```typescript
const keys = ['file1.jpg', 'file2.pdf', 'file3.mp4']
const results = await storage.metadata.getBatch(keys)

results.forEach(result => {
  if (result.success) {
    console.log(result.info.size)
  } else {
    console.log(result.error)
  }
})
```

### Specific Metadata

```typescript
// Get individual properties
const size = await storage.metadata.getSize('file.jpg')
const contentType = await storage.metadata.getContentType('file.jpg')
const lastModified = await storage.metadata.getLastModified('file.jpg')

// Custom metadata
const customMeta = await storage.metadata.getCustom('file.jpg')
await storage.metadata.setCustom('file.jpg', {
  userId: '123',
  category: 'profile-image'
})
```

## Delete Operations

### Single File Delete

```typescript
const result = await storage.delete.file('uploads/old-file.jpg')

if (result.success) {
  console.log('File deleted successfully')
} else {
  console.log('Delete failed:', result.error)
}
```

### Batch Delete

```typescript
const keys = ['file1.jpg', 'file2.pdf', 'file3.mp4']
const result = await storage.delete.files(keys)

console.log(`Deleted: ${result.deleted.length}`)
console.log(`Failed: ${result.errors.length}`)

// Check individual results
result.errors.forEach(error => {
  console.log(`Failed to delete ${error.key}: ${error.message}`)
})
```

### Delete by Prefix (Folder-like)

```typescript
// Delete all files with prefix
const result = await storage.delete.byPrefix('temp-uploads/')

console.log(`Deleted ${result.deletedCount} files`)

// With options
const result = await storage.delete.byPrefix('old-files/', {
  dryRun: true,        // Preview only, don't delete
  batchSize: 500,      // Process in batches
  maxFiles: 1000       // Limit total files
})

if (result.dryRun) {
  console.log(`Would delete ${result.totalFiles} files`)
}
```

## Validation Operations

### File Existence

```typescript
// Simple existence check
const exists = await storage.validation.exists('file.jpg')

// Existence with metadata
const result = await storage.validation.existsWithInfo('file.jpg')
if (result.exists) {
  console.log('File size:', result.info.size)
}
```

### File Validation

```typescript
// Validate single file
const result = await storage.validation.validateFile('image.jpg', {
  max: "5MB",
  types: ['image/jpeg', 'image/png'],
  min: "1KB"
})

if (result.valid) {
  console.log('File is valid')
} else {
  console.log('Validation errors:', result.errors)
}

// Validate multiple files
const results = await storage.validation.validateFiles(
  ['file1.jpg', 'file2.png'],
  { max: "10MB" }
)
```

### Connection Validation

```typescript
// Test S3 connection and permissions
const isHealthy = await storage.validation.connection()
console.log('S3 connection:', isHealthy ? 'OK' : 'Failed')
```

## Type Definitions

```typescript
interface FileInfo {
  key: string
  size: number
  contentType: string
  lastModified: Date
  etag: string
  metadata?: Record<string, string>
}

interface ListFilesOptions {
  prefix?: string
  maxResults?: number
  sortBy?: 'key' | 'size' | 'lastModified'
  sortOrder?: 'asc' | 'desc'
}

interface ValidationRules {
  max?: string | number
  min?: string | number
  types?: string[]
  requiredMetadata?: string[]
}
```

# Storage API (/docs/api/storage)

import { Cards, Card } from "fumadocs-ui/components/card";
import { Callout } from "fumadocs-ui/components/callout";

## Storage API Overview

The Storage API provides direct access to file operations, metadata retrieval, and storage management. Use it for building custom file management interfaces, bulk operations, and advanced storage workflows.

## API Categories

<Cards>
  <Card title="Quick Reference" description="Essential storage operations at a glance with code examples" href="/docs/api/storage/quick-reference">
    **Get started quickly** with common operations.

* File listing and searching
    * Basic upload/download operations
    * Quick delete and metadata operations
    * Essential API patterns

**Perfect for** getting up to speed fast.
  </Card>

<Card title="🏗️ Storage Instance" description="Object-style API for organized storage operations" href="/docs/api/storage/storage-instance">
    **Structured API interface** with organized methods.

* `storage.list.*` - File listing operations
    * `storage.metadata.*` - File information
    * `storage.delete.*` - Deletion operations
    * `storage.download.*` - URL generation

**Great for** organized code architecture.
  </Card>

<Card title="📁 File Operations" description="Comprehensive file management and manipulation" href="/docs/api/storage/file-operations">
    **Complete file management** capabilities.

* List files with filtering and pagination
    * Delete single files or batches
    * Move and copy operations
    * File metadata retrieval

**Essential for** file management features.
  </Card>

<Card title="🔗 Presigned URLs" description="Secure URL generation for direct storage access" href="/docs/api/storage/presigned-urls">
    **Secure, temporary URLs** for storage operations.

* Download presigned URLs
    * Upload presigned URLs
    * Custom expiration times
    * Access control integration

**Perfect for** secure file access.
  </Card>

<Card title="🔧 Troubleshooting" description="Common storage issues and solutions" href="/docs/api/storage/troubleshooting">
    **Debug storage problems** effectively.

* Access denied errors
    * Empty file lists
    * Presigned URL issues
    * Performance optimization

**When you need** to solve problems.
  </Card>
</Cards>

## Getting Started

### Basic Storage Setup

```typescript
// lib/upload.ts
import { createUploadConfig } from 'pushduck/server'

const { storage } = createUploadConfig()
  .provider("cloudflareR2", {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    accountId: process.env.R2_ACCOUNT_ID,
    bucket: process.env.S3_BUCKET_NAME,
  })
  .build()

export { storage }
```

### Using in API Routes

```typescript
// app/api/files/route.ts
import { storage } from '@/lib/upload'

export async function GET() {
  try {
    const files = await storage.list.files()
    return Response.json({ files })
  } catch (error) {
    return Response.json({ error: 'Failed to list files' }, { status: 500 })
  }
}

export async function DELETE(request: Request) {
  const { key } = await request.json()
  
  try {
    await storage.delete.file(key)
    return Response.json({ success: true })
  } catch (error) {
    return Response.json({ error: 'Failed to delete file' }, { status: 500 })
  }
}
```

## Common Operations

### File Listing with Pagination

```typescript
// Get paginated file list
const result = await storage.list.paginated({
  maxResults: 50,
  prefix: 'uploads/',
})

console.log(`Found ${result.files.length} files`)
if (result.hasMore) {
  console.log('More files available')
}
```

### Bulk File Operations

```typescript
// Delete multiple files
const filesToDelete = ['file1.jpg', 'file2.pdf', 'file3.png']
await storage.delete.files(filesToDelete)

// Get metadata for multiple files
const fileInfos = await Promise.all(
  fileKeys.map(key => storage.metadata.getInfo(key))
)
```

### Secure Downloads

```typescript
// Generate secure download URL
const downloadUrl = await storage.download.presignedUrl(
  'private/document.pdf',
  3600 // 1 hour expiration
)

// Use with fetch or window.open
window.open(downloadUrl)
```

## Storage Instance Structure

The storage instance organizes operations into logical namespaces:

```typescript
storage.list.*       // File listing operations
storage.metadata.*   // File metadata operations  
storage.download.*   // Download and URL operations
storage.upload.*     // Upload operations
storage.delete.*     // Delete operations
storage.validation.* // Validation operations
```

## Error Handling

All storage operations use structured error handling:

```typescript
import { isPushduckError } from 'pushduck/server'

try {
  const files = await storage.list.files()
} catch (error) {
  if (isPushduckError(error)) {
    console.log('Storage error:', error.code, error.context)
    
    switch (error.code) {
      case 'ACCESS_DENIED':
        // Handle permission errors
        break
      case 'NETWORK_ERROR':
        // Handle connectivity issues
        break
      default:
        // Handle other errors
    }
  }
}
```

<Callout type="info">
  **TypeScript Support**: All storage operations are fully typed with intelligent autocomplete and error detection.
</Callout>

## Performance Considerations

### Efficient File Listing

```typescript
// ❌ Inefficient - loads all files
const allFiles = await storage.list.files()

// ✅ Efficient - use pagination
const result = await storage.list.paginated({ maxResults: 50 })

// ✅ Even better - filter with prefix
const userFiles = await storage.list.files({ 
  prefix: `users/${userId}/`,
  maxResults: 100 
})
```

### Batch Operations

```typescript
// ❌ Inefficient - multiple API calls
for (const key of fileKeys) {
  await storage.delete.file(key)
}

// ✅ Efficient - single batch operation
await storage.delete.files(fileKeys)
```

***

## Next Steps

* **New to storage?** Start with [Quick Reference](/docs/api/storage/quick-reference)
* **Building file management?** See [File Operations](/docs/api/storage/file-operations)
* **Need secure access?** Check [Presigned URLs](/docs/api/storage/presigned-urls)
* **Having issues?** Visit [Troubleshooting](/docs/api/storage/troubleshooting)

# Presigned URLs (/docs/api/storage/presigned-urls)

## Generating Presigned URLs

Presigned URLs allow secure access to private S3 files without exposing credentials. They're essential for serving files from private buckets.

## Download URLs

### Automatic Download URLs

When files are uploaded through pushduck, download presigned URLs are automatically generated:

```typescript
const { uploadFiles } = useUploadRoute('fileUpload', {
  onSuccess: (results) => {
    results.forEach(file => {
      console.log('Public URL:', file.url);           // Permanent access
      console.log('Download URL:', file.presignedUrl); // Temporary access (1 hour)
    });
  }
});
```

### Manual Presigned URL Generation

You can also generate presigned URLs manually using the storage API:

```typescript
// Generate URL valid for 1 hour (default)
const url = await storage.download.presignedUrl('private/document.pdf')

// Custom expiration (in seconds)
const url = await storage.download.presignedUrl('private/image.jpg', 3600) // 1 hour
const url = await storage.download.presignedUrl('private/video.mp4', 86400) // 24 hours
```

### Direct File URLs

For public buckets, get direct URLs:

```typescript
const publicUrl = await storage.download.url('public/image.jpg')
// Returns: https://bucket.s3.amazonaws.com/public/image.jpg
```

## Upload URLs

### Single Upload URL

```typescript
const uploadUrl = await storage.upload.presignedUrl({
  key: 'uploads/new-file.jpg',
  contentType: 'image/jpeg',
  expiresIn: 300, // 5 minutes
  maxFileSize: 5 * 1024 * 1024 // 5MB
})

console.log(uploadUrl.url)        // Presigned URL for PUT request
console.log(uploadUrl.fields)     // Form fields for multipart upload
```

### Batch Upload URLs

```typescript
const requests = [
  { key: 'file1.jpg', contentType: 'image/jpeg' },
  { key: 'file2.pdf', contentType: 'application/pdf' },
  { key: 'file3.mp4', contentType: 'video/mp4' }
]

const urls = await storage.upload.presignedBatch(requests)

urls.forEach((result, index) => {
  if (result.success) {
    console.log(`Upload URL for ${requests[index].key}:`, result.url)
  } else {
    console.log(`Failed to generate URL:`, result.error)
  }
})
```

## Frontend Usage Examples

### Direct File Access

```typescript
// API Route (app/api/files/[key]/route.ts)
import { storage } from '@/lib/upload'
import { NextRequest, NextResponse } from 'next/server'

export async function GET(
  request: NextRequest,
  { params }: { params: { key: string } }
) {
  try {
    const url = await storage.download.presignedUrl(params.key, 3600)
    return NextResponse.redirect(url)
  } catch (error) {
    return NextResponse.json(
      { error: 'File not found' },
      { status: 404 }
    )
  }
}
```

### File Viewer Component

```tsx
'use client'

import { useState, useEffect } from 'react'

interface FileViewerProps {
  fileKey: string
}

export function FileViewer({ fileKey }: FileViewerProps) {
  const [url, setUrl] = useState<string>()
  const [loading, setLoading] = useState(true)

useEffect(() => {
    async function getUrl() {
      try {
        const response = await fetch('/api/presigned', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ 
            operation: 'get-download-url', 
            key: fileKey 
          })
        })
        
        const data = await response.json()
        if (data.success) {
          setUrl(data.url)
        }
      } finally {
        setLoading(false)
      }
    }

getUrl()
  }, [fileKey])

if (loading) return <div>Loading...</div>
  if (!url) return <div>Failed to load file</div>

return (
    <div>
      <img src={url} alt="File preview" />
      <a href={url} download>Download File</a>
    </div>
  )
}
```

### API Route for Presigned URLs

```typescript
// app/api/presigned/route.ts
import { storage } from '@/lib/upload'
import { NextRequest, NextResponse } from 'next/server'

export async function POST(request: NextRequest) {
  try {
    const { operation, key, expiresIn = 3600 } = await request.json()

switch (operation) {
      case 'get-download-url':
        const downloadUrl = await storage.download.presignedUrl(key, expiresIn)
        return NextResponse.json({
          success: true,
          url: downloadUrl,
          expiresIn
        })

case 'get-upload-url':
        const uploadUrl = await storage.upload.presignedUrl({
          key,
          expiresIn,
          contentType: 'application/octet-stream'
        })
        return NextResponse.json({
          success: true,
          ...uploadUrl
        })

default:
        return NextResponse.json(
          { success: false, error: 'Unknown operation' },
          { status: 400 }
        )
    }
  } catch (error) {
    return NextResponse.json(
      { success: false, error: error.message },
      { status: 500 }
    )
  }
}
```

## Security Considerations

### Expiration Times

Choose appropriate expiration times:

```typescript
// Short-lived for sensitive files
const sensitiveUrl = await storage.download.presignedUrl('private/sensitive.pdf', 300) // 5 minutes

// Medium-lived for user content
const userUrl = await storage.download.presignedUrl('user/profile.jpg', 3600) // 1 hour

// Longer-lived for public content
const publicUrl = await storage.download.presignedUrl('public/banner.jpg', 86400) // 24 hours
```

### Access Control

Implement proper access control before generating URLs:

```typescript
// API Route with authentication
export async function POST(request: NextRequest) {
  // Verify user authentication
  const user = await getAuthenticatedUser(request)
  if (!user) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }

const { key } = await request.json()

// Check if user can access this file
  if (!canUserAccessFile(user.id, key)) {
    return NextResponse.json({ error: 'Forbidden' }, { status: 403 })
  }

// Generate presigned URL
  const url = await storage.download.presignedUrl(key, 3600)
  return NextResponse.json({ url })
}
```

## Type Definitions

```typescript
interface PresignedUrlOptions {
  key: string
  contentType?: string
  expiresIn?: number
  maxFileSize?: number
  metadata?: Record<string, string>
}

interface PresignedUrlResult {
  url: string
  fields?: Record<string, string>
  expiresAt: Date
}
```

# Quick Reference (/docs/api/storage/quick-reference)

## Storage Operations Overview

## Setup

```typescript
// lib/upload.ts
import { createUploadConfig } from 'pushduck/server'

const { storage } = createUploadConfig()
  .provider("cloudflareR2",{
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    region: 'auto',
    endpoint: process.env.AWS_ENDPOINT_URL,
    bucket: process.env.S3_BUCKET_NAME,
    accountId: process.env.R2_ACCOUNT_ID,
  })
  .build()

export { storage }
```

## Essential Operations

### List Files

```typescript
const files = await storage.list.files({ prefix: 'uploads/', maxResults: 50 })
const paginated = await storage.list.paginated({ maxResults: 20 })
const images = await storage.list.byExtension('jpg')
```

### File Info

```typescript
const info = await storage.metadata.getInfo('file.jpg')
const exists = await storage.validation.exists('file.jpg')
```

### Delete Files

```typescript
await storage.delete.file('old-file.jpg')
await storage.delete.files(['file1.jpg', 'file2.pdf'])
await storage.delete.byPrefix('temp/')
```

### Presigned URLs

```typescript
const downloadUrl = await storage.download.presignedUrl('private/file.pdf', 3600)
const uploadUrl = await storage.upload.presignedUrl({ key: 'new-file.jpg', contentType: 'image/jpeg' })
```

## API Route Example

```typescript
// app/api/files/route.ts
import { storage } from '@/lib/upload'

export async function GET() {
  const files = await storage.list.files()
  return Response.json({ files })
}

export async function DELETE(request: Request) {
  const { key } = await request.json()
  const result = await storage.delete.file(key)
  return Response.json(result)
}
```

## Error Handling

```typescript
import { isPushduckError } from 'pushduck/server'

try {
  await storage.list.files()
} catch (error) {
  if (isPushduckError(error)) {
    console.log(error.code, error.context)
  }
}
```

## Types

```typescript
import type { 
  FileInfo, 
  ListFilesOptions, 
  ValidationRules 
} from 'pushduck/server'
```

# Storage Instance (/docs/api/storage/storage-instance)

## Storage API Instance

The `StorageInstance` provides a clean, object-style API for all S3 operations. It groups related operations under namespaces for better discoverability.

## Getting the Storage Instance

The `storage` instance comes from your upload configuration, not created separately:

```typescript
// lib/upload.ts
import { createUploadConfig } from 'pushduck/server'

// Export the storage instance
export { storage }
```

Then use it in your API routes:

```typescript
// app/api/files/route.ts
import { storage } from '@/lib/upload'

export async function GET() {
  const files = await storage.list.files()
  return Response.json({ files })
}
```

## API Structure

The storage instance organizes operations into logical namespaces:

## Configuration Methods

### getConfig()

Get the current configuration (read-only):

```typescript
const config = storage.getConfig()
console.log(config.provider.bucket) // 'my-bucket'
```

### getProviderInfo()

Get provider information:

```typescript
const info = storage.getProviderInfo()
// Returns: { provider: 'aws-s3', bucket: 'my-bucket', region: 'us-east-1' }
```

## Error Handling

All storage operations throw structured `PushduckError` instances:

```typescript
import { isPushduckError } from 'pushduck/server'

try {
  const files = await storage.list.files()
} catch (error) {
  if (isPushduckError(error)) {
    console.log(error.code)     // Error code
    console.log(error.context)  // Additional context
  }
}
```

## TypeScript Support

The storage instance is fully typed. Import types as needed:

```typescript
import type { FileInfo, ListFilesOptions } from 'pushduck/server'

const options: ListFilesOptions = {
  prefix: 'uploads/',
  maxResults: 100
}

const files: FileInfo[] = await storage.list.files(options)
```

# Troubleshooting (/docs/api/storage/troubleshooting)

## Storage Issues and Fixes

## Common Issues

### Access Denied (403 Errors)

**Problem**: Getting 403 errors when listing or accessing files.

**Solutions**:

1. **Check credentials**:

```typescript
// Verify your environment variables are set
console.log('Access Key:', process.env.AWS_ACCESS_KEY_ID?.substring(0, 5) + '...')
console.log('Bucket:', process.env.S3_BUCKET_NAME)
```

2. **Test connection**:

```typescript
const isHealthy = await storage.validation.connection()
if (!isHealthy) {
  console.log('Connection failed - check credentials and permissions')
}
```

3. **Verify bucket permissions**:
   * Ensure your access key has `s3:ListBucket`, `s3:GetObject`, `s3:DeleteObject` permissions
   * For Cloudflare R2, check your API token has the necessary permissions

### Empty File Lists

**Problem**: `storage.list.files()` returns empty array but files exist.

**Solutions**:

1. **Check prefix**:

```typescript
// Try without prefix first
const allFiles = await storage.list.files()
console.log('Total files:', allFiles.length)

// Then with specific prefix
const prefixFiles = await storage.list.files({ prefix: 'uploads/' })
console.log('Prefix files:', prefixFiles.length)
```

2. **Verify bucket name**:

```typescript
const info = storage.getProviderInfo()
console.log('Current bucket:', info.bucket)
```

### Presigned URL Errors

**Problem**: Presigned URLs return 403 or expire immediately.

**Solutions**:

1. **Check expiration time**:

```typescript
// Use longer expiration for testing
const url = await storage.download.presignedUrl('file.jpg', 3600) // 1 hour
```

2. **Verify file exists**:

```typescript
const exists = await storage.validation.exists('file.jpg')
if (!exists) {
  console.log('File does not exist')
}
```

3. **Check bucket privacy settings**:
   * Private buckets require presigned URLs
   * Public buckets can use direct URLs

### Large File Operations Timeout

**Problem**: Operations on large datasets timeout or fail.

**Solutions**:

1. **Use pagination**:

```typescript
// Instead of loading all files at once
const allFiles = await storage.list.files() // ❌ May timeout

// Use pagination
const result = await storage.list.paginated({ maxResults: 100 }) // ✅ Better
```

2. **Use async generators for processing**:

```typescript
for await (const batch of storage.list.paginatedGenerator({ maxResults: 50 })) {
  console.log(`Processing ${batch.files.length} files`)
  // Process batch...
}
```

3. **Batch operations**:

```typescript
// Delete files in batches
const filesToDelete = ['file1.jpg', 'file2.jpg', /* ... many files */]
const batchSize = 100

for (let i = 0; i < filesToDelete.length; i += batchSize) {
  const batch = filesToDelete.slice(i, i + batchSize)
  await storage.delete.files(batch)
}
```

## Error Handling Patterns

### Graceful Degradation

```typescript
async function getFilesSafely() {
  try {
    const files = await storage.list.files()
    return { success: true, files }
  } catch (error) {
    if (isPushduckError(error)) {
      console.log('Storage error:', error.code, error.context)
      
      // Handle specific error types
      if (error.code === 'NETWORK_ERROR') {
        return { success: false, error: 'Network connection failed', files: [] }
      }
      
      if (error.code === 'ACCESS_DENIED') {
        return { success: false, error: 'Access denied', files: [] }
      }
    }
    
    // Fallback for unknown errors
    return { success: false, error: 'Unknown error', files: [] }
  }
}
```

### Retry Logic

```typescript
async function withRetry<T>(
  operation: () => Promise<T>,
  maxRetries = 3,
  delay = 1000
): Promise<T> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await operation()
    } catch (error) {
      if (attempt === maxRetries) throw error
      
      console.log(`Attempt ${attempt} failed, retrying in ${delay}ms...`)
      await new Promise(resolve => setTimeout(resolve, delay))
      delay *= 2 // Exponential backoff
    }
  }
  
  throw new Error('Max retries exceeded')
}

// Usage
const files = await withRetry(() => storage.list.files())
```

## Performance Optimization

### Efficient File Listing

```typescript
// ❌ Inefficient - loads all metadata
const files = await storage.list.files()

// ✅ Efficient - only get what you need
const files = await storage.list.files({
  maxResults: 50,
  sortBy: 'lastModified',
  sortOrder: 'desc'
})

// ✅ Even better - use pagination for large datasets
const result = await storage.list.paginated({ maxResults: 20 })
```

### Batch Metadata Retrieval

```typescript
// ❌ Inefficient - multiple API calls
const fileInfos = []
for (const key of fileKeys) {
  const info = await storage.metadata.getInfo(key)
  fileInfos.push(info)
}

// ✅ Efficient - single batch call
const fileInfos = await storage.metadata.getBatch(fileKeys)
```

### Smart Caching

```typescript
// Cache file lists for a short time
const cache = new Map()

async function getCachedFiles(prefix?: string) {
  const cacheKey = `files:${prefix || 'all'}`
  
  if (cache.has(cacheKey)) {
    const { data, timestamp } = cache.get(cacheKey)
    if (Date.now() - timestamp < 60000) { // 1 minute cache
      return data
    }
  }
  
  const files = await storage.list.files({ prefix })
  cache.set(cacheKey, { data: files, timestamp: Date.now() })
  
  return files
}
```

## Debugging Tips

### Enable Debug Logging

```typescript
// Check if debug mode is enabled in your config
const config = storage.getConfig()
console.log('Debug mode:', config.provider.debug)

// The storage operations will log detailed information when debug is true
```

### Inspect Configuration

```typescript
// Check your current configuration
const config = storage.getConfig()
console.log('Provider:', config.provider.provider)
console.log('Bucket:', config.provider.bucket)
console.log('Region:', config.provider.region)

// Check provider info
const info = storage.getProviderInfo()
console.log('Provider info:', info)
```

### Test Individual Operations

```typescript
// Test each operation individually
console.log('Testing connection...')
const isHealthy = await storage.validation.connection()
console.log('Connection:', isHealthy ? 'OK' : 'Failed')

console.log('Testing file listing...')
const files = await storage.list.files({ maxResults: 1 })
console.log('Files found:', files.length)

console.log('Testing file existence...')
if (files.length > 0) {
  const exists = await storage.validation.exists(files[0].key)
  console.log('First file exists:', exists)
}
```

## Getting Help

If you're still experiencing issues:

1. **Check the logs** - Look for detailed error messages in your console
2. **Verify environment variables** - Ensure all required variables are set
3. **Test with minimal configuration** - Start with basic setup and add complexity gradually
4. **Check provider documentation** - Verify your bucket/account settings
5. **Use health check** - Run `storage.validation.connection()` to verify basic connectivity

# Authentication (/docs/guides/security/authentication)

## Authentication & Authorization

Secure your file upload endpoints with robust authentication and authorization middleware.

<Callout type="warning">
  **Important:** Never expose upload endpoints without proper authentication in
  production. Unprotected endpoints can lead to storage abuse and security
  vulnerabilities.
</Callout>

## Authentication Patterns

### Better Auth (Recommended)

Modern, type-safe authentication with native TypeScript support:

```typescript
import { s3 } from "@/lib/upload";
import { auth } from "@/lib/auth"; // Better Auth instance

const s3Router = s3.createRouter({
  userFiles: s3.image()
    .maxFileSize("5MB")
    .maxFiles(10)
    .middleware(async ({ req, metadata }) => {
      const session = await auth.api.getSession({ headers: req.headers });

if (!session?.user?.id) {
        throw new Error("Authentication required");
      }

return {
        ...metadata,
        userId: session.user.id,
        userEmail: session.user.email,
      };
    }),
});

export const { GET, POST } = s3Router.handlers;
```

### NextAuth.js Integration

```typescript
import { s3 } from "@/lib/upload";
import { getServerSession } from "next-auth";
import { authOptions } from "@/lib/auth";

const s3Router = s3.createRouter({
  userFiles: s3.image()
    .maxFileSize("5MB")
    .maxFiles(10)
    .middleware(async ({ req, metadata }) => {
      const session = await getServerSession(authOptions);

if (!session?.user?.id) {
        throw new Error("Authentication required");
      }

return {
        ...metadata,
        userId: session.user.id,
        userEmail: session.user.email,
      };
    }),
});

export const { GET, POST } = s3Router.handlers;
```

### JWT Token Validation

```typescript
import jwt from "jsonwebtoken";

const s3Router = s3.createRouter({
  protectedUploads: s3.file()
    .maxFileSize("10MB")
    .maxFiles(5)
    .middleware(async ({ req, metadata }) => {
      const token = req.headers.get("authorization")?.replace("Bearer ", "");

if (!token) {
        throw new Error("Authorization token required");
      }

try {
        const payload = jwt.verify(token, process.env.JWT_SECRET!) as any;

return {
          ...metadata,
          userId: payload.sub,
          roles: payload.roles || [],
        };
      } catch (error) {
        throw new Error("Invalid or expired token");
      }
    }),
});
```

### Custom Authentication

```typescript
const s3Router = s3.createRouter({
  apiKeyUploads: s3.file()
    .maxFileSize("25MB")
    .maxFiles(1)
    .accept(['application/pdf', 'application/msword'])
    .middleware(async ({ req, metadata }) => {
      const apiKey = req.headers.get("x-api-key");

if (!apiKey) {
        throw new Error("API key required");
      }

// Validate API key against your database
      const client = await validateApiKey(apiKey);

if (!client) {
        throw new Error("Invalid API key");
      }

return {
        ...metadata,
        clientId: client.id,
        plan: client.plan,
        quotaUsed: client.quotaUsed,
      };
    }),
});
```

## Simple Role Checking

For apps with admins vs regular users:

```typescript
const s3Router = s3.createRouter({
  adminUploads: s3.file()
    .maxFileSize("100MB")
    .middleware(async ({ req, metadata }) => {
      const { userId, role } = await authenticateUser(req);
      
      if (role !== "admin") {
        throw new Error("Admin access required");
      }
      
      return { ...metadata, userId, role };
    }),
});
```

That's it! For more complex permissions (multi-tenant, resource-based), see [advanced patterns](/docs/api/configuration/server-router#middleware).

***

## Next Steps

<Cards>
  <Card title="CORS Setup" href="/docs/guides/security/cors-and-acl">
    Configure cross-origin requests for your S3 bucket
  </Card>

<Card title="Production Checklist" href="/docs/guides/production-checklist">
    8 essential items to go live safely
  </Card>

<Card title="Client Metadata" href="/docs/guides/client-metadata">
    Pass context from UI to server securely
  </Card>
</Cards>

# CORS & ACL Setup (/docs/guides/security/cors-and-acl)

## CORS & ACL Setup

This guide covers Cross-Origin Resource Sharing (CORS) configuration for file uploads and provides an overview of Access Control Lists (ACLs) across different cloud storage providers.

## Table of Contents

* [CORS Configuration](#cors-configuration)
* [Understanding ACLs](#understanding-acls)
* [Provider-Specific Considerations](#provider-specific-considerations)
* [Common Issues & Troubleshooting](#common-issues--troubleshooting)

## CORS Configuration

Cross-Origin Resource Sharing (CORS) is essential for allowing your web application to upload files directly to cloud storage from the browser.

### Why CORS is Required

When uploading files directly from the browser to cloud storage, you're making requests from your domain (e.g., `https://myapp.com`) to a different domain (e.g., `https://mybucket.s3.amazonaws.com`). Browsers block these cross-origin requests by default unless the target server explicitly allows them via CORS headers.

### Basic CORS Configuration

#### AWS S3 CORS Configuration

```json
[
  {
    "AllowedHeaders": [
      "*"
    ],
    "AllowedMethods": [
      "GET",
      "PUT",
      "POST",
      "DELETE",
      "HEAD"
    ],
    "AllowedOrigins": [
      "https://yourdomain.com",
      "https://www.yourdomain.com"
    ],
    "ExposeHeaders": [
      "ETag",
      "x-amz-meta-custom-header"
    ],
    "MaxAgeSeconds": 3000
  }
]
```

#### Setting CORS via AWS CLI

```bash
# Save the above JSON to cors-config.json
aws s3api put-bucket-cors \
  --bucket your-bucket-name \
  --cors-configuration file://cors-config.json
```

#### Setting CORS via AWS Console

1. Go to S3 Console → Your Bucket → Permissions
2. Scroll to "Cross-origin resource sharing (CORS)"
3. Click "Edit" and paste your CORS configuration
4. Save changes

### Development vs Production CORS

#### Development Configuration (Permissive)

```json
[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
    "AllowedOrigins": [
      "http://localhost:3000",
      "http://localhost:3001",
      "http://127.0.0.1:3000",
      "https://yourdomain.com"
    ],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3000
  }
]
```

#### Production Configuration (Restrictive)

```json
[
  {
    "AllowedHeaders": [
      "Content-Type",
      "Content-MD5",
      "Authorization",
      "x-amz-date",
      "x-amz-content-sha256"
    ],
    "AllowedMethods": ["PUT", "POST"],
    "AllowedOrigins": [
      "https://yourdomain.com",
      "https://www.yourdomain.com"
    ],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 86400
  }
]
```

### Provider-Specific CORS Setup

#### Cloudflare R2

```json
[
  {
    "AllowedOrigins": ["https://yourdomain.com"],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE"],
    "AllowedHeaders": ["*"],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3600
  }
]
```

Set via Cloudflare Dashboard:

1. Go to R2 Object Storage → Your Bucket
2. Navigate to Settings → CORS policy
3. Add your CORS rules

#### DigitalOcean Spaces

```json
[
  {
    "AllowedOrigins": ["https://yourdomain.com"],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
    "AllowedHeaders": ["*"],
    "ExposeHeaders": ["ETag", "x-amz-meta-*"],
    "MaxAgeSeconds": 3600
  }
]
```

Set via DigitalOcean Control Panel:

1. Go to Spaces → Your Space → Settings
2. Add CORS configuration

#### MinIO (Self-Hosted)

```bash
# Using MinIO Client (mc)
mc admin config set myminio api cors_allow_origin="https://yourdomain.com"
mc admin service restart myminio
```

Or via MinIO Console:

1. Access MinIO Console → Buckets → Your Bucket
2. Navigate to Anonymous → Access Rules
3. Configure CORS policy

### Advanced CORS Configurations

#### Multiple Environment Setup

```json
[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["PUT", "POST"],
    "AllowedOrigins": [
      "https://yourdomain.com",
      "https://staging.yourdomain.com"
    ],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 86400
  },
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET"],
    "AllowedOrigins": ["*"],
    "MaxAgeSeconds": 3600
  }
]
```

#### CDN Integration

When using CloudFront or other CDNs:

```json
[
  {
    "AllowedHeaders": [
      "Origin",
      "Access-Control-Request-Method",
      "Access-Control-Request-Headers"
    ],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
    "AllowedOrigins": [
      "https://yourdomain.com",
      "https://d1234567890.cloudfront.net"
    ],
    "ExposeHeaders": ["ETag", "x-amz-version-id"],
    "MaxAgeSeconds": 86400
  }
]
```

### Testing CORS Configuration

#### Browser Developer Tools

1. Open your web app
2. Try uploading a file
3. Check Network tab for CORS errors
4. Look for preflight OPTIONS requests

#### Command Line Testing

```bash
# Test preflight request
curl -X OPTIONS \
  -H "Origin: https://yourdomain.com" \
  -H "Access-Control-Request-Method: PUT" \
  -H "Access-Control-Request-Headers: Content-Type" \
  https://yourbucket.s3.amazonaws.com/

# Should return CORS headers if configured correctly
```

#### Programmatic Testing

```javascript
// Test CORS from browser console
fetch('https://yourbucket.s3.amazonaws.com/', {
  method: 'OPTIONS',
  headers: {
    'Origin': window.location.origin,
    'Access-Control-Request-Method': 'PUT'
  }
})
.then(response => {
  console.log('CORS Headers:', response.headers);
})
.catch(error => {
  console.error('CORS Error:', error);
});
```

## Understanding ACLs

Access Control Lists (ACLs) define who can access your uploaded files and what permissions they have. **Important: ACL implementation varies significantly across providers.**

### What are ACLs?

ACLs are permission sets that determine:

* **Who** can access files (users, groups, public)
* **What** they can do (read, write, delete)
* **How** permissions are inherited

### Common ACL Types

#### Public Access Levels

* **`public-read`**: Anyone can download the file
* **`public-read-write`**: Anyone can download and upload
* **`private`**: Only bucket owner has access
* **`authenticated-read`**: Only authenticated users can read

#### AWS S3 ACL Examples

```typescript
// Using PushDuck with S3 ACLs
const uploadConfig = createUploadConfig({
  provider: s3({
    bucket: "my-bucket",
    region: "us-east-1",
    acl: "public-read" // File will be publicly accessible
  }),
  // ... other config
});
```

### Provider-Specific ACL Differences

#### AWS S3

* **Full ACL Support**: Comprehensive ACL system
* **Canned ACLs**: Predefined permission sets
* **Custom ACLs**: Granular user/group permissions
* **Bucket Policies**: Override ACL settings

```typescript
// S3 supports traditional ACLs
const s3Config = s3({
  bucket: "my-bucket",
  acl: "public-read", // ✅ Supported
  // Custom ACL with specific permissions
  customAcl: {
    Owner: { ID: "owner-id", DisplayName: "Owner" },
    Grants: [
      {
        Grantee: { Type: "Group", URI: "http://acs.amazonaws.com/groups/global/AllUsers" },
        Permission: "READ"
      }
    ]
  }
});
```

#### Cloudflare R2

* **Limited ACL Support**: Basic public/private only
* **No Canned ACLs**: Doesn't support AWS-style ACL names
* **Bucket-Level Permissions**: Access controlled at bucket level

```typescript
// R2 has limited ACL support
const r2Config = cloudflareR2({
  bucket: "my-bucket",
  // ❌ acl: "public-read" // Not supported
  // Access controlled via Cloudflare dashboard or API
});
```

#### DigitalOcean Spaces

* **S3-Compatible ACLs**: Supports most S3 ACL types
* **Public/Private Toggle**: Simple public access control
* **CDN Integration**: Automatic CDN for public files

```typescript
// Spaces supports basic S3 ACLs
const spacesConfig = digitalOceanSpaces({
  bucket: "my-space",
  acl: "public-read", // ✅ Supported
  region: "nyc3"
});
```

#### MinIO (Self-Hosted)

* **Policy-Based**: Uses bucket policies instead of ACLs
* **No Traditional ACLs**: Custom permission system
* **IAM Integration**: Role-based access control

```typescript
// MinIO uses policies, not ACLs
const minioConfig = minio({
  endpoint: "https://minio.yourdomain.com",
  bucket: "my-bucket",
  // ❌ acl: "public-read" // Not supported
  // Access controlled via MinIO policies
});
```

### ACL Best Practices

#### Security Considerations

1. **Default to Private**: Start with `private` ACL
2. **Explicit Public Access**: Only make files public when necessary
3. **Regular Audits**: Review public files periodically
4. **Bucket Policies**: Use bucket policies for complex permissions

#### Implementation Strategy

```typescript
// Environment-based ACL configuration
const getAcl = () => {
  if (process.env.NODE_ENV === 'development') {
    return 'public-read'; // Easy testing
  }
  
  if (process.env.FILE_TYPE === 'profile-images') {
    return 'public-read'; // Profile images need public access
  }
  
  return 'private'; // Default to private
};

const uploadConfig = createUploadConfig({
  provider: s3({
    bucket: process.env.S3_BUCKET!,
    acl: getAcl()
  })
});
```

## Provider-Specific Considerations

### AWS S3

* **Bucket Policies Override ACLs**: Bucket policies take precedence
* **Block Public Access**: May prevent ACL-based public access
* **IAM Permissions**: Required for ACL operations

### Cloudflare R2

* **Dashboard Configuration**: Set public access via Cloudflare dashboard
* **Custom Domains**: Use custom domains for public files
* **Workers Integration**: Use Cloudflare Workers for access control

### DigitalOcean Spaces

* **CDN Integration**: Automatic CDN for public files
* **Subdomain Access**: Public files accessible via subdomain
* **CORS + ACL**: Both required for browser uploads

### MinIO

* **Policy-Only**: No ACL support, use bucket policies
* **Admin Configuration**: Set policies via MinIO admin
* **Custom Authentication**: Integrate with your auth system

## Common Issues & Troubleshooting

### CORS Issues

#### Symptom: "CORS policy" errors in browser console

**Solution:**

1. Check CORS configuration includes your domain
2. Verify all required methods are allowed
3. Ensure preflight requests are handled

```bash
# Debug CORS with curl
curl -X OPTIONS \
  -H "Origin: https://yourdomain.com" \
  -H "Access-Control-Request-Method: PUT" \
  -v https://yourbucket.s3.amazonaws.com/
```

#### Symptom: Uploads work locally but fail in production

**Solution:**

1. Add production domain to CORS origins
2. Check for HTTPS vs HTTP mismatches
3. Verify subdomain configurations

### ACL Issues

#### Symptom: Files uploaded but not accessible

**Solution:**

1. Check if bucket has "Block Public Access" enabled
2. Verify ACL permissions match requirements
3. Review bucket policies for conflicts

#### Symptom: ACL settings ignored

**Solution:**

1. Provider may not support ACLs (R2, MinIO)
2. Bucket policies may override ACL settings
3. Check IAM permissions for ACL operations

### Mixed Issues

#### Symptom: Uploads succeed but files have wrong permissions

**Solution:**

```typescript
// Ensure ACL is set correctly for your provider
const config = createUploadConfig({
  provider: s3({
    bucket: "my-bucket",
    acl: "public-read", // Only for S3-compatible providers
  }),
  onUploadComplete: async ({ file, url }) => {
    // Verify file accessibility
    const response = await fetch(url, { method: 'HEAD' });
    if (!response.ok) {
      console.error('File not publicly accessible:', response.status);
    }
  }
});
```

### Debug Checklist

* [ ] CORS configuration includes all required origins
* [ ] All HTTP methods needed are allowed
* [ ] Headers match what your client sends
* [ ] ACL settings match provider capabilities
* [ ] Bucket policies don't conflict with ACLs
* [ ] IAM permissions allow required operations
* [ ] Block Public Access settings reviewed
* [ ] CDN/proxy configurations considered

### Provider Support Matrix

| Feature         | AWS S3 | Cloudflare R2 | DigitalOcean Spaces | MinIO      |
| --------------- | ------ | ------------- | ------------------- | ---------- |
| CORS            | ✅ Full | ✅ Full        | ✅ Full              | ✅ Full     |
| Canned ACLs     | ✅ Yes  | ❌ No          | ✅ Limited           | ❌ No       |
| Custom ACLs     | ✅ Yes  | ❌ No          | ❌ No                | ❌ No       |
| Bucket Policies | ✅ Yes  | ✅ Yes         | ❌ No                | ✅ Yes      |
| Public Access   | ✅ Yes  | ✅ Dashboard   | ✅ Yes               | ✅ Policies |

This guide should help you configure CORS properly and understand how ACLs work differently across providers. Remember to test your configuration thoroughly in both development and production environments.

Upload Errors:

Upload Images

Enhanced UI

Custom Validation

Other Providers

Enhanced Client

File Upload Demo

Profile Picture

Documents

Images

Videos

Documents

Images

Videos

Documents

Image Upload

Document Upload

Image Upload

Document Upload

File Upload Demo

My Files

Uploaded Files

{file.name}

Image Upload

Document Upload

File Upload Demo

My Files

Uploaded Files

{file.name}

File Upload Demo

File Upload Demo

Image Upload

Document Upload

My Files

Uploaded Files

Image Upload

Document Upload

File Upload Demo

My Files

Uploaded Files

{{ file.name }}

Image Upload

Document Upload

File Upload Demo

My Files

Uploaded Files

{file.name}

Upload Files