File Explorer

A clean, self-hosted web file explorer built with FastAPI + Vanilla JS

Browse your local filesystem through a minimal, dark-themed web interface — no Electron, no npm, no bloat.

---

📸 Preview

---

✨ Features

• Zero-dependency frontend — pure HTML, CSS and JavaScript, no frameworks
• FastAPI backend — fast, async, and easy to extend
• Dark UI — easy on the eyes, smooth hover transitions
• Directory navigation — click into folders, go back up with one button
• File preview — open files in a new tab directly from the browser
• Smart file sizes — auto-formatted as KB / MB / GB
• Security — all requests are sandboxed to a configurable root directory; directory traversal is blocked at the API level
• HTML source viewer — .html files are served as plain text so you see source, not a rendered page

---

🚀 Quick Start

Requirements: Python 3.14+ (verified version)

# 1. Clone the repo
git clone https://github.com/Defaultik/file-explorer.git
cd file-explorer

# 2. Set your root directory in config.py
#    ALLOWED_DIR = r"C:\Users\You\Documents"

# 3. Run
uvicorn main:app --reload

Then open http://localhost:8000 in your browser.

Installing dependencies

pip

pip install -r requirements.txt

uv

uv sync

---

⚙️ Configuration

Edit config.py:

ALLOWED_DIR = r"C:\Users\Defaultik\Documents\GitHub"

This is the only directory the server will expose. Any request attempting to navigate outside it returns 403 Forbidden.

---

📂 Project Structure

file-explorer/
├── main.py          # FastAPI app & API routes
├── config.py        # Root directory config
├── utils.py         # File size formatting
├── index.html       # App shell
├── static/
│   ├── css/
│   │   └── main.css
│   └── js/
│       ├── visual.js   # DOM rendering & directory loading
│       └── utils.js    # Navigation helpers (goUp)
└── assets/
    ├── rsz_folder.png
    └── rsz_file.png

---

🔌 API Reference

Method	Endpoint	Description
GET	/	Serves the UI
GET	/api/get_dir_content?path=...	Lists directory contents
GET	/api/open_file?path=...	Serves a file for viewing

---

🛡️ Security Notes

• The server enforces path boundaries using os.path.abspath() + str.startswith(ALLOWED_DIR) on every request
• No write operations are exposed — this is a read-only explorer
• Bind to 127.0.0.1 (default) to keep it local; do not expose to a public network without adding authentication

---

🗺️ Roadmap

• Search / filter files by name
• File type icons per extension
• Breadcrumb navigation bar
• Image thumbnail preview
• Drag-and-drop upload support
• Auth layer (Basic / token)

---

🤝 Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you'd like to change.

1. Fork the repo
2. Create a feature branch: git checkout -b feature/cool-thing
3. Commit your changes: git commit -m 'Add cool thing'
4. Push: git push origin feature/cool-thing
5. Open a Pull Request

---

i'll glad to get a star from you ❤️