Filexplorer

A lightweight highly extensible, and highly configurable NodeJS web-based file explorer and utility kit.

Included features

The included plugins provide the following features:

• Directory listings with file/folder information
• Intelligent file type resolving
• Full web interface for viewing files
  • Markdown rendered in browser
  • Syntax highlighting for text files
  • Embedded image, video and audio files
• Ability to serve raw files, and falls back to doing so
• Ability to upload files
• Live scratchpad
• Breadcrumb navigation
• Dark mode
• Non-browser clients are always served raw files

For more information, please read about each of the plugins below.

Installation

⚠️ Note that the package makes use of experimental node features and requires Node >= 18.

Standalone

Clone this repo and run the following to install dependencies and compile:

yarn start
yarn build

Run using yarn start. Alternatively you can start using node directly:

node --experimental-wasm-modules --experimental-import-meta-resolve lib

NPM Package

Filexplorer can be installed as an NPM package, which is useful if you plan to embed it or develop a plugin.

npm i filexplorer --save
# or
yarn add filexplorer

The package also includes a CLI which can be used for impromptu serving:

Note the CLI does not load the appListing, upload, or scratchpad plugins by default.

λ fe help
  Usage: fe [options] [command]
  
  Commands:
    help     Display help
  
  Options:
    -H, --help            Output usage information
    -h, --hostname        The host address to bind to
    -P, --plugins         The plugins to load, comma separated list
    -p, --port            The port to bind to
    -s, --serveDirectory  The path to the directory on disk to serve

Docker

A docker image is available and can be run like so:

docker run \
  -p 5000:5000 \
  -v config.corn:/opt/filexplorer/config.corn \ # Passing a config is optional
  -v data.db:/data.db \ # necessary to persist plugin data
  -v path/to/files:/srv/http \
  jakestanger/filexplorer

Configuration

The app works out of the box without any configuration, and by default all plugins are enabled.

To override the default configuration, create a config file using one of the following supported formats:

• config.js, config.mjs, config.cjs
• config.json
• config.yaml, config.yml
• config.toml
• config.corn (useful for environment variables! see here)

Plugins may provide their own configuration options, which are namespaced under the plugin name. For example, the showHidden option for the directoryListing plugin should be set at directoryListing.showHidden.

| Name | Type | Default | Description | |------------------|----------|----------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------| | hostname | string | 127.0.0.1 | Host address to listen on | | port | number | 5000 | Port to listen on | | cors | boolean | false | Whether to enable CORS support | | serveDirectory | string | . | Path on disk to the directory to serve | | baseUrl | string | / | URL path to use as 'root' | | caseSensitive | boolean | true | Whether file route handling should be case sensitive. Disable on Windows or on case-insensitive file systems. | | databasePath | string | data.db | Path to create/load database at | | plugins | string[] | ["directoryListing", "appListing", "markdown", "textFile", "mediaFile", "raw", "upload", "scratchpad"] | List of plugins to load, in the order they should be loaded |

The following environment variables are also respected and will override the configuration file:

• HOSTNAME
• PORT
• SERVE_DIRECTORY
• DATABASE_PATH

Example

An example config file in yaml is shown below, overriding the port, serve directory and directoryListing plugin options.

port: 5202
serveDirectory: '/srv/http/public'

directoryListing:
  showHidden = true
  relativeDates = false

Included plugins

The following plugins are

directoryListing

Shows a table of files and folders inside a directory. Each row has a link to the item, file size, and created/modified dates.

| Name | Type | Default | Description | |-----------------|---------|---------|--------------------------------------------------------------| | showHidden | boolean | false | Show hidden files and folders | | relativeDates | boolean | true | Display created/modified dates as relative from current time |

textFile

Shows the contents of plain text files in the web interface. Provides a link to the raw file (requires raw), a direct download, and the ability to copy to clipboard.

The file is syntax highlighted using highlight.js.

| Name | Type | Default | Description | |----------------------|---------|-----------|----------------------------------------------------------------------------------------------------------------------------------------| | highlightTheme | string | default | The highlight.js theme to use for light mode. See here for a list | | highlightThemeDark | string | dark | The highlight.js theme to use for dark mode. See here for a list | | autoHighlight | boolean | false | Whether highlight.js should try to automatically detect syntax highlighting if the language could not be determined from the extension | | maxHighlightKb | number | 50 | The maximum file size in kB that should be highlighted | | handleSvg | boolean | false | Whether SVGs should be handled as text |

