@wulzymart/fileman-server

A robust backend for managing files with support for multiple storage backends.

Links

• GitHub: https://github.com/wulzymart/fileman-gs

Features

• Express + Bun: High-performance backend engine.
• Storage Providers:
  • LocalStorageProvider: For local filesystem storage.
  • S3StorageProvider: For AWS S3 or S3-compatible (Minio, DigitalOcean) storage.
• REST API: Clean endpoints for all file operations.

Library Usage

You can also import and start the server within your own Node.js/Bun project:

import { startServer } from "@wulzymart/fileman-server";

startServer({
  port: 3000,
  storageType: "local",
  uploadDir: "./my-uploads",
});

ServerOptions

| Option | Type | Default | Description | | ------------- | ----------------- | ------------------------- | ------------------------------------------------------- | | port | number | 3000 | Port to listen on (overrides STORAGE_SERVER_PORT env) | | storageType | 'local' \| 's3' | 'local' | Storage provider to use | | uploadDir | string | './uploads' | Directory for local storage | | serveStatic | boolean | true | Whether to serve static files/Vite middleware | | distPath | string | process.cwd() + '/dist' | Path to static files for production |

Environment Variables

The server can be configured using environment variables. Note that certain configurations, such as S3 credentials, must be set via environment variables as they are not currently exposed through ServerOptions.

| Variable | Required | Default | Description | | --------------------- | -------- | ----------- | ------------------------------------------ | | STORAGE_TYPE | No | local | Storage provider to use (local or s3) | | STORAGE_SERVER_PORT | No | 3000 | Port to listen on | | UPLOAD_DIR | No | ./uploads | Directory for local storage | | APP_URL | No | * | Frontend URL used for CORS allowed origins | | BASE_URL | Yes | | Base URL for the server,for file url |

S3 Configuration (Required if STORAGE_TYPE=s3)

| Variable | Description | | ---------------------- | --------------------------------------------------------------------- | | S3_REGION | AWS Region (e.g., us-east-1) | | S3_BUCKET | The name of your S3 bucket | | S3_ACCESS_KEY_ID | Your AWS Access Key ID | | S3_SECRET_ACCESS_KEY | Your AWS Secret Access Key | | S3_ENDPOINT | Optional: Custom S3 endpoint (e.g., for MinIO or DigitalOcean Spaces) |

API Endpoints

GET /api/files

List files and folders inside a specific folder path.

• Query Parameters:
  • path (string): The path to list files from. Default "" (root).
• Returns: FileInfo[]

interface FileInfo {
  id: string; // The file's absolute path / key
  name: string;
  size: number;
  type: string;
  lastModified: number;
  url: string;
  isFolder?: boolean;
}

GET /api/folders/tree

List all folders in a nested tree structure.

• Returns: FolderNode[]

interface FolderNode {
  id: string; // Path or key
  name: string;
  children: FolderNode[];
}

POST /api/upload

Upload a single file to a specific path.

• Content-Type: multipart/form-data
• Form Data Fields:
  • file: The file binary to upload.
  • path (optional): The target path.
• Returns: FileInfo (the created file object)

POST /api/upload-url

Download an external image/file from a URL and save it to the storage.

• Content-Type: application/json
• Request Body:

{
  "url": string; // The external URL to download
  "path"?: string; // The target path to save the file
}

• Returns: FileInfo (the created file object)

POST /api/folders

Create a new folder.

• Content-Type: application/json
• Request Body:

{
  "name": string; // The folder name to create
  "path"?: string; // The parent path
}

• Returns: FileInfo (the created folder object)

POST /api/files/copy

Copy a file to a new location.

• Content-Type: application/json
• Request Body:

{
  "id": string; // Source file path/ID
  "targetPath": string; // Destination path
}

• Returns: FileInfo (the new file object)

POST /api/files/move

Move or rename a file to a new location.

• Content-Type: application/json
• Request Body:

{
  "id": string; // Source file path/ID
  "targetPath": string; // Destination path
}

• Returns: FileInfo (the new file object)

GET /api/files/*

Retrieve the actual binary content of a file. Supports inline display.

• Path Parameter: The wildcard * matches the file id / path.
• Returns: Binary file stream with Content-Type, Content-Length, and Content-Disposition.

DELETE /api/files/*

Delete a file or an entire folder.

• Path Parameter: The wildcard * matches the file id / path.
• Returns:

{ "success": true }