Skip to content

README.md

Latest commit

 

History

History
345 lines (217 loc) · 6.14 KB

README.md

File metadata and controls

345 lines (217 loc) · 6.14 KB

📁 Folder Structure Visualizer

Turn ASCII folder trees into working React + Node projects in seconds.

Paste a structure → visualize it → export a working project.

Preview

Working

Example Use

Search Features

Search Search

✨ Core Features

📂 ASCII → Visual Tree

  • Paste standard ASCII folder structures
  • Supports ├──, └──, │, and indentation-based formats

🌳 Interactive Explorer

  • Expand/collapse folders
  • Smooth animations
  • Clean IDE-like experience

🔍 Smart Search

  • Real-time filtering
  • Auto-expands matching folders
  • Highlights matches

📊 Counters & Icons

  • File/folder counts
  • Intelligent file-type icons

📋 Utilities

  • Copy full path
  • Export tree as Markdown

📦 Scaffold Generator (Main Feature)

Generate a fully working project ZIP directly from your structure.

Supported Presets

  • React + Vite (JSX)
  • React + Vite + Tailwind
  • React + Vite + TypeScript (TSX)
  • React + Vite + TSX + Tailwind
  • Node + Express backend
  • Root .gitignore

What You Get

  • Frontend with working dev server
  • Backend with Express + /api/status
  • Vite proxy preconfigured
  • Clean starter UI

Yes — it actually runs. Not fake files.

⚠️ Important Behavior (Read This Once)

⚠️ Small note of caution:

  • If, after clicking the "Parse Structure" button and the root project name changes to whatever you gave, it means the structure got parsed correctly.

  • Else, check the ASCII structure once.

1. Root vs Custom Placement

You have two modes:

🟢 Root Mode

Scaffold is created at root:

frontend/
backend/

Run from:

cd frontend
npm install
npm run dev

🟡 Custom Placement Mode

Example:

Parent: WORK_PLEASE
Target: apps

Output:

WORK_PLEASE/apps/frontend
WORK_PLEASE/apps/backend

👉 You MUST run from THIS location:

cd WORK_PLEASE/apps/frontend
npm install
npm run dev

❌ Running from existing apps/frontend (from your input tree) will fail.

2. Placeholder Folder Conflicts

If your input already contains:

apps/frontend
apps/backend

Those are treated as plain folders, not scaffold apps.

➡️ The tool generates NEW working apps in the selected destination.

3. Empty Config Handling

Files like:

package.json
vite.config.js

may be empty in your input tree.

✔️ The tool replaces them with valid scaffold configs when presets are enabled.

4. Extra Folders May Appear

Example:

src/utils/

These may be added by presets.

✔️ Safe to delete ✔️ Required for some setups

(Translation: don’t panic, nothing is broken.)

5. Tailwind Behavior

  • With Tailwind → no App.css
  • Without Tailwind → standard CSS setup

6. Node Version Requirement

Generated projects use Vite 8

You need:

  • Node.js 20.19+ OR
  • Node.js 22.12+

7. Module System Behavior (Advanced)

The generated project uses different module systems:

  • Frontend → ES Modules (type: "module")
  • Backend (JS mode) → CommonJS (require)

This is intentional for compatibility and simplicity.

⚠️ If you modify backend to use ESM, you must update:

  • package.json
  • import syntax (import instead of require)

⚛️ Generated Frontend Structure

JSX Mode

  • App.jsx
  • main.jsx
  • vite.config.js

TSX Mode

  • App.tsx
  • main.tsx
  • vite.config.ts
  • tsconfig.json

Tailwind Adds

  • tailwind.config.js
  • postcss.config.js

🧠 How It Works

  1. Parse ASCII → structured JSON tree
  2. Render interactive collapsible UI
  3. Merge scaffold presets into user-defined structure
  4. Replace empty config placeholders with working defaults
  5. Generate production-ready ZIP using JSZip

🚀 Installation (Local Dev)

git clone https://github.com/Far-200/folder-structure-visualizer
cd folder-structure-visualizer/frontend
npm install
npm run dev

🧪 Testing Reality (Honest Section)

This tool has been tested with:

  • Large monorepo-style trees
  • Nested folders (10+ levels)
  • JSX + TSX combinations
  • Tailwind on/off
  • Backend on/off
  • Root + custom placement

⚠️ Known Limitations

  • Parser is flexible, not strict — expects reasonable ASCII format
  • Custom placement can confuse users if they run wrong folders (Trust me on this 🫠)
  • Not designed for malformed or inconsistent tree syntax
  • Mixing ESM (frontend) and CommonJS (backend JS mode) can confuse beginners
  • Large template strings in codebase (planned extraction into modular templates)

🎯 Use Cases

  • Rapid project scaffolding
  • Visualizing large repos
  • Sharing architecture
  • Generating README trees

🏆 Highlights

  • Built recursive tree renderer
  • Dynamic scaffold generator
  • Real working full-stack output
  • Practical developer tool (not just UI demo)
  • Smart placeholder replacement system (prevents broken configs)
  • Dynamic preset merging with conflict-safe tree injection

🥲 Why This Exists

I didn’t want to manually create 50 folders and 70 files for a project. I'm too lazy for that.

I needed something that would skip the structure trap and get me to the actual coding faster.

So I built a tool to do it for me.

Then I realized — if it solves my problem, it’ll probably help other developers too.

So I turned it into this.

🔮 Future Improvements

  • Extract scaffold templates into modular files (better maintainability)
  • Add more backend presets (FastAPI, NestJS, etc.)
  • README auto-generation for exported projects
  • Improved placement guidance in UI
  • Better validation for malformed ASCII input
  • ⚠️ Halting Development due to college exams🫠

👨‍💻 Author

Farhaan Khan CSE Student • Full-Stack Builder • AI Explorer

⭐ Support

If this helped you — star the repo.

If it broke — open an issue 😄