PDF Thumbnail (mkholt/pdf-thumbnail)

PDF Thumbnail

https://github.com/mkholt/pdf-thumbnail
Admin
A library for generating thumbnails from PDF documents with support for server-side and client-side...

Tokens:6,356
Snippets:36
Trust Score:6.5
Update:1 month ago
Show doc for...
Context Summary (auto-generated)
Raw
# PDF Thumbnail

PDF Thumbnail is a TypeScript library for generating thumbnail images from PDF documents. It provides a simple, efficient API that works in both Node.js and browser environments, making it easy to integrate PDF preview functionality into any JavaScript application.

The library supports multiple output formats (base64 data URLs or Buffer), customizable scale factors, page selection, concurrent batch processing with progress callbacks, and AbortSignal support for cancellation. It also includes a React hook for seamless client-side integration with built-in loading and error state management.

## Installation

```bash
npm install @mkholt/pdf-thumbnail

# For Node.js environments, also install the canvas dependency
npm install @napi-rs/canvas
```

## createThumbnail

Creates a thumbnail for a single PDF file. Returns a `StringThumbnail` (base64 data URL) or `BufferThumbnail` on success, an `ErrorThumbnail` on failure, or `undefined` if the operation was aborted. Supports local file paths in Node.js and URLs in both Node.js and browser environments.

```typescript
import { createThumbnail } from '@mkholt/pdf-thumbnail';

// Basic usage - returns base64 data URL
const thumb = await createThumbnail('path/to/document.pdf');
if (!thumb) {
  console.log('Operation was aborted');
} else if (thumb.thumbType === 'error') {
  console.error('Failed to create thumbnail:', thumb.thumbData);
} else {
  // thumb.thumbData contains base64 data URL string
  console.log('Thumbnail created:', thumb.thumbData.substring(0, 50) + '...');
}

// Advanced usage with all options
const abortController = new AbortController();

const thumbnail = await createThumbnail('https://example.com/report.pdf', {
  output: 'string',           // 'string' (default) for data URL, 'buffer' for Buffer
  scale: 2,                   // Scale factor (default: 1), higher = larger thumbnail
  page: 1,                    // Page number to render (default: 1)
  logLevel: 'debug',          // 'silent' | 'error' (default) | 'debug'
  signal: abortController.signal,  // AbortSignal for cancellation
});

// Buffer output for server-side file saving
const bufferThumb = await createThumbnail('document.pdf', { output: 'buffer' });
if (bufferThumb && bufferThumb.thumbType === 'buffer') {
  const fs = await import('fs/promises');
  await fs.writeFile('thumbnail.png', bufferThumb.thumbData);
}
```

## createThumbnails

Creates thumbnails for multiple PDF files with support for batch processing, concurrency control, and progress callbacks. Returns an array containing both successful thumbnails and `ErrorThumbnail` results for files that failed. Aborted files are excluded from results.

```typescript
import { createThumbnails, FileData } from '@mkholt/pdf-thumbnail';

// Define files with optional metadata
type MyFile = FileData & { name: string; id: number };

const files: MyFile[] = [
  { file: 'report-2024.pdf', name: 'Annual Report', id: 1 },
  { file: 'invoice-001.pdf', name: 'Invoice #001', id: 2 },
  { file: 'contract.pdf', name: 'Service Contract', id: 3 },
];

const abortController = new AbortController();

const results = await createThumbnails(files, {
  prefix: 'public/documents/',  // Prefix prepended to all file paths
  scale: 0.5,                   // Scale factor for all thumbnails
  page: 1,                      // Page number to render
  concurrency: 4,               // Max parallel operations (default: Infinity)
  signal: abortController.signal,
  onProgress: (completed, total) => {
    console.log(`Progress: ${completed}/${total} (${Math.round(completed/total*100)}%)`);
  },
});

// Separate successes from errors
const successes = results.filter(t => t.thumbType !== 'error');
const errors = results.filter(t => t.thumbType === 'error');

console.log(`Generated ${successes.length} thumbnails`);
successes.forEach(thumb => {
  // Original metadata is preserved
  console.log(`- ${thumb.name} (ID: ${thumb.id}): ${thumb.thumbData.substring(0, 30)}...`);
});

if (errors.length > 0) {
  console.error(`${errors.length} files failed:`);
  errors.forEach(err => {
    console.error(`- ${err.file}: ${err.thumbData}`);
  });
}
```

