imgminer

Download all images from any URL. Simple image scraping library and CLI for Node.js.

Installation

npm install imgminer

CLI Usage

# Download all images from a URL
npx imgminer https://example.com

# Save to specific directory
npx imgminer https://example.com -o ./downloads

# Limit number of images
npx imgminer https://example.com -n 100

# Enable deep scan (parse CSS files for background images)
npx imgminer https://example.com --deep

# List images without downloading
npx imgminer --list https://example.com

Library Usage

Download images to a ZIP file

import { downloadImages } from 'imgminer';

const result = await downloadImages('https://example.com', {
  maxImages: 50,
  deepScan: true,
  outputDir: './downloads',
  onProgress: (progress) => {
    console.log(`${progress.percentage}% - ${progress.current}`);
  }
});

console.log(`Downloaded ${result.downloadedCount} images to ${result.zipPath}`);

Get image URLs without downloading

import { getImages } from 'imgminer';

const result = await getImages('https://example.com', {
  maxImages: 100,
  deepScan: true
});

console.log(`Found ${result.totalImages} images`);
result.images.forEach(img => console.log(img.url));

Get ZIP as buffer (for web servers)

import { downloadImages } from 'imgminer';

const result = await downloadImages('https://example.com');
// result.zipBuffer contains the ZIP file as a Buffer
// (only available when outputDir is not specified)

API

downloadImages(url, options?)

Downloads all images from a URL and creates a ZIP file.

Options:

• maxImages (number): Maximum images to download. Default: 50
• deepScan (boolean): Parse CSS files for background images. Default: false
• outputDir (string): Output directory. If not specified, returns buffer
• filename (string): Custom ZIP filename
• formats (string[]): Filter by formats (e.g., ['jpg', 'png'])
• onProgress (function): Progress callback

Returns: DownloadResult

• zipPath: Path to the created ZIP file
• zipBuffer: ZIP as Buffer (when no outputDir)
• totalSize: Total size in bytes
• downloadedCount: Number of images downloaded
• images: Array of image info
• errors: Any errors encountered

getImages(url, options?)

Scrapes image URLs from a page without downloading.

Options:

• maxImages (number): Maximum images to find. Default: 50
• deepScan (boolean): Parse CSS files. Default: false
• formats (string[]): Filter by formats

Returns: ScrapingResult

• images: Array of ImageInfo objects
• totalImages: Total number found
• errors: Any errors encountered

Supported Formats

jpg, jpeg, png, gif, webp, svg, bmp, ico

Features

• Extracts images from <img> tags
• Detects lazy-loaded images (data-src, data-lazy-src)
• Finds CSS background images
• Deep scan mode for external CSS files
• Automatic image optimization (resize, compress)
• Progress tracking
• Handles relative and absolute URLs

License

MIT