Skip to content
Uploadista Docs

Installation

This guide will walk you through installing Uploadista SDK packages for your project. Uploadista follows a modular architecture, so you only install what you need.

Prerequisites

Section titled “Prerequisites”

Before installing Uploadista, ensure you have:

  • Node.js 24.10.0 or higher
  • npm, yarn, or pnpm package manager

Package Overview

Section titled “Package Overview”

Uploadista SDK is organized into several categories of packages:

Core Packages

Section titled “Core Packages”

Required for all Uploadista implementations:

  npm install @uploadista/core @uploadista/server
  • @uploadista/core - Upload engine, flow engine, and core types
  • @uploadista/server - Server utilities, auth context, and middleware

Client SDKs

Section titled “Client SDKs”

Choose the client SDK that matches your frontend framework:

React

Section titled “React”
npm install @uploadista/react

Vue 3

Section titled “Vue 3”
npm install @uploadista/vue

React Native / Expo

Section titled “React Native / Expo”
npm install @uploadista/expo

Vanilla JavaScript (browser)

Section titled “Vanilla JavaScript (browser)”
npm install @uploadista/client-browser

All client SDKs are built on top of:

  • @uploadista/client-core - Core client logic (automatically installed as dependency)

Server Adapters

Section titled “Server Adapters”

Choose the adapter for your HTTP framework:

Section titled “Hono (recommended for Cloudflare Workers)”
npm install @uploadista/adapters-hono

Express

Section titled “Express”
npm install @uploadista/adapters-express

Fastify

Section titled “Fastify”
npm install @uploadista/adapters-fastify

Data Stores (File Storage)

Section titled “Data Stores (File Storage)”

Choose one or more storage backends where files will be stored:

AWS S3 / Cloudflare R2

Section titled “AWS S3 / Cloudflare R2”
npm install @uploadista/data-store-s3

Azure Blob Storage

Section titled “Azure Blob Storage”
npm install @uploadista/data-store-azure

Google Cloud Storage

Section titled “Google Cloud Storage”
npm install @uploadista/data-store-gcs

Local filesystem (development)

Section titled “Local filesystem (development)”
npm install @uploadista/data-store-filesystem

KV Stores (Metadata & State)

Section titled “KV Stores (Metadata & State)”

Choose a KV store for managing upload metadata and flow job state:

Redis

Section titled “Redis”
npm install @uploadista/kv-store-redis

IORedis (with clustering support)

Section titled “IORedis (with clustering support)”
npm install @uploadista/kv-store-ioredis

Cloudflare KV (edge)

Section titled “Cloudflare KV (edge)”
npm install @uploadista/kv-store-cloudflare-kv

Cloudflare Durable Objects (edge)

Section titled “Cloudflare Durable Objects (edge)”
npm install @uploadista/kv-store-cloudflare-do

In-memory (development only)

Section titled “In-memory (development only)”
npm install @uploadista/kv-store-memory

Filesystem (development)

Section titled “Filesystem (development)”
npm install @uploadista/kv-store-filesystem

Event System

Section titled “Event System”

Optional packages for real-time progress updates:

WebSocket event emitter

Section titled “WebSocket event emitter”
npm install @uploadista/event-emitter-websocket

Durable Object event emitter

Section titled “Durable Object event emitter”
npm install @uploadista/event-emitter-durable-object

Redis pub/sub broadcaster

Section titled “Redis pub/sub broadcaster”
npm install @uploadista/event-broadcaster-redis

IORedis pub/sub broadcaster

Section titled “IORedis pub/sub broadcaster”
npm install @uploadista/event-broadcaster-ioredis

In-memory broadcaster (development)

Section titled “In-memory broadcaster (development)”
npm install @uploadista/event-broadcaster-memory

Flow Processing Nodes

Section titled “Flow Processing Nodes”

Optional packages for building file processing pipelines:

Utility nodes (conditional, merge, multiplex, zip)

