@wulzymart/fileman-server

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

Features

• Hono + 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 create your own Hono server and add the fileman server routes to it:

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

const app = generateHonoServer({
  port: 3000,
  storageType: "local",
  uploadDir: "./my-uploads",
});

This will generate a Hono app with the file server routes on the appended base path, ensure you specify the path in FILE_API_URL` to avoid any issues with file urls.

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",
});

This will automatically start the file server on /api/*` path. You may configure CORS_ORIGINS to restrict access in your env or leave to allow all

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 | | CORS_ORIGINS | No | * | Comma separated Frontend URLS used for CORS allowed origins | | FILES_API_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 in a specific path.
  • Query Param: path (optional) - The directory path to list (e.g., ?path=images/vacation).
• GET /api/folders/tree: Get a recursive tree structure of all folders.
• GET /api/files/*: Download or view a file by its path.
• POST /api/upload: Upload a single file using multipart/form-data.
  • Body: A file field containing the binary data.
  • Query Param: path (optional) - The target directory where the file should be saved.
• POST /api/upload-url: Download a file from a remote URL directly to storage.
  • Body: { "url": "https://example.com/file.jpg", "path": "optional/target/path" }
• POST /api/folders: Create a new folder.
  • Body: { "name": "new-folder", "path": "parent/directory" }
• POST /api/files/copy: Copy a file or folder to a new location.
  • Body: { "id": "source/path/file.txt", "targetPath": "destination/path" }
• POST /api/files/move: Move a file or folder to a new location.
  • Body: { "id": "source/path/file.txt", "targetPath": "destination/path" }
• DELETE /api/files/*: Delete a file or folder at the specified path.