Plugins

What are Plugins?

Plugins provide the processing capabilities that power flow nodes. While nodes define what operations to perform (resize, scan, extract text), plugins provide how those operations are executed.

Think of it this way:

• Nodes = The recipe (resize to 800x600, convert to WebP)
• Plugins = The kitchen equipment (Sharp library, ClamAV scanner)

Architecture

┌─────────────────────────────────────────────────────────┐
│                      Your Flow                          │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐            │
│  │  Input   │ → │  Resize  │ → │ Optimize │ → Output   │
│  │  Node    │   │  Node    │   │  Node    │            │
│  └──────────┘   └──────────┘   └──────────┘            │
└─────────────────────────────────────────────────────────┘
                        ↓ requires
┌─────────────────────────────────────────────────────────┐
│                    Plugin Layer                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │              imagePlugin (Sharp)                 │   │
│  │   Provides: resize(), optimize(), transform()   │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Node Packages vs Plugin Packages

Package Type	Purpose	Example
Node packages	Define node types and parameters	@uploadista/flow-images-nodes
Plugin packages	Provide processing implementation	@uploadista/flow-images-sharp

You need both: nodes define what to do, plugins do the work.

Available Plugins

By Category

Category	Node Package	Plugin Packages
Images	@uploadista/flow-images-nodes	flow-images-sharp, flow-images-photon, flow-images-replicate
Documents	@uploadista/flow-documents-nodes	flow-documents-plugin (recommended), flow-documents-pdflib, flow-documents-unpdf, flow-documents-replicate
Videos	@uploadista/flow-videos-nodes	flow-videos-av-node
Security	@uploadista/flow-security-nodes	flow-security-clamscan
Utility	@uploadista/flow-utility-nodes	flow-utility-zipjs

Plugin Selection Guide

Image Processing

Plugin	Best For	Environment	Speed
imagePlugin	Full-featured processing	Node.js	Fast (50-100ms)
imagePluginNode	Edge/serverless	Cloudflare Workers, Deno	Fastest (5-10ms)
imageAiPlugin	AI operations	Any (API-based)	Slow (5-20s)

Document Processing

Plugin	Best For	Operations
documentPlugin	Most use cases (recommended)	Split, merge, metadata, text extraction
pdfLibDocumentPlugin	PDF manipulation only	Split, merge, metadata
unpdfDocumentPlugin	Text extraction only	Fast text extraction
documentAiPlugin	Scanned documents	OCR, AI extraction

Video Processing

Plugin	Best For	Requirements
videoPlugin	All video operations	None (FFmpeg bundled)

Security

Plugin	Best For	Requirements
virusScanPlugin	Virus scanning	ClamAV installed

Installing Plugins

Step 1: Install Packages

npm

npm install @uploadista/flow-images-nodes @uploadista/flow-images-sharp

pnpm

pnpm add @uploadista/flow-images-nodes @uploadista/flow-images-sharp

yarn

yarn add @uploadista/flow-images-nodes @uploadista/flow-images-sharp

Step 2: Add Plugin to Server

import { createUploadistaServer } from "@uploadista/server";
import { imagePlugin } from "@uploadista/flow-images-sharp";

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

  // Add plugins here
  plugins: [
    imagePlugin(),
  ],
});

Configuring Plugins

Most plugins work out of the box. Some require configuration:

Plugins Requiring API Keys

import { createUploadistaServer } from "@uploadista/server";
import { imagePlugin } from "@uploadista/flow-images-sharp";
import { imageAiPlugin } from "@uploadista/flow-images-replicate";
import { documentAiPlugin } from "@uploadista/flow-documents-replicate";

const uploadista = await createUploadistaServer({
  // ...
  plugins: [
    imagePlugin(),
    imageAiPlugin(process.env.REPLICATE_API_TOKEN),
    documentAiPlugin({ apiToken: process.env.REPLICATE_API_TOKEN }),
  ],
});

Plugins Requiring System Dependencies

import { createUploadistaServer } from "@uploadista/server";
import { virusScanPlugin } from "@uploadista/flow-security-clamscan";

const uploadista = await createUploadistaServer({
  // ...
  plugins: [
    virusScanPlugin({
      preference: "clamdscan", // Use daemon for better performance
      clamdscan_socket: "/var/run/clamav/clamd.sock",
    }),
  ],
});

Combining Multiple Plugins

Add multiple plugins to handle different file types:

import { createUploadistaServer } from "@uploadista/server";
import { imagePlugin } from "@uploadista/flow-images-sharp";
import { imageAiPlugin } from "@uploadista/flow-images-replicate";
import { videoPlugin } from "@uploadista/flow-videos-av-node";
import { documentPlugin } from "@uploadista/flow-documents-plugin";
import { virusScanPlugin } from "@uploadista/flow-security-clamscan";

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

  plugins: [
    // Image processing
    imagePlugin(),
    imageAiPlugin(process.env.REPLICATE_API_TOKEN),

    // Video processing
    videoPlugin(),

    // Document processing (combined plugin recommended)
    documentPlugin,

    // Security
    virusScanPlugin(),
  ],
});

Error Handling

When a required plugin is missing, you’ll get a clear error:

Error: Service not found: ImagePlugin

This means you need to:

1. Install the plugin package (npm install @uploadista/flow-images-sharp)
2. Add it to your server plugins array

Detailed Documentation

For detailed plugin documentation including installation, configuration, and node requirements, see the specific flow pages:

• Image Nodes - imagePlugin, imagePluginNode, imageAiPlugin
• Document Nodes - documentPlugin, pdfLibDocumentPlugin, unpdfDocumentPlugin, documentAiPlugin
• Video Nodes - videoPlugin
• Security Nodes - virusScanPlugin
• Utility Nodes - zipPlugin

Related Concepts

• Flows Engine - How flows work
• Flow Nodes Overview - All available nodes
• Data Stores - Where processed files are saved