🚀 FOLDERA — The Fast Project Generator

███████╗  ██████╗  ██╗      ██████═╗ ███████╗ ██████╗   █████╗
██╔════╝ ██╔═══██╗ ██║      ██   ██║ ██╔════╝ ██╔══██╗ ██╔══██╗
██████   ██║   ██║ ██║      ██   ██║ █████╗   ██████╔╝ ███████║
██╚      ██║   ██║ ██║      ██   ██║ ██╔══╝   ██╔═██   ██╔══██║
██║       ██████╔╝ ███████╗ ██████ ║ ███████╗ ██║ ███  ██║  ██║
══╝       ╚═════╝  ╚══════╝  ╚═════╝ ╚══════╝ ╚═╝      ╚═╝  ╚═╝

Foldera is a blazing‑fast project scaffolding CLI. Bootstrap modern stacks in seconds with interactive prompts, pre‑baked templates, and smart defaults.

✨ Features

• ⚡ Instant scaffolding: npx foldera my-app
• 🎨 Templates: Node (basic), React + Vite + Tailwind + Nodejs + Express (fullstack), Express API
• 🔌 Interactive UX via Clack prompts
• 📦 Auto‑install dependencies (root + nested client/, server/)
• 🔔 Update notifier built‑in
• 🧩 Extensible commands (init)
• 🛠️ Clean, modular architecture (ESM)

📦 Installation

# Global install
npm install -g foldera

# OR run directly
npx foldera my-app

🚀 Quick Start

Default Generator (Interactive)

foldera          # asks for name, template, install

Named Project (Interactive Template)

foldera my-app   # skips name prompt, picks template interactively

Fully Non‑Interactive

foldera my-app nodejs   # name + template provided

Explicit Command

foldera generate             # same interactive generator

Initialize Existing Folder

foldera init

Add a Feature Later

foldera add tailwind

🏗️ Templates

• nodejs — Minimal Node.js starter
• fullstack-vite — React + Vite + Tailwind, prewired configs
• express-api — RESTful API skeleton with routing & scripts

Use a template directly:

npx foldera my-app react-basic

🏷️ Flags

• --help, -h — Show help
• --version, -v — Show installed version

Strict flags: Unknown flags (e.g., --helo) produce an error. Use --help to see valid options.

🛠️ Project Architecture

project-root/
│
├── app.js                 # CLI entry → runs src/core/cli.js
│
├── /src
│   ├── /core
│   │   ├── cli.js         # Router: parses flags/args, dispatches
│   │   ├── prompts.js     # Clack prompts
│   │   ├── installer.js   # npm installs (root + nested)
│   │   ├── notifier.js    # update checks
│   │   └── utils.js       # helpers
│   │
│   ├── /commands
│   │   ├── index.js       # registers commands
│   │   ├── generate.js    # scaffold projects
│   │   ├── add.js         # add features/templates
│   │   ├── init.js        # init in existing dir
│   │   └── help.js        # help renderer
│   │
│   ├── /templates
│   │   ├── nodejs/
│   │   ├── fullstack-vite/
│   │   ├── express-api/
│   │   └── config.json

🔧 Template: React + Vite + Tailwind (Expectations)

Dependencies (dev): tailwindcss, @tailwindcss/vite, autoprefixer

index.css

@import "tailwindcss";

App.jsx (sample)

export default function App() {
  return (
    <div className="text-4xl font-semibold text-center mt-10">
      🚀 Tailwind is ready!
    </div>
  );
}

⚙️ Behavior & Routing Rules

• No args → run interactive generator.
• npx foldera <folder-name> → treat <name> as project name, prompt for template & install.
• Known command (e.g., init) → dispatch to command handler(still in development).
• Flags first: --help, -h, --version, -v handled globally.
• Strict flag mode: any unknown --something → error out with guidance.

🧪 Local Development

git clone https://github.com/your-username/foldera.git
cd foldera
npm install
npm link          # use `foldera` globally during dev

Run CLI:

foldera --help
foldera my-app

🤝 Contributing

• Use ESM (import), no CommonJS
• Keep commands small, focused
• Document changes in this README + /docs
• Add tests for new flags/commands

PR checklist:

• [ ] Feature works on Node 18/20+
• [ ] No breaking UX without docs
• [ ] Tests and docs updated

❓ FAQ

Q: How do I create a new project? npx foldera my-app

Q: Can I specify the template directly? npx foldera my-app react-basic

Q: How do I show help or version? npx foldera --help, npx foldera --version

Q: Why do I get Unknown flag? Flags are strict. Use exact names.

Q: Does it install nested deps (client/server)? Yes. The installer scans root and known subfolders and runs npm install where needed.

📖 Deep Dives

For focused guides, see /docs:

• Architecture — docs/architecture.md
• Commands — docs/commands.md

📜 License

MIT © 2025 Nikhil Mishra