## useThumbnails (React Hook)

A React hook for client-side thumbnail generation that provides loading state management, automatic cleanup on unmount, and error handling. Uses AbortController internally to cancel pending operations when the component unmounts or dependencies change.

```typescript
import { useThumbnails, FileData } from '@mkholt/pdf-thumbnail';

export type DocumentFile = FileData & { name: string; url: string };

interface DocumentGalleryProps {
  files: DocumentFile[];
}

export const DocumentGallery = ({ files }: DocumentGalleryProps) => {
  const { thumbnails, isLoading, error } = useThumbnails(files, {
    prefix: '/api/files/',  // URL prefix for file fetching
    scale: 1,               // Scale factor
    page: 1,                // Page to render
  });

  if (isLoading) {
    return (
      <div className="loading">
        <span>Generating thumbnails...</span>
      </div>
    );
  }

  if (error) {
    return (
      <div className="error">
        <h3>Error generating thumbnails</h3>
        <p>{error.message}</p>
      </div>
    );
  }

  return (
    <div className="gallery">
      {thumbnails.map((doc) => (
        <a
          key={doc.file}
          href={doc.url}
          target="_blank"
          rel="noopener noreferrer"
          className="thumbnail-link"
        >
          <img
            src={doc.thumbData}
            alt={doc.name}
            className="thumbnail-image"
          />
          <span className="thumbnail-name">{doc.name}</span>
        </a>
      ))}
    </div>
  );
};

// Usage example
const App = () => {
  const documents: DocumentFile[] = [
    { file: 'report.pdf', name: 'Q4 Report', url: '/docs/report.pdf' },
    { file: 'manual.pdf', name: 'User Manual', url: '/docs/manual.pdf' },
  ];

  return <DocumentGallery files={documents} />;
};
```

## Types

The library exports TypeScript types for type-safe integration. `FileData` is the base type for input files, while `Thumbnail`, `StringThumbnail`, `BufferThumbnail`, and `ErrorThumbnail` represent the different output formats.

```typescript
import type {
  FileData,
  Thumbnail,
  StringThumbnail,
  BufferThumbnail,
  ErrorThumbnail,
  CreateThumbnailOptions,
  CreateThumbnailsOptions,
  UseThumbnailsOptions,
  UseThumbnailsResult,
  LogLevel,
} from '@mkholt/pdf-thumbnail';

// FileData - base type for input files
type FileData = {
  file?: string;  // Path or URL to the PDF file
};

// Thumbnail output types
type StringThumbnail = {
  thumbType: 'string';
  thumbData: string;  // Base64 data URL
};

type BufferThumbnail = {
  thumbType: 'buffer';
  thumbData: Buffer;  // Raw image buffer
};

type ErrorThumbnail = {
  thumbType: 'error';
  thumbData: string;  // Error message
};

type Thumbnail = StringThumbnail | BufferThumbnail | ErrorThumbnail;

// Extend FileData with custom properties
interface CustomDocument extends FileData {
  id: string;
  title: string;
  category: string;
}

// Type-safe thumbnail processing
async function processDocuments(docs: CustomDocument[]) {
  const results = await createThumbnails(docs);

  // Type narrowing based on thumbType
  for (const result of results) {
    if (result.thumbType === 'error') {
      console.error(`Failed: ${result.title} - ${result.thumbData}`);
    } else {
      // result is CustomDocument & StringThumbnail
      console.log(`Success: ${result.title} (${result.category})`);
    }
  }
}
```

## Summary

PDF Thumbnail is ideal for applications that need to display PDF previews, such as document management systems, file browsers, content management platforms, and any interface where users need visual identification of PDF files. The library handles both server-side rendering (using @napi-rs/canvas) for static site generation or API endpoints, and client-side rendering (using native browser canvas) for dynamic single-page applications.

The dual environment support enables flexible integration patterns: use `createThumbnails` with the `buffer` output in Node.js to generate and cache thumbnail images during build time or on the server, or leverage the `useThumbnails` React hook for on-demand client-side generation with automatic state management. The concurrency control, progress callbacks, and AbortSignal support make it well-suited for processing large document collections while maintaining responsive user interfaces.