Uploadista Server

What is the Uploadista Server?

The Uploadista Server is your single entry point for file uploads and processing. It combines:

Upload Engine - Handles file uploads, chunking, and resumability
Flows Engine - Processes files (resize, optimize, transform)
Plugins - Add capabilities like image processing, virus scanning
Framework Adapters - Connect to Hono, Express, or Fastify

You create one server instance with createUploadistaServer(), configure it once, and it handles everything.

Quick Start

import { createUploadistaServer } from "@uploadista/server";
import { s3Store } from "@uploadista/data-store-s3";
import { redisKvStore } from "@uploadista/kv-store-redis";
import { honoAdapter } from "@uploadista/adapters-hono";

const uploadista = await createUploadistaServer({
  // Where files are stored (required)
  dataStore: s3Store({
    deliveryUrl: "https://cdn.example.com",
    s3ClientConfig: { bucket: "uploads", region: "us-east-1" },
  }),

  // Where metadata is stored (required)
  kvStore: redisKvStore({ redis }),

  // Framework adapter (required)
  adapter: honoAdapter(),
});

// Returns:
// - uploadista.handler      → HTTP request handler
// - uploadista.websocketHandler → WebSocket handler for progress
// - uploadista.dispose      → Cleanup function

Configuration Options

Required Options

Option	Type	Description
`dataStore`	`DataStore`	Where file content is stored. See Data Stores.
`kvStore`	`KvStore`	Where upload metadata is stored. See KV Stores.
`adapter`	`Adapter`	Framework adapter (Hono, Express, or Fastify).

Optional Options

Option	Type	Default	Description
`flows`	`FlowProvider`	-	Flow definitions for file processing.
`plugins`	`Plugin[]`	`[]`	Processing plugins (image, video, etc.).
`eventBroadcaster`	`EventBroadcaster`	Memory	For multi-server setups, use Redis.
`withTracing`	`boolean`	`false`	Enable OpenTelemetry tracing.
`observabilityLayer`	`Layer`	-	Custom observability configuration.

Full Configuration Example

import { createUploadistaServer } from "@uploadista/server";
import { s3Store } from "@uploadista/data-store-s3";
import { redisKvStore } from "@uploadista/kv-store-redis";
import { redisEventBroadcaster } from "@uploadista/event-broadcaster-redis";
import { imagePlugin } from "@uploadista/flow-images-sharp";
import { honoAdapter } from "@uploadista/adapters-hono";

const uploadista = await createUploadistaServer({
  // Storage
  dataStore: s3Store({ /* ... */ }),
  kvStore: redisKvStore({ redis }),

  // Multi-server event broadcasting
  eventBroadcaster: redisEventBroadcaster({
    redis: redisPublisher,
    subscriberRedis: redisSubscriber,
  }),

  // File processing
  flows: getFlowById,
  plugins: [imagePlugin],

  // Observability
  withTracing: true,

  // Framework
  adapter: honoAdapter(),
});

Choosing a Backend

The Uploadista Server works with popular Node.js and edge frameworks. Choose based on your deployment:

Framework	Best For	Deployment
Hono	Edge, Cloudflare Workers	Cloudflare, Deno, Bun
Express	Traditional Node.js	AWS, GCP, Azure, self-hosted
Fastify	High-performance Node.js	AWS, GCP, Azure, self-hosted

Hono Integration Edge-first with Cloudflare Workers support

Express Integration Classic Node.js with wide ecosystem

Fastify Integration High-performance with schema validation

Mounting Routes

import { Hono } from "hono";
import { upgradeWebSocket } from "hono/cloudflare-workers";

const app = new Hono();

// HTTP routes for uploads and flows
app.on(
  ["HEAD", "POST", "GET", "PATCH", "DELETE"],
  ["/uploadista/api/*"],
  (c) => uploadista.handler(c)
);

// WebSocket for progress updates
app.get(
  "/uploadista/ws/upload/:uploadId",
  upgradeWebSocket(uploadista.websocketHandler)
);

import express from "express";
import expressWs from "express-ws";

const { app } = expressWs(express());

// HTTP routes
app.all("/uploadista/api/*", (req, res) =>
  uploadista.handler({ request: req, reply: res })
);

