pixel-serve-server
TypeScript icon, indicating that this package has built-in type declarations

0.0.5 • Public • Published

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:

Option Type Description
baseDir string Base directory for local image files.
idHandler Function Function to handle and format user IDs.
getUserFolder Function Async function to resolve a user-specific folder path.
websiteURL string Your website's base URL for identifying internal resources.
apiRegex RegExp Regex to strip API prefixes from internal paths.
allowedNetworkList string[] List of allowed domains for network images.

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:

Parameter Type Description
src string Path or URL to the image source.
format ImageFormat Desired output format (e.g., jpeg, png, webp).
width number Desired width of the output image.
height number Desired height of the output image.
quality number Image quality (1-100, default: 80).
folder 'public' | 'private' Image folder type (default: public).
userId string | null User ID for private folder access.
type 'normal' | 'avatar' Image type (default: normal).

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:

Error Condition Fallback Behavior
Invalid local path Returns a fallback image.
Unsupported network domain Returns a fallback image.
Invalid or missing parameters Defaults to placeholder values.

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.

Package Sidebar

Install

npm i pixel-serve-server

Weekly Downloads

11

Version

0.0.5

License

MIT

Unpacked Size

98.1 kB

Total Files

15

Last publish

Collaborators

  • hiprax