Quickthumb-slug NPM

QuickThumb-Slug

Fast and secure on-the-fly thumbnail generation middleware for Express, based on QuickThumb. Uses pre-defined sizes to prevent malicious exploitation. Built with Sharp for optimal performance and memory efficiency.

Features

On-demand thumbnail generation
Pre-defined size configurations for security
High-performance image processing with Sharp
Support for modern image formats (including WebP)
Compatible with Express and Connect
Simple slug-based URL format

Installation

npm install quickthumb-slug

Usage

ESM (Recommended)

import express from 'express';
import quickthumb from 'quickthumb-slug';

const app = express();

app.use(quickthumb.static({
    baseDir: new URL('.', import.meta.url).pathname + "/public",
    sizes: {
        square: { width: 400, height: 400, type: "crop" },
        landscape: { width: 1200, height: 600, type: "crop" },
        fitinportrait: { width: 400, height: 700, type: "resize" }
    }
}));

CommonJS (Legacy)

const express = require('express');
const qt = require('quickthumb-slug');

const app = express();

app.use(qt.static({
    baseDir: __dirname + "/public",
    sizes: {
        square: { width: 400, height: 400, type: "crop" },
        landscape: { width: 1200, height: 600, type: "crop" },
        fitinportrait: { width: 400, height: 700, type: "resize" }
    }
}));

Usage in HTML

<!-- Original image -->
<img src="/images/photo.jpg" />

<!-- Thumbnailed version using 'square' configuration -->
<img src="/images/photo-square.jpg" />

Configuration

The static() middleware accepts an options object with the following properties:

Option	Type	Description	Default
`baseDir`	string	Source images directory	Required
`cacheDir`	string	Generated thumbnails directory	`[baseDir]/thumbs/`
`sizes`	object	Size configurations (see below)	Default sizes
`quality`	number	JPEG quality (0-100)	80

Size Configuration

Each size configuration in the sizes object can have:

width: Width in pixels
height: Height in pixels
type: Processing type
- "crop" (default): Exact dimensions using center crop
- "resize": Maintain aspect ratio, fit within dimensions

Default Sizes

{
    small: { width: 320, height: 9999, type: "crop" },
    medium: { width: 768, height: 9999, type: "crop" },
    large: { width: 1200, height: 9999, type: "crop" }
}

File Naming

Thumbnails are automatically generated based on the filename format: [original-name]-[size-slug].[extension]

Examples:

Original: photo.jpg
Square thumbnail: photo-square.jpg
Landscape version: photo-landscape.jpg

Supported Formats

JPEG/JPG
PNG
GIF
WebP

Caching

Generated thumbnails are cached in [cacheDir]/[type]/[slug]/. The cache is automatically invalidated when the source image is modified.

Performance

This library uses Sharp for image processing, which provides:

4-5x faster processing than ImageMagick
Lower memory usage
Better image quality
Native WebP support

Migration from v1.x

If you're upgrading from version 1.x: 1. No code changes required - API remains compatible 2. ImageMagick is no longer required 3. Better memory management and performance 4. Added WebP support