{"id":13689054,"url":"https://github.com/JakeStanger/filexplorer","last_synced_at":"2025-05-01T23:31:49.795Z","repository":{"id":38380911,"uuid":"233247491","full_name":"JakeStanger/filexplorer","owner":"JakeStanger","description":"A lightweight highly extensible, and highly configurable NodeJS web-based file explorer and utility kit.","archived":false,"fork":false,"pushed_at":"2024-11-05T13:29:44.000Z","size":1049,"stargazers_count":12,"open_issues_count":1,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-11-10T19:02:20.291Z","etag":null,"topics":["docker-image","express","file-sharing","file-upload","hackable","markdown","node","pastebin","pastebin-service","plugins","react","server-side-rendering","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JakeStanger.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-11T14:50:19.000Z","updated_at":"2024-11-05T13:29:40.000Z","dependencies_parsed_at":"2024-02-22T11:31:18.981Z","dependency_job_id":"adf99049-87ce-44b5-89c5-0946ac26b490","html_url":"https://github.com/JakeStanger/filexplorer","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JakeStanger%2Ffilexplorer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JakeStanger%2Ffilexplorer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JakeStanger%2Ffilexplorer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JakeStanger%2Ffilexplorer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JakeStanger","download_url":"https://codeload.github.com/JakeStanger/filexplorer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224282092,"owners_count":17285769,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker-image","express","file-sharing","file-upload","hackable","markdown","node","pastebin","pastebin-service","plugins","react","server-side-rendering","typescript"],"created_at":"2024-08-02T15:01:32.252Z","updated_at":"2024-11-12T13:30:38.899Z","avatar_url":"https://github.com/JakeStanger.png","language":"TypeScript","funding_links":[],"categories":["express"],"sub_categories":[],"readme":"# Filexplorer\n\nA lightweight highly extensible, and highly configurable\nNodeJS web-based file explorer and utility kit.\n\n## Included features\n\nThe included plugins provide the following features:\n\n- Directory listings with file/folder information\n- Intelligent file type resolving\n- Full web interface for viewing files\n  - Markdown rendered in browser\n  - Syntax highlighting for text files\n  - Embedded image, video and audio files\n- Ability to serve raw files, and falls back to doing so\n- Ability to upload files\n- Live scratchpad\n- Breadcrumb navigation\n- Dark mode\n- Non-browser clients are always served raw files\n\nFor more information, please read about each of the plugins below.\n\n![Screenshot showing this readme with markdown plugin](.github/images/app.png)\n\n## Installation\n\n\u003e ⚠️ Note that the package makes use of experimental node features and requires Node \u003e= 18.\n\n### Standalone\n\nClone this repo and run the following to install dependencies and compile:\n\n```bash\nyarn start\nyarn build\n```\n\nRun using `yarn start`. Alternatively you can start using node directly:\n\n```bash\nnode --experimental-wasm-modules --experimental-import-meta-resolve lib\n```\n\n### NPM Package\n\nFilexplorer can be installed as an NPM package,\nwhich is useful if you plan to embed it or develop a plugin.\n\n```bash\nnpm i filexplorer --save\n# or\nyarn add filexplorer\n```\n\nThe package also includes a CLI which can be used for impromptu serving:\n\nNote the CLI does not load the `appListing`, `upload`, or `scratchpad` plugins by default.\n\n```\nλ fe help\n  Usage: fe [options] [command]\n  \n  Commands:\n    help     Display help\n  \n  Options:\n    -H, --help            Output usage information\n    -h, --hostname        The host address to bind to\n    -P, --plugins         The plugins to load, comma separated list\n    -p, --port            The port to bind to\n    -s, --serveDirectory  The path to the directory on disk to serve\n```\n\n### Docker\n\nA docker image is available and can be run like so:\n\n```bash\ndocker run \\\n  -p 5000:5000 \\\n  -v config.corn:/opt/filexplorer/config.corn \\ # Passing a config is optional\n  -v data.db:/data.db \\ # necessary to persist plugin data\n  -v path/to/files:/srv/http \\\n  jakestanger/filexplorer\n```\n\n## Configuration\n\nThe app works out of the box without any configuration,\nand by default all plugins are enabled.\n\nTo override the default configuration,\ncreate a `config` file using one of the following supported formats:\n\n- `config.js`, `config.mjs`, `config.cjs`\n- `config.json`\n- `config.yaml`, `config.yml`\n- `config.toml`\n- `config.corn` (useful for environment variables! see [here](https://github.com/jakestanger/corn#writing-corn))\n\nPlugins may provide their own configuration options,\nwhich are namespaced under the plugin name.\nFor example, the `showHidden` option for the `directoryListing` plugin\nshould be set at `directoryListing.showHidden`.\n\n| Name             | Type     | Default                                                                                                  | Description                                                                                                   |\n|------------------|----------|----------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|\n| `hostname`       | string   | `127.0.0.1`                                                                                              | Host address to listen on                                                                                     |\n| `port`           | number   | `5000`                                                                                                   | Port to listen on                                                                                             |\n| `cors`           | boolean  | `false`                                                                                                  | Whether to enable CORS support                                                                                |\n| `serveDirectory` | string   | `.`                                                                                                      | Path on disk to the directory to serve                                                                        |\n| `baseUrl`        | string   | `/`                                                                                                      | URL path to use as 'root'                                                                                     |\n| `caseSensitive`  | boolean  | `true`                                                                                                   | Whether file route handling should be case sensitive. Disable on Windows or on case-insensitive file systems. |\n| `databasePath`   | string   | `data.db`                                                                                                | Path to create/load database at                                                                               |\n| `plugins`        | string[] | `[\"directoryListing\", \"appListing\", \"markdown\", \"textFile\", \"mediaFile\", \"raw\", \"upload\", \"scratchpad\"]` | List of plugins to load, in the order they should be loaded                                                   |\n\nThe following environment variables are also respected and will override the configuration file:\n\n- `HOSTNAME`\n- `PORT`\n- `SERVE_DIRECTORY`\n- `DATABASE_PATH`\n\n### Example\n\nAn example config file in yaml is shown below,\noverriding the port, serve directory and `directoryListing` plugin options.\n\n```yaml\nport: 5202\nserveDirectory: '/srv/http/public'\n\ndirectoryListing:\n  showHidden = true\n  relativeDates = false\n```\n\n## Included plugins\n\nThe following plugins are\n\n### `directoryListing`\n\nShows a table of files and folders inside a directory.\nEach row has a link to the item, file size, and created/modified dates.\n\n![Directory listing plugin showing root of this repo](.github/images/directoryListing.png)\n\n| Name            | Type    | Default | Description                                                  |\n|-----------------|---------|---------|--------------------------------------------------------------|\n| `showHidden`    | boolean | `false` | Show hidden files and folders                                |\n| `relativeDates` | boolean | `true`  | Display created/modified dates as relative from current time |\n\n### `textFile`\n\nShows the contents of plain text files in the web interface.\nProvides a link to the raw file (requires `raw`), a direct download, and the ability to copy to clipboard.\n\nThe file is syntax highlighted using `highlight.js`.\n\n![Text file plugin showing this package.json](.github/images/textFile.png)\n\n| Name                 | Type    | Default   | Description                                                                                                                            |\n|----------------------|---------|-----------|----------------------------------------------------------------------------------------------------------------------------------------|\n| `highlightTheme`     | string  | `default` | The highlight.js theme to use for light mode. See [here](https://github.com/highlightjs/highlight.js/tree/main/src/styles) for a list  |\n| `highlightThemeDark` | string  | `dark`    | The highlight.js theme to use for dark mode. See [here](https://github.com/highlightjs/highlight.js/tree/main/src/styles) for a list   |\n| `autoHighlight`      | boolean | `false`   | Whether highlight.js should try to automatically detect syntax highlighting if the language could not be determined from the extension |\n| `maxHighlightKb`     | number  | `50`      | The maximum file size in kB that should be highlighted                                                                                 |\n| `handleSvg`          | boolean | `false`   | Whether SVGs should be handled as text                                                                                                 |\n\n### `mediaFile`\n\nShows the contents of images, videos and audio in the web interface.\nProvides a link to the raw file (requires `raw`) and a direct download.\n\n![Media file plugin showing emoji of a cake](.github/images/mediaFile.png)\n\n*This plugin provides no configuration options.*\n\n### `markdown`\n\n\u003e ⚠ This plugin must be loaded **before** `textFile`\n\nRenders markdown files in the web interface. Supports GFM and syntax highlighting.\n\n![Markdown plugin showing this readme](.github/images/markdown.png)\n\n| Name                 | Type    | Default   | Description                                                                                                                           |\n|----------------------|---------|-----------|---------------------------------------------------------------------------------------------------------------------------------------|\n| `highlight`          | boolean | `true`    | Whether code blocks should be highlighted                                                                                             |\n| `highlightTheme`     | string  | `default` | The highlight.js theme to use for light mode. See [here](https://github.com/highlightjs/highlight.js/tree/main/src/styles) for a list |\n| `highlightThemeDark` | string  | `dark`    | The highlight.js theme to use for dark mode. See [here](https://github.com/highlightjs/highlight.js/tree/main/src/styles) for a list  |\n| `gfm`                | boolean | `true`    | Whether to use Github Flavored Markdown                                                                                               |\n\n### `raw`\n\n\u003e ⚠ This plugin must be loaded **after** any other file handling plugins\n\nServes files statically without the web interface, letting the browser handle them.\n\nIf a file's type cannot be determined, the plugin will test if is a text file and force-serve it as one.\n\n*This plugin provides no configuration options.*\n\n### `appListing`\n\n\u003e App URL: `/_/`\n\nShows a list of available app plugins with the ability to navigate to each one.\n\n*This plugin provides no configuration options.*\n\n### `upload`\n\n\u003e App URL: `/_/upload`\n\nProvides the ability to upload files. This can be done programmatically or via the web interface.\nFiles are automatically given random names according to a chosen scheme.\n\nFor example to upload using `cURL`:\n\n```bash\ncurl -F \"file=@Pictures/Cake.png\" -H \"Authorization: 1234\" http://localhost:5000\n```\n\n![Upload plugin web interface](.github/images/upload.png)\n\n| Name            | Type                                                | Default | Description                                                                       |\n|-----------------|-----------------------------------------------------|---------|-----------------------------------------------------------------------------------|\n| `maxFileSize`   | number                                              | `null`  | Maximum allowed file size                                                         |\n| `authorization` | string                                              | `null`  | Expected HTTP `Authorization` header value. Leave blank to disable authorization. |\n| `path`          | string                                              | `/`     | Path relative to served root to upload files to.                                  |\n| `nameScheme`    | `hex \\| uuid \\| cuid \\| adjective-adjective-animal` | `hex`   | Naming scheme to use for generating random names for uploaded files.              |\n\n### `scratchpad`\n\n\u003e App URL: `/_/scratch`\n\nProvides a live scratchpad which can be used for quickly sharing text.\nAny client with the same URL will see the same content and will see changes apply near-instantly.\n\nThere are controls for instantly copying the scratchpad contents and URL.\n\n![Scratchpad plugin, including interface breadcrumbs, showing text in the pad](.github/images/scratchpad.png)\n\n*This plugin provides no configuration options.*\n\n### Use as a library\n\n\u003e ⚠ This is very experimental still. Any issues discussing bugs/improvements are very welcome.\n\n```ts\nimport { App } from 'filexplorer/lib/App.js';\n\n// the promise will not resolve until the server receives a shutdown signal\n// you can optionally pass a config\nawait App.init({ port: 5678 })\n\n// close the server once you're done with it\nApp.server.close();\n```\n\n### Developing plugins\n\n\u003e ⚠ This is very experimental still. Any issues discussing bugs/improvements are very welcome.\n\nPlugins can be loaded from inside this codebase or as a standalone npm package.\n\nA very basic example plugin is shown below:\n\n```ts\nimport {\n  InitEvent,\n  MiddlewarePlugin,\n  PluginManager,\n} from '../../pluginManager.js';\n\ninterface IExampleConfig {\n  // put your plugin config options here\n  greeting: string;\n}\n\n// init hooks are called just before the web server starts\n// and are useful for configuring any required modules based on the app config\nconst init: InitEvent\u003c'example', IExampleConfig\u003e = async ({ config }) =\u003e {\n  // do init things!\n  console.log(config.example.greeting ?? 'hello', 'world');\n};\n\n// middleware can be used for handling files/directories\n// this is just express.js middleware under the hood\nconst exampleMiddeware: MiddlewarePlugin\u003c'example', IExampleConfig\u003e = async ({\n                                                                               req,\n                                                                               res,\n                                                                               next\n                                                                             }) =\u003e {\n  res.send('hello from example');\n};\n\n// other available features for plugins:\n// - `withAppMiddleware`: register middleware on a specific route to create an app\n// - `withSocketIO`: passes a socket to a callback when the socket connects\n// - `withDatabaseTable`: Ensures a database table exists with the provided schema\nPluginManager.register('example').onInit(init).withMiddleware(markdown);\n```\n\nYour plugin can be loaded by adding it to the `plugins` config option. More information on this below:\n\n#### Embedded\n\nCreate a new folder in `src/plugins` that matches your plugin name.\nThis folder *must* contain an `index.ts` (or `.js` or `.mts` or `.mjs`) file.\n\nHandlebars templates should be placed in the `resources/plugins` folder in the root of this repo.\n\nTo load an embedded plugin, add the plugin directory name to `plugins` config option.\n\n#### Separate package\n\nCreate a new package. If necessary add `filexplorer` as a dev/peer dependency for development.\nEnsure your package has a `main` entrypoint set in the `package.json`.\n\nHandlebars templates should be placed in the `resources/plugins` folder in the root of your package.\n\nTo load separate-package plugins, add the plugin package name to the `plugins` config option.\n\n### Theming\n\nThe app makes use of modern CSS features like custom properties to make theming as easy as possible.\nTo make global CSS changes, apply these in `public/index.css`.\nFor plugin-specific changes, these should be placed in the appropriate `head.hbs` template.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJakeStanger%2Ffilexplorer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FJakeStanger%2Ffilexplorer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJakeStanger%2Ffilexplorer/lists"}