readmefy

Generate professional README.md files for your projects in seconds ⚡

readmefy is a powerful CLI tool that automatically analyzes your Node.js project and generates a comprehensive, well-structured README.md file. Say goodbye to tedious documentation writing!

Table of Contents

• Features
• Installation
• Usage
• CLI Options
• Examples
• How It Works
• Tech Stack
• AI Enhancement
• Project Structure
• Contributing
• License

Features

✨ Automatic Detection

• Detects tech stack from package.json dependencies
• Extracts npm scripts and creates formatted tables
• Generates folder structure tree
• Identifies key features (authentication, databases, ORMs, etc.)

🎨 Beautiful Output

• Shields.io badges for technologies, npm version, license
• Clean markdown formatting with table of contents
• Proper code blocks and consistent headings
• Professional styling

🤖 Optional AI Enhancement

• Enhance descriptions and usage sections with AI
• Single-call and multi-call modes supported
• Falls back gracefully to deterministic mode

🛡️ Safe & Reliable

• Overwrite protection with confirmation prompt
• Dry-run mode to preview output
• Comprehensive error handling
• Never sends source code to AI (only metadata)

Installation

Global Installation (Recommended)

npm install -g readmefy

Use with npx (No Installation)

npx readmefy

Local Development

git clone https://github.com/yourusername/readmefy.git
cd readmefy
npm install
npm run build
npm link

Usage

Navigate to your project directory and run:

npx readmefy

That's it! readmefy will analyze your project and generate a README.md file.

CLI Options

Basic Commands

# Generate complete README
npx readmefy

# Generate minimal structure only
npx readmefy --structure

# Preview without writing file
npx readmefy --dry

# Use custom AI key for enhancement
npx readmefy --key=<YOUR_API_KEY>

Flags

| Flag | Description | |------|-------------| | --structure | Generate minimal README structure only (no scripts, basic sections) | | --key=<API_KEY> | Provide custom AI key for content enhancement (multi-call mode) | | --dry | Print generated README to console without writing to file | | --version | Show CLI version | | --help | Display help menu |

Examples

Example 1: Basic Usage

cd my-awesome-project
npx readmefy

Output:

✔ Stack detected: Node.js, TypeScript, React, Express
✔ 5 scripts extracted
✔ Folder structure generated
✔ README.md created successfully

✔ README generated successfully by readmefy.

Example 2: Dry Run (Preview)

npx readmefy --dry

This will print the generated README to your console without creating a file, perfect for testing.

Example 3: Structure Only

npx readmefy --structure

Generates a minimal README with just:

• Project title
• Description
• Tech stack badges
• Project structure

Example 4: AI Enhancement

# Using environment variable
export READMEGEN_AI_KEY="your-openai-api-key"
npx readmefy

# Or using --key flag
npx readmefy --key=your-openai-api-key

How It Works

readmefy follows a systematic approach:

1. Detection Phase

   • Locates and reads package.json
   • Analyzes dependencies to detect tech stack
   • Extracts npm scripts
   • Scans project structure

2. Feature Detection

   • Identifies authentication libraries (JWT, Passport)
   • Detects databases (MongoDB, PostgreSQL, MySQL)
   • Finds ORMs (Prisma, Mongoose)
   • Recognizes HTTP clients (Axios)
   • Spots environment config tools (dotenv)

3. Badge Generation

   • Creates shields.io badges for all technologies
   • Generates NPM version badge
   • Adds license and Node version badges

4. Content Assembly

   • Builds markdown with proper formatting
   • Creates table of contents
   • Formats script tables
   • Adds folder structure tree

5. Optional AI Enhancement

   • Enhances descriptions
   • Generates usage examples
   • Provides stack explanations

6. Output

   • Writes formatted README.md
   • Or prints to console with --dry flag

Tech Stack

Technologies:

• Node.js - Runtime environment
• TypeScript - Type-safe development
• Commander - CLI argument parsing
• Chalk - Terminal styling
• OpenAI API - Optional AI enhancement

AI Enhancement

readmefy supports optional AI-powered content enhancement using OpenAI's API.

Two Modes

1. Single-Call Mode (Environment Variable)

export READMEGEN_AI_KEY="your-api-key"
npx readmefy

2. Multi-Call Mode (CLI Flag)

npx readmefy --key=your-api-key

What Gets Enhanced?

• Project descriptions
• Tech stack explanations
• Usage/Getting Started sections

Privacy

readmefy never sends your source code to AI services. Only metadata is shared:

• Project name
• Package.json description
• Detected technologies
• Script names
• Folder structure (paths only)

Project Structure

readmefy/
├── src/
│   ├── cli.ts                 # CLI entry point and orchestration
│   ├── index.ts               # Main entry point
│   ├── analyzer/
│   │   ├── detectStack.ts     # Tech stack detection
│   │   ├── detectScripts.ts   # Script extraction
│   │   ├── detectStructure.ts # Folder tree generation
│   │   └── detectFeatures.ts  # Feature detection
│   ├── generator/
│   │   ├── badges.ts          # Badge generation
│   │   ├── buildMarkdown.ts   # README assembly
│   │   └── scriptTable.ts     # Script table formatting
│   ├── ai/
│   │   └── aiEnhancer.ts      # AI enhancement logic
│   └── utils/
│       ├── fileReader.ts      # File I/O utilities
│       ├── logger.ts          # Colored console output
│       └── treeBuilder.ts     # Tree structure builder
├── package.json
├── tsconfig.json
└── README.md

Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes
4. Run the build

   npm run build

5. Commit your changes

   git commit -m "Add amazing feature"

6. Push to your branch

   git push origin feature/amazing-feature

7. Open a Pull Request

Development Scripts

npm run build    # Build TypeScript to JavaScript
npm run dev      # Watch mode for development

License

This project is licensed under the ISC License.

Made with ❤️ by the readmefy team

Star ⭐ this repository if you find it helpful!