HFS: HTTP File Server

3.1.1 verified Sat Apr 25 auth: no javascript

HFS (HTTP File Server) is a file-sharing server that turns your computer into a file-sharing hub with unlimited space and bandwidth. Current stable version is 3.1.1 (December 2024), with active development and frequent releases (multiple minor versions per year). Key differentiators include a virtual file system, instant ZIP downloads for large folders, real-time activity monitoring, bandwidth throttling, and a plugin system. It supports HTTPS, WebDAV (since 3.1.0), IPv6, and runs on Windows, Linux, macOS, FreeBSD, and Android. Compared to alternatives like FileZilla or Samba, HFS is lightweight, zero-configuration, and designed for temporary or permanent file sharing over HTTP/HTTPS with a web-based admin interface. It requires Node.js >=18.15.0 and is available as a binary or via npx.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/hfs/index.js from /path/to/your/file.js not supported ↓

cause Using CommonJS require() on an ESM-only package (HFS v3)

fix

Change your file extension to .mjs or use dynamic import(): const { start } = await import('hfs')

error TypeError: hfs.start is not a function ↓

cause Incorrect import: used default import (import hfs from 'hfs') but start is a named export

fix

Use named import: import { start } from 'hfs'

error Error: listen EADDRINUSE :::8080 ↓

cause Port 8080 is already in use by another process

fix

Either kill the process using port 8080, or specify a different port in config (e.g., port: 3000)

Warnings

breaking HFS v3 requires Node.js >= 18.15.0 ↓

fix Update Node.js to version 18.15.0 or later, or use HFS v2.x which supports older Node versions.

breaking HFS v3 is ESM-only; CommonJS require() will throw an error ↓

fix Use ESM imports (import { start } from 'hfs') or switch to dynamic import() inside CommonJS modules.

deprecated The 'vfs' option in config is deprecated in favor of 'virtualFileSystem' ↓

fix Replace 'vfs' with 'virtualFileSystem' in the config object.

gotcha Admin panel does not require a password for localhost by default (localhost_admin defaults to true) ↓

fix Run 'config localhost_admin false' in the console or set 'localhostAdmin: false' in config to require authentication from localhost.

gotcha Windows antivirus may flag the HFS binary as a false positive ↓

fix Add exception for the HFS binary in your antivirus, or verify the checksum from GitHub releases.

Install

npm install hfs

yarn add hfs

pnpm add hfs

Imports

start
wrong
```
const hfs = require('hfs'); hfs.start()
```
correct
```
import { start } from 'hfs'
```
HFS v3 is ESM-only. CommonJS require() will fail. The start function is the primary entry point to launch the server programmatically.
Hfs
wrong
```
import Hfs from 'hfs'
```
correct
```
import { Hfs } from 'hfs'
```
Hfs is a named export, not default. In v3, there is no default export.
Config
wrong
```
const Config = require('hfs').Config
```
correct
```
import { Config } from 'hfs'
```
Config type/interface for programmatic configuration. Requires TypeScript or JSDoc type imports.

Quickstart

Programmatically start an HFS server with custom port, root directory, and admin password using the ESM import.

import { start } from 'hfs';

const config = {
  port: 8080,
  host: '0.0.0.0',
  root: './shared',
  admin: {
    password: process.env.HFS_ADMIN_PASSWORD ?? 'temp123'
  }
};

const server = await start(config);
console.log('HFS server running on http://localhost:' + config.port);

// To stop: await server.close();