🌲 fstree

A zero-dependency, high-performance CLI tool to visualize your file system.

Render beautiful, customizable directory trees in your terminal and export them to Markdown, JSON, or Plain Text. Built for speed with Bun, compatible with Node.js.

✨ Features

• 🚀 Zero Dependencies: Uses only the standard library.
• ⚡ Bun-Native Speed: Blazing fast directory traversal.
• 📦 Multi-Platform: Works on Windows, macOS, and Linux.
• 🎨 Beautiful Output: Clean Unicode-based tree structure.
• 💾 Export Ready: Save to .md, .json, or .txt natively.
• ⚙️ Smart Defaults: Automatically ignores node_modules, .git, and dist.
• 📏 Size Aware: Optional file size visualization.

🚀 Quick Start

Run it instantly without installing:

# Using bun
bunx @zulfikawr/fstree

# Using npx
npx @zulfikawr/fstree

Installation

# Using bun
bun install -g @zulfikawr/fstree

# Using npm
npm install -g @zulfikawr/fstree

🛠️ Usage

# Print tree of current directory
fstree

# Target a specific path
fstree ./src

# Limit depth
fstree --depth 2

# Show file sizes
fstree --size

# Include hidden files
fstree --hidden

# Custom ignore patterns
fstree --ignore "temp,cache,build"

📤 Exporting

Perfect for READMEs or automated documentation:

# Export as a Markdown code block
fstree --out structure.md

# Export as a JSON AST
fstree --out structure.json

# Export as plain text
fstree --out structure.txt

📊 CLI Options

| Option | Description | Example | | :--- | :--- | :--- | | path | Target directory (positional) | fstree ./src | | --depth | Max recursion depth | --depth 3 | | --ignore | Comma-separated list to skip | --ignore "dist,out" | | --size | Show human-readable file sizes | --size | | --hidden | Include hidden files/folders | --hidden | | --out | Save output to a file | --out tree.md |

💻 Programmatic API

You can also use fstree as a library in your TypeScript/JavaScript projects:

import { walk } from '@zulfikawr/fstree/walker';
import { renderTree } from '@zulfikawr/fstree/renderer';

const tree = await walk('./src', { 
  depth: 2, 
  ignore: ['node_modules', '.git'] 
});

console.log(renderTree(tree, { showSize: true }));

📄 License

Distributed under the MIT License. See LICENSE for more information.