TagSpaces

Self-Hosted

Organize files offline with tags and local web clipping

Active(100)

4.6kstars

0views

Updated 3 days ago

1 / 5

Overview

Discover what makes TagSpaces powerful

TagSpaces is a **fully offline, cross‑platform file manager** that treats the filesystem itself as its database. By embedding tags directly in filenames or storing them in lightweight sidecar files, it eliminates the need for a server‑side metadata store. The application is built with **React.js** and **MUI** for a responsive UI, while the desktop distribution leverages **Electron** to expose native file‑system APIs. The core logic lives in the `renderer/` directory, with the Electron main process handling inter‑process communication (IPC) and system integration. This architecture allows developers to extend or replace the UI without touching low‑level file operations.

Frontend

Desktop Runtime

Data Layer

Packaging

Overview

TagSpaces is a fully offline, cross‑platform file manager that treats the filesystem itself as its database. By embedding tags directly in filenames or storing them in lightweight sidecar files, it eliminates the need for a server‑side metadata store. The application is built with React.js and MUI for a responsive UI, while the desktop distribution leverages Electron to expose native file‑system APIs. The core logic lives in the renderer/ directory, with the Electron main process handling inter‑process communication (IPC) and system integration. This architecture allows developers to extend or replace the UI without touching low‑level file operations.

Architecture

Frontend: React 18 with functional components, hooks, and context for state management. Styling is handled by MUI v5, enabling theme overrides and dark‑mode support out of the box.
Desktop Runtime: Electron 25 serves as a bridge to Node.js APIs, exposing file system access (fs, path) and native dialogs. The boilerplate used is the Electron React Boilerplate, which ships with Webpack, Babel, and Hot‑Reloading configured for both main and renderer processes.
Data Layer: No relational or NoSQL database; metadata is persisted as JSON sidecar files (.tsmeta) alongside the target file or in a centralized tags.json for bulk operations. This design keeps TagSpaces lightweight and portable.
Packaging: The docker/ directory contains a minimal Dockerfile that bundles the Electron app into an Alpine‑based image, enabling containerized deployments on headless servers or NAS devices.

Core Capabilities

Feature	Technical Detail
Tagging	Tags are stored as JSON in sidecar files or appended to filenames (`file.tag1.tag2.ext`). The API exposes `addTag(filePath, tag)`, `removeTag(filePath, tag)`, and `listTags()` for programmatic use.
Search & Filtering	Implements a fuzzy search engine (Fuse.js) over filenames and tags, with support for regex and custom filters exposed via the `search(query)` API.
Note & To‑Do	Markdown/HTML files are rendered using `react-markdown` and a lightweight editor (`Draft.js`). Notes can be linked to files via metadata entries.
Media Playback	Uses the HTML5 `<video>` and `<audio>` elements, with a custom player UI built on MUI components.
Web Clipper	Browser extensions (Chrome, Edge, Firefox) capture pages as Markdown or HTML and upload them to the local filesystem via a custom protocol (`tagspaces://`).

Deployment & Infrastructure

TagSpaces can be run as a native desktop app, a web‑only build (npm run build:web), or inside Docker. The Docker image exposes the application on a specified port and can be mounted to a host directory, making it ideal for NAS or Raspberry Pi setups. Because the app is entirely client‑side, scaling is trivial: each instance runs independently without a central server. For environments that require headless operation, the Electron main process can be wrapped in an Xvfb session to render UI components without a display.

Integration & Extensibility

The project ships with a plugin system that allows developers to inject new panels, context menu actions, or file handlers. Plugins are simple JavaScript modules that register via the pluginRegistry exposed in the renderer context. Additionally, TagSpaces offers a webhook API: by exposing an HTTP endpoint (via the express server bundled in Electron), external services can trigger actions such as tagging a file when an event occurs in GitHub or Jira. The absence of a backend also means that any custom logic can be written directly in the Electron main process and accessed through IPC.

Developer Experience

Configuration: Settings are stored in a JSON file (settings.json) located in the user data directory, making it easy to script or version control. The UI provides a comprehensive settings panel with live preview.
Documentation: The official docs include architecture diagrams, API references, and a plugin guide. The community forum on Discourse is active, with frequent contributions from core maintainers.
Community & Licensing: Distributed under the MIT license, TagSpaces encourages contributions. The GitHub repo has a healthy issue tracker and pull request flow, with CI built on GitHub Actions.

Use Cases

Personal Knowledge Management – Store markdown notes, PDFs, and images locally with tags for quick retrieval without a cloud service.
Enterprise File Cataloging – Deploy on a company’s internal network to provide employees with an offline file explorer that respects corporate privacy policies.
Developer Toolchain – Use TagSpaces as a lightweight file manager for source code, logs, and build artifacts while keeping the workspace portable across machines.
IoT & Edge Devices – Run the Docker image on a Raspberry Pi to organize media or sensor data collected locally, with tags enabling automated processing pipelines.

Advantages

Zero‑Backend: Eliminates the need for a database server, reducing attack surface and operational overhead.
Performance: File operations are direct filesystem calls; no ORM or query parsing adds latency.
Privacy‑First: All data remains on the local machine; no telemetry or user accounts are required.
Extensibility: The plugin API and sidecar metadata model let developers add custom workflows without altering the core