A powerful developer tool for browsing and managing S3-compatible storage and MongoDB databases through a sleek web UI. Built with TypeScript, designed for developers who need quick, visual access to their data stores during development. 🚀

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

# Global installation (recommended for CLI usage)
npm install -g @git.zone/tsview
# or
pnpm add -g @git.zone/tsview

# Local installation (for programmatic usage)
npm install @git.zone/tsview
# or
pnpm add @git.zone/tsview

Features ✨

🗄️ S3 Storage Browser

Column View Navigation - Mac Finder-style interface with resizable columns for intuitive file browsing
List View - Traditional key-based view with hierarchical navigation
Real-time Preview - View images, JSON, text files, and more directly in the browser
Bucket Management - Create, delete, and switch between buckets
File Operations - Upload, download, delete objects with ease
Smart Content Type Detection - Automatic content type recognition for 20+ file types
Breadcrumb Navigation - Easy path traversal with clickable breadcrumbs

🍃 MongoDB Browser

Database Explorer - Hierarchical navigation through databases and collections
Document Viewer - Paginated table view with sorting and filtering
Document Editor - Full CRUD operations with JSON syntax highlighting
Index Management - View, create, and drop indexes
Aggregation Pipeline - Run custom aggregation queries (coming soon)
Collection Stats - View document counts, sizes, and storage metrics
Server Status - Monitor connection info and server health

🎨 Modern Web UI

🌙 Dark theme designed for developer comfort
📱 Responsive layout with resizable panels
⌨️ Keyboard-friendly navigation
🔌 Zero external runtime dependencies in the browser

Quick Start 🚀

1. Configure Your Connection

Create a .nogit/env.json file in your project root:

{
  "S3_ENDPOINT": "localhost",
  "S3_PORT": "9000",
  "S3_ACCESSKEY": "minioadmin",
  "S3_SECRETKEY": "minioadmin",
  "S3_USESSL": false,
  "MONGODB_URL": "mongodb://localhost:27017",
  "MONGODB_NAME": "mydb"
}

2. Launch the Viewer

tsview

That's it! 🎉 Your browser will automatically open to the viewer interface.

CLI Usage

# Start viewer with auto-detected port (starts from 3010)
tsview

# Force a specific port
tsview --port 3000

# S3 browser only
tsview s3

# MongoDB browser only
tsview mongo
# or
tsview mongodb

Configuration via npmextra.json

For project-level configuration, add a @git.zone/tsview section to your npmextra.json:

{
  "@git.zone/tsview": {
    "port": 3015,
    "killIfBusy": true,
    "openBrowser": false
  }
}

Option	Type	Default	Description
`port`	`number`	auto	Fixed port to use (auto-finds from 3010 if not set)
`killIfBusy`	`boolean`	`false`	Kill existing process if port is busy
`openBrowser`	`boolean`	`true`	Automatically open browser on start

Priority order: CLI --port flag > npmextra.json config > auto-detect

Programmatic API

Use tsview as a library in your own tools:

import { TsView } from '@git.zone/tsview';

const viewer = new TsView();

// Option 1: Load from .nogit/env.json (gitzone service format)
await viewer.loadConfigFromEnv();

// Option 2: Configure programmatically for local development
viewer.setS3Config({
  endpoint: 'localhost',
  port: 9000,
  accessKey: 'minioadmin',
  accessSecret: 'minioadmin',
  useSsl: false
});

viewer.setMongoConfig({
  mongoDbUrl: 'mongodb://localhost:27017',
  mongoDbName: 'mydb'
});

// Option 3: Configure for cloud services
viewer.setS3Config({
  endpoint: 's3.amazonaws.com',
  accessKey: 'AKIAXXXXXXX',
  accessSecret: 'your-secret-key',
  useSsl: true,
  region: 'us-east-1'
});

viewer.setMongoConfig({
  mongoDbUrl: 'mongodb+srv://user:pass@cluster.mongodb.net',
  mongoDbName: 'production'
});

// Start the server
const port = await viewer.start();
console.log(`Viewer running on http://localhost:${port}`);

// Or specify a port
await viewer.start(3500);

// Graceful shutdown
await viewer.stop();

Environment Variables

The following environment variables are supported in .nogit/env.json:

S3 Configuration

Variable	Description
`S3_ENDPOINT`	S3 server hostname
`S3_PORT`	S3 server port (optional)
`S3_ACCESSKEY`	Access key ID
`S3_SECRETKEY`	Secret access key
`S3_USESSL`	Use HTTPS (`true`/`false`)

MongoDB Configuration

Variable	Description
`MONGODB_URL`	Full MongoDB connection string
`MONGODB_NAME`	Default database name

Or use individual MongoDB variables:

Variable	Description
`MONGODB_HOST`	MongoDB hostname
`MONGODB_PORT`	MongoDB port
`MONGODB_USER`	Username
`MONGODB_PASS`	Password
`MONGODB_NAME`	Database name

Supported S3 Providers

tsview works with any S3-compatible storage:

Provider	Status
MinIO	✅ Perfect for local development
AWS S3	✅ Amazon's object storage
DigitalOcean Spaces	✅ Simple object storage
Backblaze B2	✅ S3-compatible API
Cloudflare R2	✅ Zero egress fees
Wasabi	✅ Hot cloud storage
Self-hosted	✅ Any S3-compatible server

Supported File Types for Preview

Category	Extensions
Images	`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg`
Text	`.txt`, `.md`, `.log`, `.sh`, `.env`
Code	`.json`, `.js`, `.ts`, `.tsx`, `.jsx`, `.html`, `.css`
Data	`.csv`, `.xml`, `.yaml`, `.yml`
Documents	`.pdf`

Development

# Clone the repository
git clone https://code.foss.global/git.zone/tsview.git
cd tsview

# Install dependencies
pnpm install

# Build (bundles frontend + compiles TypeScript)
pnpm build

# Development mode with hot reload
pnpm run watch

# Run tests
pnpm test

Architecture

tsview/
├── ts/                    # Backend TypeScript source
│   ├── api/               # TypedRequest API handlers
│   │   ├── handlers.s3.ts
│   │   └── handlers.mongodb.ts
│   ├── config/            # Configuration management
│   ├── server/            # Web server (TypedServer)
│   ├── interfaces/        # Shared TypeScript interfaces
│   └── tsview.classes.tsview.ts  # Main class
├── ts_web/                # Frontend TypeScript source
│   ├── elements/          # Web components (LitElement)
│   ├── services/          # API client service
│   ├── styles/            # Shared theme styles
│   └── utilities/         # Helper functions
└── cli.ts.js              # CLI entry point

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@git.zone/tsview