express-file-bucket

A small helper for saving uploaded files, deleting saved files, and building public URLs in Express apps. It supports CommonJS and ES modules, and accepts express-fileupload file objects or common Multer file objects.

Install

npm install express-file-bucket

You also need an upload middleware, for example:

npm install express-fileupload

// app.js (ES module)
import express from 'express';
import fileUpload from 'express-fileupload';
import { saveFiles, deleteFiles, getFiles } from 'express-file-bucket';

const app = express();
app.use(fileUpload());
app.use('/uploads', express.static('public/uploads'));

app.post('/upload', async (req, res, next) => {
  try {
    const names = await saveFiles(req.files?.files ?? req.files?.file);
    res.json({ files: names, urls: getFiles(req, 'uploads', names) });
  } catch (error) {
    next(error);
  }
});

CommonJS

const { saveFiles, deleteFiles, getFiles } = require('express-file-bucket');

API

await saveFiles(fileOrFiles, options?)

Save one file or an array of files. Always returns an array of saved basenames. With no options, files go to public/uploads and keep their original filename unless that name already exists, in which case a random suffix is added to avoid overwriting.

const names = await saveFiles(req.files.avatar);
const many = await saveFiles(req.files.documents);

Options:

| Option | Type | Default | Meaning | | --- | --- | --- | --- | | upload_path | string | public/uploads | Local directory to save into | | file_name | string | original filename | Optional exact desired filename; preserved exactly as supplied, including its extension (or lack of one) | | fixed_file_name | string | — | Backwards-compatible fixed-name option; can overwrite only when overwrite: true | | keep_original_name | boolean | false | Keep each original filename | | allowed_ext | string[] | — | Allow only these extensions, e.g. ['jpg', 'png'] | | min_size | number | — | Minimum size in bytes | | max_size | number | — | Maximum size in bytes | | overwrite | boolean | false | Allow writing over the requested destination name |

Examples:

// Save using the exact requested name (extension included)
await saveFiles(req.files.avatar, { file_name: 'school-logo.png' });

// The name is preserved exactly as supplied (no extension is added)
await saveFiles(req.files.avatar, { file_name: 'profile-photo' });

// Custom directory and validation
await saveFiles(req.files.documents, {
  upload_path: 'public/uploads/documents',
  allowed_ext: ['pdf', 'docx'],
  max_size: 5 * 1024 * 1024
});

// Keep each original filename; existing files are not overwritten
await saveFiles(req.files.documents, { keep_original_name: true });

If a name already exists and overwrite is false, the package adds a suffix to prevent accidental replacement. To deliberately replace a file at a known name, set overwrite: true and provide file_name or fixed_file_name.

await deleteFiles(folder, filenameOrFilenames)

Delete one or many files from a directory. It returns an array of successfully deleted basenames; missing files are ignored. It does not recursively delete directories.

await deleteFiles('public/uploads', 'school-logo.png');
await deleteFiles('public/uploads', ['one.pdf', 'two.png']);

Only basenames are accepted: paths supplied as filenames are reduced to their basename, preventing ../ traversal outside the selected folder.

getFiles(req, publicFolder, filenameOrFilenames)

Build absolute public URLs from the Express request. The folder argument is the URL path, not necessarily the disk path. Mount the matching static directory yourself.

app.use('/uploads', express.static('public/uploads'));
const urls = getFiles(req, 'uploads', ['school-logo.png', 'photo.jpg']);
// ['https://example.com/uploads/school-logo.png', ...]
const oneUrl = getFiles(req, 'uploads', 'school-logo.png');
// Returns an array with one URL, for consistency with the original API.

ensureDir(folder)

Creates a directory and any missing parent directories, then resolves with the folder path.

Supported upload middleware objects

• express-fileupload: uses file.name, file.size, and file.mv(destination).
• Multer: supports file.originalname with file.buffer (memory storage) or file.path (disk storage).

For Multer disk storage, this package copies the file to the destination; it does not remove Multer's temporary/source file.

Important notes

• Upload validation errors reject the promise. Handle them with try/catch or Express error middleware.
• allowed_ext checks the extension only; it does not inspect file contents or prove that a file is safe.
• Configure upload middleware limits as well as package-level validation for production.
• getFiles() only constructs URLs. The app must expose the directory with express.static() or another static-file handler.
• The default path is relative to the process working directory. Set upload_path explicitly if your app uses a different root.