Section titled “Utility nodes (conditional, merge, multiplex, zip)”
npm install @uploadista/flow-utility-nodes

Image processing nodes

Section titled “Image processing nodes”
npm install @uploadista/flow-images-nodes

Sharp-based image processing (Node.js)

Section titled “Sharp-based image processing (Node.js)”
npm install @uploadista/flow-images-sharp

Photon-based image processing (Edge/WASM)

Section titled “Photon-based image processing (Edge/WASM)”
npm install @uploadista/flow-images-photon

AI image processing via Replicate API

Section titled “AI image processing via Replicate API”
npm install @uploadista/flow-images-replicate

ZIP file utilities

Section titled “ZIP file utilities”
npm install @uploadista/flow-utility-zipjs

Installation Examples

Section titled “Installation Examples”

Basic Server Setup (Express + S3 + Redis)

Section titled “Basic Server Setup (Express + S3 + Redis)”
npm install @uploadista/core @uploadista/server \
@uploadista/adapters-express \
@uploadista/data-store-s3 \
@uploadista/kv-store-redis

Full-Stack React App (Hono + S3 + Redis)

Section titled “Full-Stack React App (Hono + S3 + Redis)”
# Server
npm install @uploadista/core @uploadista/server \
@uploadista/adapters-hono \
@uploadista/data-store-s3 \
@uploadista/kv-store-redis


# Client
npm install @uploadista/react

Edge Deployment (Cloudflare Workers)

Section titled “Edge Deployment (Cloudflare Workers)”
npm install @uploadista/core @uploadista/server \
@uploadista/adapters-hono \
@uploadista/data-store-s3 \
@uploadista/kv-store-cloudflare-kv \
@uploadista/event-emitter-durable-object

Development Setup (Local Storage)

Section titled “Development Setup (Local Storage)”
npm install @uploadista/core @uploadista/server \
@uploadista/adapters-hono \
@uploadista/data-store-filesystem \
@uploadista/kv-store-memory

Image Processing Pipeline

Section titled “Image Processing Pipeline”
# Add to your existing server setup
npm install @uploadista/flow-images-nodes \
@uploadista/flow-images-sharp \
@uploadista/flow-utility-nodes

TypeScript Configuration

Section titled “TypeScript Configuration”

Uploadista is built with TypeScript and requires TypeScript 5.9 or higher. Add the following to your tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true
  }
}

Environment Variables

Section titled “Environment Variables”

Depending on your chosen packages, you’ll need to configure environment variables. Here are common examples:

AWS S3

Section titled “AWS S3”
Terminal window
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=us-east-1
AWS_S3_BUCKET=your-bucket-name

Azure Blob Storage

Section titled “Azure Blob Storage”
Terminal window
AZURE_STORAGE_ACCOUNT=your_account_name
AZURE_STORAGE_KEY=your_account_key
AZURE_CONTAINER_NAME=your-container

Google Cloud Storage

Section titled “Google Cloud Storage”
Terminal window
GCS_PROJECT_ID=your-project-id
GCS_BUCKET_NAME=your-bucket-name
GCS_CREDENTIALS_PATH=./credentials.json

Redis

Section titled “Redis”
Terminal window
REDIS_URL=redis://localhost:6379

Cloudflare KV

Section titled “Cloudflare KV”
Terminal window
# Configured in wrangler.toml
[[kv_namespaces]]
binding = "UPLOADISTA_KV"
id = "your-kv-namespace-id"

Verification

Section titled “Verification”

After installation, verify your setup by checking installed versions:

Terminal window
npm list @uploadista/core

You should see output similar to:

your-project@1.0.0
└── @uploadista/core@1.0.0

Next Steps

Section titled “Next Steps”

Now that you have Uploadista installed, proceed to the Basic Usage guide to learn how to configure and use the SDK in your application.

Package Registry

Section titled “Package Registry”

All Uploadista packages are published to the npm registry under the @uploadista scope. You can browse available packages at:

Getting Help

Section titled “Getting Help”

If you encounter issues during installation: