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 IntegrationEdge-first with Cloudflare Workers support

Express IntegrationClassic Node.js with wide ecosystem

Fastify IntegrationHigh-performance with schema validation

Mounting Routes

Hono

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)
);

Express

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);

Fastify

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 ClientHooks and components for React apps

Vue ClientComposables for Vue 3 apps

Expo ClientReact 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);
});

Related Concepts

• 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