This project is generated by Gemini CLI. Please see conversation.md for a summary of requests.

S3 Bucket Browser

S3 Bucket Browser is a single-file, zero-dependency HTML application for browsing public Amazon S3 buckets. It works entirely in the browser using the S3 XML API, making it an ideal lightweight solution for sharing open data datasets.

Features

Zero Dependencies: A single index.html file. No build steps, no external libraries (like jQuery or React), and no backend server required.
Dual View Modes:
- Folder View (Default): Navigate directories like a traditional file manager.
- Recursive View: Flatten the directory structure to find files deep within subfolders. Supports recursive search starting from any sub-directory.
Robust Navigation:
- Browser History: Full support for Back/Forward buttons.
- Deep Linking: The bucket, current path, and view mode are stored in the URL hash, making it easy to share specific file lists.
Smart Connectivity:
- Auto-Proxy: Automatically detects network/CORS errors and switches to a proxy (using corsproxy.io) to ensure access to buckets without CORS headers (e.g., human-pangenomics).
- Region Support: Handles bucket names with region suffixes (e.g., bucket.us-east-1).
- Auto-Configuration: If hosted directly in an S3 bucket (e.g., as a static website), it automatically detects the bucket URL and hides the configuration controls.
Enhanced UI:
- Smart Search: Filter files by name instantly.
- Sorting: Sort by filename, size, or last modified date.
- Readable Data: Fixed-width fonts for file lists, standard numeric alignment, and clear 24-hour timestamps (YYYY-MM-DD HH:mm:ss).
- Compact Design: Optimized for viewing buckets with thousands of files.

Usage

Method 1: Local Use (Standalone)

Download index.html.
Open it in any modern web browser.
Enter an S3 bucket name (e.g., openhgl or bucket.region) or a full URL.
Click Load Bucket.
- Note: If the bucket requires CORS headers but doesn't provide them, the tool will automatically attempt to fetch data via a proxy.

Method 2: Hosting on S3

Upload index.html to the root of your public S3 bucket.
Ensure your bucket has Static Website Hosting enabled or is publicly readable.
CORS Configuration: For direct client-side access (faster than proxy), add the following CORS configuration to your bucket permissions in the AWS Console:
```
[
    {
        "AllowedHeaders": ["*"],
        "AllowedMethods": ["GET"],
        "AllowedOrigins": ["*"],
        "MaxAgeSeconds": 3000
    }
]
```
Navigate to the file (e.g., https://my-bucket.s3.amazonaws.com/index.html). The tool will automatically load your bucket's contents and hide the input bar.

Technology Stack

HTML5 / CSS3 (Flexbox, Grid)
Vanilla JavaScript (ES6+)
S3 ListObjectsV2 API (XML parsing)

License

MIT

s3bb

README