chart-page-handler 1.0.0

package/README.md

@@ -0,0 +1,106 @@
+# server-file-explorer
+
+A self-contained filesystem manager and file explorer served automatically from any Node.js server. 
+
+Allows you to **view, access, traverse, and download** files and directories (as auto-zipped archives) directly from the host server.
+
+## 🚀 Features
+
+- **Self-contained Client**: Zero build steps. Serves a highly-polished responsive HTML interface (dark/light mode support, list/grid view toggles, code viewer modal, search/filter).
+- **Directory Zip Downloads**: Uses `archiver` under the hood to compress and stream folders as `.zip` downloads on-the-fly.
+- **Universal Middleware**: Compatible with **Express**, **Vite Dev Server**, and **native Node.js HTTP servers** using a single request listener function.
+- **Secure Sandbox Option**: Configurable root path (traversal can be locked to project directory or open to system root).
+
+## 💿 Installation
+
+Install the package via npm:
+
+```bash
+npm install server-file-explorer
+```
+
+## 🛠️ Usage
+
+### 1. Express Integration
+
+Mount it as a custom middleware. When you navigate to `/files`, the file explorer UI will load:
+
+```javascript
+import express from 'express';
+import { fileExplorer } from 'server-file-explorer';
+
+const app = express();
+
+app.use((req, res, next) => {
+  // Option 'root' sets starting directory path (defaults to process.cwd())
+  // Option 'route' sets base path to listen on (defaults to '/files')
+  const handled = fileExplorer(req, res, { 
+    root: process.cwd(), 
+    route: '/files' 
+  });
+  
+  if (!handled) {
+    next();
+  }
+});
+
+app.listen(3000);
+```
+
+### 2. Vite Dev Server Integration
+
+Configure it inside `vite.config.js` to enable the file manager in local development mode:
+
+```javascript
+import { defineConfig } from 'vite';
+import { fileExplorer } from 'server-file-explorer';
+
+export default defineConfig({
+  plugins: [
+    {
+      name: 'vite-plugin-file-explorer',
+      configureServer(server) {
+        server.middlewares.use((req, res, next) => {
+          const handled = fileExplorer(req, res);
+          if (!handled) next();
+        });
+      }
+    }
+  ]
+});
+```
+
+### 3. Native Node.js HTTP Server
+
+Use it directly inside Node's native `http.createServer`:
+
+```javascript
+import http from 'node:http';
+import { fileExplorer } from 'server-file-explorer';
+
+const server = http.createServer((req, res) => {
+  const handled = fileExplorer(req, res);
+  if (handled) return; // Handled by server-file-explorer
+  
+  // Your standard routing here...
+  res.writeHead(404);
+  res.end('Not Found');
+});
+
+server.listen(5178);
+```
+
+## ⚙️ Options
+
+The `fileExplorer` handler accepts a configuration options object:
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `root` | `string` | `process.cwd()` | Absolute path to target filesystem root folder. |
+| `route` | `string` | `/files` | Base path used to access the file explorer page. |
+| `apiRoute` | `string` | `/api/files` | Base path used for REST calls. |
+| `allowParent` | `boolean` | `true` | Allows users to traverse outside and navigate to parent directories. |
+
+## ⚖️ License
+
+MIT