API Reference

Complete API reference for pushduck - from client hooks to server configuration and storage operations

Complete API Documentation

Complete reference documentation for all pushduck APIs, from client-side hooks to server configuration and storage operations.

Type-Safe by Design: All pushduck APIs are built with TypeScript-first design, providing excellent developer experience with full type inference and autocompletion.

Client APIs

React Hooks

Reactive hooks for file uploads with built-in state management

useUpload - Core upload hook with progress tracking
useUploadRoute - Route-specific uploads with validation

Perfect for: React applications, reactive UIs

Upload Client

Property-based client for structured upload access

createUploadClient - Type-safe upload client
Property-based route access
Enhanced type inference

Perfect for: Complex applications, better DX

Server Configuration

Upload Configuration

Configure upload behavior, validation, and storage

Route definitions and validation
File type and size restrictions
Custom naming strategies

Essential for: Setting up upload routes

Server Router

Configure the server-side upload router

Router configuration options
Middleware integration
Advanced routing patterns

Essential for: Server setup and customization

Client Options

Configure client-side behavior and defaults

Default upload options
Error handling configuration
Progress tracking settings

Essential for: Client-side configuration

Path Configuration

Configure file paths and naming patterns

Dynamic path generation
Custom naming strategies
Folder organization

Essential for: File organization

Server APIs

S3 Router

Create type-safe upload routes with validation

Route definition and configuration
Built-in validation and middleware
Type-safe request/response handling

Core API: The heart of pushduck

Storage Operations

Direct storage API for file management

File listing and metadata
Delete operations
Presigned URL generation

Perfect for: File management features

Developer Tools

CLI Reference

Command-line tools for setup and development

Project initialization
Component generation
Development utilities

Perfect for: Quick setup and scaffolding

Troubleshooting

Common issues and debugging guides

Error diagnosis and solutions
Performance optimization
Common gotchas and fixes

Essential for: Problem solving

Quick Reference

Basic Server Setup

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

const uploadRouter = createS3Router({
  storage: {
    provider: 'aws-s3',
    region: 'us-east-1',
    bucket: 'my-bucket',
    credentials: {
      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    },
  },
  routes: {
    imageUpload: s3.image().maxFileSize("5MB"),
    documentUpload: s3.file().maxFileSize("10MB"),
  },
});

export const { GET, POST } = uploadRouter.handlers;

Basic Client Usage

import { useUpload } from 'pushduck/client';

function UploadComponent() {
  const { upload, uploading, progress } = useUpload({
    endpoint: '/api/upload',
    route: 'imageUpload',
  });

  const handleUpload = async (file: File) => {
    const result = await upload(file);
    console.log('Public URL:', result.url);           // Permanent access
    console.log('Download URL:', result.presignedUrl); // Temporary access (1 hour)
  };

  return (
    <div>
      <input type="file" onChange={(e) => handleUpload(e.target.files![0])} />
      {uploading && <div>Progress: {progress}%</div>}
    </div>
  );
}

Architecture Overview

Getting Started: New to pushduck? Start with the Quick Start guide, then explore the specific APIs you need for your use case.

API Categories

Category	Purpose	Best For
Client APIs	Frontend file uploads	React components, user interactions
Server APIs	Backend upload handling	Route definitions, validation
Storage APIs	File management	Listing, deleting, URL generation
Configuration	Setup and customization	Project configuration, advanced features
Developer Tools	Development workflow	Setup, debugging, optimization

Next Steps

New to pushduck? → Start with Quick Start
Setting up uploads? → Check S3 Router
Building UI? → Explore React Hooks
Managing files? → Use Storage API
Need help? → Visit Troubleshooting