CyberFiles Lite

A (not-so) bare-bones file index built to work with Node.js Express and look like GitHub's file browser.

Features

• Easy and portable setup
• A minimalistic, modern, and responsive design
• Customizable themes with several built-in options
• Choose the root of your file index
• Use RegEx to hide (and prevent access to) certain files and directories
• Serve directory index files (like index.html) automatically
• Render a directory's README.md file below the file list
  • The contents of the README are also shown in that directory's link preview when sent on platforms like Discord
• View text files, images, videos, and audio files without leaving your browser
  • Text files of certain formats are syntax-highlighted
  • Videos and audio files use embedded players provided by @CyberGen49/web-resources (undocumented)
• Use the automatically-generated table of contents button to quickly jump to headings in markdown files
• Conveniently move between files in the file viewer using the next/previous arrows
• Change the sort order of a directory
• Filter files in a directory just by pressing Ctrl + F
• View the file extension breakdown of a directory in the File info pane
• Quickly download whole directories as zip files
• See image previews before clicking with thumbnails
• Get a better look at your files with tile view
  • Directories where more than 50% of the contents have thumbnails will use tile view automatically (see auto_view and auto_view_threshold)
• Add to your existing ExpressJS projects

Running CyberFiles Lite standalone

If your main goal is to get a simple file index up and running, a standalone CyberFiles Lite installation is the way to go!

Preparation

First, install git and Node.js (tested and working on v18.12.1).

Next, create or choose a directory where the files you want to serve are stored. Open your terminal, and cd into it:

cd /path/to/my/files

Installation

Now, we'll download CyberFiles Lite. The easiest way to do this is to clone the repository. This will place all of the code into a new folder.

git clone https://github.com/CyberGen49/cyberfiles-lite.git

Once git has finished cloning the repo, we'll rename the folder, adding an underscore at the beginning. This will hide the folder by default on the website, preventing users from entering it. After renaming, we'll cd into it.

mv ./cyberfiles-lite ./_cyberfiles
cd ./_cyberfiles

Next, we'll install all of CyberFiles Lite's dependencies from npm:

npm i

With everything set up, we can make sure it all works by starting the server:

npm start

At this point, assuming no errors occurred during any of the previous steps, you should be able to view your files by visiting http://localhost:8080.

Configuration

From this point, you can edit server-config.yml to change various settings for the server and CyberFiles Lite. The server configuration file is split into two sections:

{
    "cyberfiles": {
        "...": "..."
    },
    "server": {
        "...": "..."
    }
}

The cyberfiles section contains options for CyberFiles Lite itself. Descriptions of these options can be found below.

The server section contains options specific to the standalone server:

Number port

The port on which to host the server. Note that ports below 1000 may require root/administrator permissions.

Default: 8080

String ip_header

The HTTP header containing the client's IP address, used only for logging to the console.

Default: req.socket.remoteAddress

Don't forget to restart your server after changing any of these settings.

Adding CyberFiles Lite to an existing project

If you have an existing ExpressJS project, you can add CyberFiles lite to it so your users can see directory listings on pages that don't have index files.

Installation

Start by installing the package with npm:

npm i cyberfiles-lite

Then, require it in your project:

const cyberfiles = require('cyberfiles-lite');

The module exports a single, default function. This function only takes an optional opts parameter, which is an object containing any number of the options listed below, and returns an Express request handler.

Setup

Add CyberFiles Lite as an Express middleware by useing it:

// Where express is initialized and set to `srv`
srv.use(cyberfiles());

Without any options, the root of the file index will be set to the current directory (see the root option). CyberFiles will serve static file URLs as expected, so additional handlers (like express.static()) aren't necessary, assuming the files aren't hidden by one of your configured hide_patterns.

By default, CyberFiles will respond with a directory's index.html file if it exists (see the index_files option).

Example

This is about the simplest your server needs to be to get things working:

const express = require('express');
const cyberfiles = require('cyberfiles-lite');

const port = 8080;
const srv = express();
srv.use(cyberfiles());
srv.listen(port, () => console.log(`Listening on port ${port}`));

Options

These are all the configuration options for CyberFiles Lite.

string root

A directory path to serve as the root of your file index.

Defaults to the directory of the parent module.

Relative paths are relative to the directory of the parent module.

string data_dir

A separate directory where thumbnails should be stored to prevent them from being deleted when updating. A thumbs directory will be created inside this directory.

Defaults to where cyberfiles-lite is installed.

Relative paths are relative to cyberfiles-lite's installation directory.

string site_name

The name of this file index, used in various places around the site.

Defaults to "CyberFiles Lite".

string icon

A URL to use as the tab icon for the file index.

Defaults to one of the built-in themed icons: ?asset=icons/icon-<theme>.svg

string theme

A theme to use for the file index. This value must be the same as one of the keys in themes.json.

Defaults to "darkmuted".

string[] index_files

An array of file names to checked for and sent when a directory is accessed. If one of these files exist in a directory, they'll be sent instead of the file index.

Defaults to [ "index.html" ].

string[] hide_patterns

An array of RegEx strings to be checked against the absolute file/directory path of each request. If the pattern matches, the file/directory will be hidden from view.

Defaults to [ /\/(\.|_).*?(\/|$)/ ], which will hide all files and directories whose paths contain a node/segment starting with . or _.

When storing these options in JSON, be sure to escape backslashes when escaping other characters.

boolean handle_404

If true, CyberFiles Lite will handle requests for nonexistent paths (error 404s) and show the user an error page. If false, next() will be called, passing control to the next middleware.

Defaults to false.

boolean get_dir_sizes

If true, the index will recurse through directories to get and display their total sizes. This will impact performance with lots of files.

Defaults to false.

boolean make_thumbs

If true, thumbnails to show in the index will be generated for image and video files. ffmpeg needs to be installed for video thumbnail generation.

Defaults to false.

boolean auto_view

If this and make_thumbs are true, and if more than 50% (or the value of auto_view_threshold) of the files in a directory have thumbnails, the directory will automatically be switched to tiles view.

Defaults to true.

number auto_view_threshold

A float between 0 and 1, representing the percentage of files in a directory that need to have thumbnails for the directory to be switched to tiles view.

Defaults to 0.5.

boolean show_path_subfolders

If true, you'll be able to view the subfolders of a directory when you right-click on it in the path bar. This might affect performance in large directories.

Defaults to true.

boolean debug

If true, debug messages will be logged to the console.

Defaults to false.

Other projects that make this one possible

CyberFiles Lite wouldn't be here without these amazing projects:

• Express
• EJS
• Marked
• Day.js
• Prism