// WebSocket
app.ws("/uploadista/ws/upload/:uploadId", uploadista.websocketHandler);

import Fastify from "fastify";
import fastifyWebsocket from "@fastify/websocket";

const fastify = Fastify();
await fastify.register(fastifyWebsocket);

// HTTP routes
fastify.all("/uploadista/api/*", async (request, reply) =>
  uploadista.handler({ request, reply })
);

// WebSocket
fastify.get(
  "/uploadista/ws/upload/:uploadId",
  { websocket: true },
  uploadista.websocketHandler
);

Connecting Clients

Use our official client libraries for the best experience with uploads, progress tracking, and error handling:

Client	Platform	Features
React	Web	Hooks, components, drag-and-drop
Vue	Web	Composables, components
Expo	React Native	Mobile-optimized, background uploads

React Client Hooks and components for React apps

Vue Client Composables for Vue 3 apps

Expo Client React Native with background uploads

Why Use Official Clients?

The official clients handle:

Chunked uploads - Automatic file splitting for large files
Resumability - Auto-resume on connection failure
Progress tracking - WebSocket-based real-time progress
Error handling - Retry logic and error recovery
TypeScript - Full type safety

Exposed Routes

The Uploadista Server exposes these HTTP routes:

Upload Routes

Method	Route	Description
`POST`	`/uploadista/api/upload`	Create new upload
`HEAD`	`/uploadista/api/upload/:id`	Get upload offset
`PATCH`	`/uploadista/api/upload/:id`	Upload chunk
`GET`	`/uploadista/api/upload/:id`	Get upload status
`DELETE`	`/uploadista/api/upload/:id`	Delete upload

Flow Routes

Method	Route	Description
`POST`	`/uploadista/api/flow/:flowId/execute`	Execute a flow
`GET`	`/uploadista/api/flow/job/:jobId`	Get job status
`DELETE`	`/uploadista/api/flow/job/:jobId`	Cancel job

WebSocket

Route	Description
`/uploadista/ws/upload/:uploadId`	Real-time upload progress

See Upload Engine for details on the upload protocol.

Triggering Flows

Configure flows to run automatically when uploads complete:

const uploadista = await createUploadistaServer({
  // ... other options

  flows: async (flowId, clientId) => {
    // Return flow definition based on flowId
    return getFlowFromDatabase(flowId);
  },
});

Or trigger flows manually via API:

POST /uploadista/api/flow/image-processing/execute
{
  "uploadId": "upload_abc123"
}

See Flows Engine for more on flow configuration.

Custom HTTP Client (Advanced)

If you’re not using React, Vue, or Expo, you can implement uploads directly using the HTTP API:

async function uploadFile(file) {
  // 1. Create upload
  const createRes = await fetch("/uploadista/api/upload", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      fileName: file.name,
      size: file.size,
      type: file.type,
    }),
  });
  const upload = await createRes.json();

  // 2. Upload content
  await fetch(`/uploadista/api/upload/${upload.id}`, {
    method: "PATCH",
    headers: {
      "Content-Type": "application/offset+octet-stream",
      "Upload-Offset": "0",
    },
    body: file,
  });

  return upload.id;
}

For resumable uploads, chunking, and progress tracking, see the Upload Engine documentation.

Best Practices

Production Checklist

Use Redis for KV Store (not Memory) - enables multi-server deployments
Use Redis Event Broadcaster for WebSocket events across servers
Configure appropriate file size limits
Set up authentication middleware
Enable tracing for debugging (withTracing: true)

Security

// Add authentication middleware before Uploadista routes
app.use("/uploadista/*", authMiddleware);

// Then mount Uploadista
app.on(["HEAD", "POST", "GET", "PATCH", "DELETE"], ["/uploadista/api/*"],
  (c) => uploadista.handler(c)
);

See Authentication for fine-grained access control.

Cleanup

When shutting down your server, dispose of the Uploadista instance:

process.on("SIGTERM", async () => {
  await uploadista.dispose();
  process.exit(0);
});

Upload Engine - How uploads work internally
Flows Engine - File processing pipelines
Data Stores - File storage backends
KV Stores - Metadata storage
Event System - Real-time progress events
Plugins - Processing capabilities
Authentication - Access control