pixel-serve-server v0.0.5

Image Server Middleware

A powerful and customizable middleware for processing, resizing, and serving images in Node.js applications. Built with TypeScript and powered by Sharp, this package allows you to handle local and network images with robust error handling, fallback images, and customizable options.

Features

• 🖼️ Dynamic Image Resizing and Formatting

  • Supports various formats: jpeg, png, webp, gif, tiff, avif, and svg.
  • Adjustable dimensions with constraints for safety.

• 🌐 Network and Local File Handling

  • Fetches images from allowed network domains.
  • Processes images stored locally with safe path validation.

• 🔒 Fallback Images

  • Provides fallback images for invalid or missing sources.

• 🔧 Highly Configurable

  • Flexible option to set base directories, private folders, and user-specific paths.
  • Supports user-defined ID handlers and folder logic.

• 🚀 Efficient and Scalable

  • Built on Sharp for high-performance image processing.
  • Handles concurrent requests with ease.

Installation

Install the package using npm or yarn:

npm install pixel-serve-server

Usage

Basic Setup

Here’s how to integrate the middleware with an Express application:

import express from "express";
import { registerServe } from "pixel-serve-server";
import path, { dirname } from "node:path";
import { fileURLToPath } from "node:url";

const app = express();
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

const BASE_IMAGE_DIR = path.join(__dirname, "../assets/images/public");
const PRIVATE_IMAGE_DIR = path.join(__dirname, "../assets/images/private");

const serveImage = registerServe({
  baseDir: BASE_IMAGE_DIR, // Base directory for local images
  idHandler: (id: string) => `user-${id}`, // Custom handler for user IDs
  getUserFolder: async (id: string) => `/private/users/${id}`, // Logic for user-specific folder paths
  websiteURL: "example.com", // Your website's base URL
  apiRegex: /^\/api\/v1\//, // Regex for removing API prefixes
  allowedNetworkList: ["trusted.com"], // List of allowed network domains
});

app.get("/api/v1/pixel/serve", serveImage);

app.listen(3000, () => {
  console.log("Server is running on http://localhost:3000");
});

Options

The serveImage middleware accepts the following options:

Example Requests

Fetching a Local Image

GET http://localhost:3000/images?src=/uploads/image1.jpg&width=300&height=300

Fetching a Network Image

GET http://localhost:3000/images?src=https://trusted.com/image2.jpg&format=webp

Handling Private User Folders

GET http://localhost:3000/images?src=/avatar.jpg&folder=private&userId=12345

User Data Parameters

The middleware uses the following UserData query parameters:

Image Formats

The following image formats are supported:

• jpeg
• jpg
• png
• webp
• gif
• tiff
• avif
• svg

Each format is processed with the specified quality settings.

Advanced Configuration

Custom ID Handler

Use the idHandler option to customize how user IDs are formatted.

const options = {
  idHandler: (id) => `user-${id.toUpperCase()}`, // Converts ID to uppercase with "user-" prefix
};

Resolving User Folders

The getUserFolder function dynamically resolves private folder paths for users.

const options = {
  getUserFolder: async (id) => `/private/data/users/${id}`, // Returns a private directory path
};

Allowed Network Domains

Whitelist trusted domains for fetching network images.

const options = {
  allowedNetworkList: ["example.com", "cdn.example.com"], // Only allows images from these domains
};

Error Handling

The middleware automatically falls back to pre-defined images for errors:

Dependencies

This package uses the following dependencies:

• Express: HTTP server framework.
• Sharp: High-performance image processing.
• Axios: HTTP client for fetching network images.

License

This package is licensed under the MIT License.

Feedback

If you encounter issues or have suggestions, feel free to open an issue.