@bubblystorage/express

Express.js middleware and helpers for Bubbly Storage file uploads.

Installation

npm install @bubblystorage/express express multer

Usage

Basic Setup

import express from 'express';
import { createBubblyStorageHandler } from '@bubblystorage/express';

const app = express();

const uploadHandler = createBubblyStorageHandler({
  apiKey: 'your-api-key',
  apiUrl: 'https://your-bubbly-storage-api.com/api/v1', // optional, defaults to production
  maxFileSize: 10 * 1024 * 1024, // 10MB, optional
  allowedTypes: ['image/*', 'application/pdf'], // optional
  fieldName: 'files', // optional, defaults to 'files'
  maxFiles: 10 // optional, defaults to 10
});

// Use as middleware
app.post('/upload', uploadHandler, (req, res) => {
  // Files have been uploaded and processed
  res.json({ message: 'Upload successful' });
});

Single File Upload

import { createBubblyStorageSingleHandler } from '@bubblystorage/express';

const singleUploadHandler = createBubblyStorageSingleHandler({
  apiKey: 'your-api-key',
  fieldName: 'file' // optional, defaults to 'file'
});

app.post('/upload-single', singleUploadHandler, (req, res) => {
  res.json({ message: 'Single file upload successful' });
});

Custom Error Handling

app.post('/upload', uploadHandler, (req, res) => {
  // The middleware handles errors automatically
  // Success responses contain the upload result from Bubbly Storage API
});

API Reference

createBubblyStorageHandler(options)

Creates Express middleware for handling multiple file uploads.

Options

• apiKey (string, required): Your Bubbly Storage API key
• apiUrl (string, optional): API endpoint URL, defaults to production
• maxFileSize (number, optional): Maximum file size in bytes, defaults to 10MB
• allowedTypes (string[], optional): Array of allowed MIME types (supports wildcards like 'image/*')
• fieldName (string, optional): Form field name for files, defaults to 'files'
• maxFiles (number, optional): Maximum number of files, defaults to 10

Returns

Express middleware function that:

1. Parses multipart/form-data using multer
2. Validates files (type and size)
3. Uploads files to Bubbly Storage API
4. Returns JSON response with upload results

createBubblyStorageSingleHandler(options)

Creates Express middleware for handling single file uploads.

Same options as createBubblyStorageHandler but fieldName defaults to 'file' and maxFiles is ignored.

Error Handling

The middleware automatically handles and returns appropriate HTTP status codes:

• 400 Bad Request: No files uploaded, invalid file types
• 413 Payload Too Large: File size exceeds limit
• 500 Internal Server Error: API errors or server issues

Error responses include a JSON object with success: false and an error message.

Response Format

Successful uploads return:

{
  "success": true,
  "data": {
    // Bubbly Storage API response
  }
}

Requirements

• Node.js 14+
• Express 4+
• Multer 1.4+