mediaFile

Shows the contents of images, videos and audio in the web interface. Provides a link to the raw file (requires raw) and a direct download.

This plugin provides no configuration options.

markdown

⚠ This plugin must be loaded before textFile

Renders markdown files in the web interface. Supports GFM and syntax highlighting.

| Name | Type | Default | Description | |----------------------|---------|-----------|---------------------------------------------------------------------------------------------------------------------------------------| | highlight | boolean | true | Whether code blocks should be highlighted | | highlightTheme | string | default | The highlight.js theme to use for light mode. See here for a list | | highlightThemeDark | string | dark | The highlight.js theme to use for dark mode. See here for a list | | gfm | boolean | true | Whether to use Github Flavored Markdown |

raw

⚠ This plugin must be loaded after any other file handling plugins

Serves files statically without the web interface, letting the browser handle them.

If a file's type cannot be determined, the plugin will test if is a text file and force-serve it as one.

This plugin provides no configuration options.

appListing

App URL: /_/

Shows a list of available app plugins with the ability to navigate to each one.

This plugin provides no configuration options.

upload

App URL: /_/upload

Provides the ability to upload files. This can be done programmatically or via the web interface. Files are automatically given random names according to a chosen scheme.

For example to upload using cURL:

curl -F "file=@Pictures/Cake.png" -H "Authorization: 1234" http://localhost:5000

| Name | Type | Default | Description | |-----------------|-----------------------------------------------------|---------|-----------------------------------------------------------------------------------| | maxFileSize | number | null | Maximum allowed file size | | authorization | string | null | Expected HTTP Authorization header value. Leave blank to disable authorization. | | path | string | / | Path relative to served root to upload files to. | | nameScheme | hex \| uuid \| cuid \| adjective-adjective-animal | hex | Naming scheme to use for generating random names for uploaded files. |

scratchpad

App URL: /_/scratch

Provides a live scratchpad which can be used for quickly sharing text. Any client with the same URL will see the same content and will see changes apply near-instantly.

There are controls for instantly copying the scratchpad contents and URL.

This plugin provides no configuration options.

Use as a library

⚠ This is very experimental still. Any issues discussing bugs/improvements are very welcome.

import { App } from 'filexplorer/lib/App.js';

// the promise will not resolve until the server receives a shutdown signal
// you can optionally pass a config
await App.init({ port: 5678 })

// close the server once you're done with it
App.server.close();

Developing plugins

⚠ This is very experimental still. Any issues discussing bugs/improvements are very welcome.

Plugins can be loaded from inside this codebase or as a standalone npm package.

A very basic example plugin is shown below:

import {
  InitEvent,
  MiddlewarePlugin,
  PluginManager,
} from '../../pluginManager.js';

interface IExampleConfig {
  // put your plugin config options here
  greeting: string;
}

// init hooks are called just before the web server starts
// and are useful for configuring any required modules based on the app config
const init: InitEvent<'example', IExampleConfig> = async ({ config }) => {
  // do init things!
  console.log(config.example.greeting ?? 'hello', 'world');
};

// middleware can be used for handling files/directories
// this is just express.js middleware under the hood
const exampleMiddeware: MiddlewarePlugin<'example', IExampleConfig> = async ({
                                                                               req,
                                                                               res,
                                                                               next
                                                                             }) => {
  res.send('hello from example');
};

// other available features for plugins:
// - `withAppMiddleware`: register middleware on a specific route to create an app
// - `withSocketIO`: passes a socket to a callback when the socket connects
// - `withDatabaseTable`: Ensures a database table exists with the provided schema
PluginManager.register('example').onInit(init).withMiddleware(markdown);

Your plugin can be loaded by adding it to the plugins config option. More information on this below:

Embedded

Create a new folder in src/plugins that matches your plugin name. This folder must contain an index.ts (or .js or .mts or .mjs) file.

Handlebars templates should be placed in the resources/plugins folder in the root of this repo.

To load an embedded plugin, add the plugin directory name to plugins config option.

Separate package

Create a new package. If necessary add filexplorer as a dev/peer dependency for development. Ensure your package has a main entrypoint set in the package.json.

Handlebars templates should be placed in the resources/plugins folder in the root of your package.

To load separate-package plugins, add the plugin package name to the plugins config option.

Theming

The app makes use of modern CSS features like custom properties to make theming as easy as possible. To make global CSS changes, apply these in public/index.css. For plugin-specific changes, these should be placed in the appropriate head.hbs template.