@fastify-core/elfinder

A powerful Node.js file manager integration for Fastify applications, built on the elFinder library. Provides comprehensive file and directory management capabilities with image processing support.

Features

• 📁 File Management - Create, read, update, delete files and directories
• 🖼️ Image Processing - Resize, crop, rotate images with Sharp integration
• 📦 Archive Support - Create and extract ZIP files
• 🔍 File Search - Search files by name within volumes
• 🎨 Thumbnails - Auto-generate image thumbnails
• 🔐 Permission Control - Fine-grained ACL (Access Control List) support
• 📤 File Upload - Configurable upload with MIME type validation
• ⚡ TypeScript - Full TypeScript support with type definitions

Requirements

• Node.js ≥ 24
• Fastify compatible environment

Installation

npm install @fastify-core/elfinder

Peer Dependencies

Install the required peer dependencies:

npm install adm-zip archiver base-64 dotenv mime-types sharp

Or install specific versions:

npm install \
  adm-zip@^0.6.0 \
  archiver@^8.0.0 \
  base-64@^1.0.0 \
  dotenv@^17.4.2 \
  mime-types@^3.0.2 \
  sharp@^0.35.3

Quick Start

Basic Setup

import { createElfinder, initImgFinder, getImgElfinder } from '@fastify-core/elfinder';

// Create an elFinder instance with custom options
const elfinder = createElfinder({
  URL: 'http://localhost:3000/files/',
  path: './uploads',
  uploadAllow: ['image/png', 'image/jpg', 'image/jpeg'],
  uploadMaxSize: 5 // MB
});

Image Manager

// Initialize the image manager
const imgFinder = await initImgFinder();

// Get the initialized image finder instance
const currentFinder = getImgElfinder();

API Reference

ElFinder Class

Methods

| Method | Description | |--------|-------------| | archive(opts) | Create a ZIP archive from multiple files/directories | | dim(opts) | Get image dimensions | | duplicate(opts) | Duplicate a file or directory | | extract(opts) | Extract ZIP files | | file(opts) | Get file information | | get(opts) | Read file content | | ls(opts) | List directory contents | | mkdir(opts) | Create a new directory | | mkfile(opts) | Create a new file | | open(opts) | Initialize file tree | | parents(opts) | Get parent directories | | resize(opts) | Resize images | | rm(opts) | Delete files/directories | | size(opts) | Get directory/file size | | search(opts) | Search files by name | | tree(opts) | Get directory tree | | tmb(opts) | Generate thumbnails | | upload(opts) | Handle file uploads | | zipdl(opts) | Download as ZIP |

Configuration

ElFinderOptions

interface ElFinderOptions {
  target?: string;           // Target file/directory hash
  name?: string;             // Name for new files/archives
  dirs?: string[];           // Directory paths
  makedir?: number;          // Directory creation options
  intersect?: string[];      // Intersection targets
  cut?: number;              // Cut operation flag
  suffix?: string;           // File suffix
  renames?: string[];        // Rename targets
  dst?: string;              // Destination
  content?: string;          // File content
  encoding?: string;         // Content encoding
  q?: string;                // Search query
  upload_path?: string[];    // Upload paths
  width?: number;            // Image width (resize)
  height?: number;           // Image height (resize)
  x?: number;                // Crop X position
  y?: number;                // Crop Y position
  degree?: number;           // Rotation degree
  bg?: string;               // Background color
  quality?: number;          // Image quality (1-100)
  mode?: 'resize' | 'crop' | 'rotate'; // Image operation mode
  current?: string;          // Current directory hash
  targets?: string[];        // Multiple targets
  init?: boolean;            // Initialization flag
}

VolumePermissions

interface VolumePermissions {
  read: number;              // Read permission (1 = allowed, 0 = denied)
  write: number;             // Write permission (1 = allowed, 0 = denied)
  locked: number;            // Locked state (1 = locked, 0 = unlocked)
}

Config

interface Config {
  router: string;            // Router path (default: '/elFinder')
  disabled: string[];        // Disabled commands
  allowed: string[];         // Allowed commands
  volumeicons: string[];     // Volume icons
  roots: any[];              // Root volumes configuration
  volumes: string[];         // Volume paths
  tmbroot: string;           // Thumbnail root directory
  init?: () => void;         // Initialization callback
  acl?: (p: string) => VolumePermissions; // ACL function
}

FsUtils Class

Utility class for file system operations:

• compress(files, dest) - Compress multiple files into ZIP
• decode(hash) - Decode path hash to absolute path
• info(filePath) - Get file information
• volume(filePath) - Get volume from path
• readDir(dirPath) - Read directory contents
• generateThumbnail(imagePath) - Generate image thumbnail

Environment Variables

BASE_URL=http://localhost:3000

Required for proper URL generation in thumbnail and file paths.

Usage Example

import { ElFinder } from '@fastify-core/elfinder';

const elfinder = new ElFinder();

// Configure with roots and volumes
elfinder.init({
  roots: [
    {
      driver: 'LocalFileSystem',
      path: './uploads',
      URL: 'http://localhost:3000/uploads/',
      uploadAllow: ['image/*'],
      uploadMaxSize: 10,
      permissions: (path) => ({
        read: 1,
        write: 1,
        locked: 0
      })
    }
  ],
  volumes: ['./uploads'],
  tmbroot: './public/.tmb',
  disabled: ['extract'],
  acl: (path) => ({
    read: 1,
    write: 1,
    locked: 0
  })
});

// Use elFinder operations
const archiveResult = await elfinder.archive({
  target: 'encodedHash',
  name: 'archive.zip',
  targets: ['file1Hash', 'file2Hash']
});

// Resize an image
const resizeResult = await elfinder.resize({
  target: 'imageHash',
  mode: 'resize',
  width: 800,
  height: 600,
  quality: 85
});

// Search files
const searchResult = await elfinder.search({
  q: 'document',
  current: 'currentDirHash'
});

Error Handling

try {
  const result = await elfinder.archive(options);
} catch (error) {
  console.error('elFinder operation failed:', error);
}

Image Operations

Supported Formats

• Resize: Scales image to specified dimensions
• Crop: Crops image at specified coordinates
• Rotate: Rotates image by specified degrees

Options

const resizeOpts = {
  mode: 'resize',
  width: 1024,
  height: 768,
  quality: 90
};

const cropOpts = {
  mode: 'crop',
  x: 0,
  y: 0,
  width: 500,
  height: 500
};

const rotateOpts = {
  mode: 'rotate',
  degree: 90,
  bg: '#ffffff'
};

Notes

• All file paths should be encoded using the elFinder hash encoding scheme
• Thumbnails are cached in the configured tmbroot directory
• Permissions are evaluated per file/directory via the ACL function
• Image processing requires Sharp library (native image processing)

License

ISC

Author

MIT

Last Updated: 2026-08-18