File Browser

A lightweight web‑based file browser written in TypeScript and Express. It allows you to explore a directory tree on the server, create zip archives on‑the‑fly, delete files, and download single files. The UI is a simple static HTML page served by Express.

---

Table of Contents

• Prerequisites
• Installation
• Environment Setup
• Available Scripts
• Running the App
• Using the Browser UI
• API Endpoints
• License

---

Prerequisites

Requirement	Version
Node.js	≥ 20.0.0
npm	≥ 10.0.0

You can install Node from nodejs.org.

---

Installation

# Clone the repository
git clone https://github.com/Coder-ak/file-browser.git
cd file-browser

# Install dependencies
npm install

---

Environment Setup

The server reads the root directory to expose via a BASE_DIR environment variable. Create a .env file in the project root:

BASE_DIR=/absolute/path/to/serve
PORT=3000

Security note: The API includes a basic directory‑traversal guard that checks the BASE_DIR prefix. Do not expose a directory that contains sensitive data.

---

Available Scripts

Script	Description
npm run build	Compile TypeScript → dist/
npm start	Start a production build (node dist/server.js)
npm run dev	Run the development server with hot‑reload (ts-node-dev)
npm run clean	Delete the dist/ folder
npm test	Placeholder test script

---

Running the App

Development

# Set BASE_DIR in .env and run dev server
npm run dev

Visit http://localhost:3000 to see the UI.

Production

# Build & start
npm run build
npm start

The server will listen on http://localhost:3000.

---

Using the Browser UI

Feature	How to use
Browse	Click folders in the table or use the breadcrumb.
Zip	Click Zip next to a folder or file, choose a name, and hit Create. A progress bar will appear.
Cancel Zip	Close the modal or click the Cancel button.
Delete	Click Del next to an item and confirm.
Download URL	Click Copy next to a file to copy a secure download link.
Copy URL	The link points to /api/download?path=<encoded_path>.

---

API Endpoints

All responses are JSON unless noted. All requests are relative to the server root (http://localhost:3000).

Method	Path	Description	Payload / Query
GET	/api/list	List directory contents	?path=<encoded_path> (default "")
POST	/api/zip	Create zip archive	{"sourcePath":"<path>","zipName":"<name>","progressId":"<id>"}
GET	/api/zip-progress/:id	Stream zip progress via SSE	N/A
POST	/api/zip-cancel	Cancel an in‑progress zip	{"progressId":"<id>"}
DELETE	/api/delete	Delete a file or directory	{"path":"<path>"}
GET	/api/download	Download a single file	?path=<encoded_path>

All paths are resolved relative to BASE_DIR. The server protects against directory traversal by verifying the resolved path starts with BASE_DIR.

---

License

This project is licensed under the ISC License – see the LICENSE file for details.