SpaceBadger

SpaceBadger is a macOS storage analysis app built with Electron, React, and TypeScript. It focuses on scanning folders, visualizing disk usage, and comparing historical snapshots to track growth over time.

Chinese README: README.zh.md

Features

• Worker-threaded scanning with progress updates
• Snapshot persistence in SQLite (metadata + folder tree)
• Treemap, Sunburst, and List visualizations
• Snapshot history management (load, rename, delete)
• Snapshot comparison with top growth/shrink lists
• Theme switching (light, dark, auto)

Tech Stack

• Electron + electron-vite
• React + TypeScript
• Zustand state management
• D3 (Treemap) and ECharts (Sunburst, charts)
• better-sqlite3 for local persistence

Project Status

• Core scanning, storage, and visualization flows are in place.
• Trend analysis backend exists; chart UI is planned.
• Comparison highlight in Treemap is planned.

Recommended IDE Setup

• VSCode + ESLint + Prettier

Project Setup

Prerequisites

• Node.js 18+ (or 20+)
• pnpm

Install

$ pnpm install

Development

$ pnpm dev

Build

# For windows
$ pnpm build:win

# For macOS
$ pnpm build:mac

# For Linux
$ pnpm build:linux

Tests

$ pnpm test:run

Lint and Typecheck

$ pnpm lint
$ pnpm typecheck

Project Structure

src/
  main/        Electron main process (IPC, DB, scanning, analysis)
  preload/     Preload bridge (typed IPC APIs)
  renderer/    React UI and visualizations
  types/       Shared data models and IPC payload types

Data Storage

SQLite is used for snapshots and settings. The database is created at:

• app.getPath('userData')/spacebadger.db

Docs

• mac-storage-analyzer-prd.md
• DEVELOPMENT_PLAN.md
• CICD.md