appgen 0.3.3

A modern project generator CLI for web frameworks

AppGen 🚀

A modern project generator CLI for web frameworks. Quickly scaffold projects for Next.js, React, Express, Flask, Django, and more with support for TypeScript, Tailwind CSS, databases, and modern tooling.

✨ Features

• Multiple Frameworks: Next.js, React, Express, Flask, Django, Svelte
• Database Support: MongoDB, PostgreSQL, Supabase, AWS DynamoDB
• Modern Tooling: TypeScript, Tailwind CSS, Prisma ORM, shadcn/ui
• Interactive CLI: Guided setup with beautiful UI
• Serverless Ready: AWS SAM templates for serverless deployment (JavaScript, TypeScript, Python, Go)
• Fullstack Presets: MERN stack, Next.js + Prisma, and more
• Clean Architecture: Modular, maintainable codebase
• Cross-Platform: Works on Windows, macOS, and Linux
• Smart Dependency Install: After project creation, choose and auto-detect your preferred package manager (npm, yarn, pnpm, bun)
• Editor Detection: Choose your code editor (VS Code, Cursor, Sublime, Atom, Vim, Nano) with installed status shown

🏗️ Architecture

AppGen uses a clean, modular architecture for maintainability and extensibility:

appgen/
├── __init__.py              # Package initialization
├── cli.py                   # Main CLI orchestration
├── ui_helper.py             # UI operations and styling
├── framework_selector.py    # Framework selection logic
└── project_manager.py       # Project creation and management

🛠️ Installation

From PyPI (Recommended)

pip install appgen

From Source

# Clone the repository
git clone https://github.com/yourusername/appgen.git
cd appgen

# Create and activate virtual environment (recommended)
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Upgrade pip
pip install --upgrade pip

# Install in development mode
pip install -e .

Verify Installation

appgen --help

You should see the CLI help with all available commands.

🚀 Quick Start

Interactive Mode (Easiest)

appgen -i
# or
appgen create --interactive

This will guide you through:

1. Framework selection with beautiful tables
2. Feature configuration (TypeScript, Tailwind, etc.)
3. Project directory setup
4. Project generation with progress indicators

Command Line Mode

# Create a Next.js project with App Router
appgen create --framework nextjs --dir my-app --router app

# Create an Express project with MongoDB
appgen create --framework express --dir my-api --db mongodb

# Create a React project with TypeScript
appgen create --framework reactjs --dir my-react-app --features typescript

📚 Usage Examples

Next.js Projects

# Basic Next.js with App Router
appgen create --framework nextjs --dir my-next-app --router app

# Next.js with TypeScript and Tailwind
appgen create --framework nextjs --dir my-next-app --router app --features typescript,tailwind

# Next.js with Prisma ORM
appgen create --framework nextjs --dir my-next-app --router app --features typescript,prisma

# Next.js with shadcn/ui components
appgen create --framework nextjs --dir my-next-app --router app --features shadcn

# Next.js with t3 stack (TypeScript + Tailwind + tRPC)
appgen create --framework nextjs --dir my-next-app --router app --features t3

Express.js Projects

# Basic Express server
appgen create --framework express --dir my-api

# Express with MongoDB
appgen create --framework express --dir my-api --db mongodb

# Express with PostgreSQL
appgen create --framework express --dir my-api --db postgresql

# Express with Supabase
appgen create --framework express --dir my-api --db supabase

# Express with AWS Lambda (serverless)
appgen create --framework express --dir my-api --db serverless

React Projects

# Basic React app
appgen create --framework reactjs --dir my-react-app

# React with TypeScript
appgen create --framework reactjs --dir my-react-app --features typescript

# React with Tailwind CSS
appgen create --framework reactjs --dir my-react-app --features tailwind

# React with both TypeScript and Tailwind
appgen create --framework reactjs --dir my-react-app --features typescript,tailwind

Python Projects

# Flask application
appgen create --framework flask --dir my-flask-app

# Django application
appgen create --framework django --dir my-django-app

Svelte Projects

# Svelte application
appgen create --framework svelte --dir my-svelte-app

Fullstack Presets

# MERN Stack (MongoDB + Express + React + Node.js)
appgen preset mern --dir my-mern-app

# Next.js Fullstack with Prisma
appgen preset nextjs-fullstack --dir my-nextjs-app

Serverless Projects

# JavaScript (Node.js) serverless
appgen create --framework serverless --language javascript --dir my-serverless-js

# TypeScript serverless
appgen create --framework serverless --language typescript --dir my-serverless-ts

# Python serverless
appgen create --framework serverless --language python --dir my-serverless-py

# Go serverless
appgen create --framework serverless --language go --dir my-serverless-go

📋 Available Commands

# List all available frameworks and features
appgen list-frameworks

# Show current configuration
appgen config

# Create a new project
appgen create [OPTIONS]

# Generate from preset
appgen preset [OPTIONS]

# Interactive mode (shortcut)
appgen -i

# Show help for any command
appgen --help
appgen create --help
appgen preset --help

🎯 Available Frameworks

Interactive Frameworks

• Next.js: App Router & Pages Router, TypeScript, Tailwind, Prisma, shadcn/ui, t3
• React: TypeScript, Tailwind CSS

Simple Frameworks

• Express.js: MongoDB, PostgreSQL, Supabase, AWS Lambda (serverless)
• Flask: Lightweight Python web framework
• Django: Full-featured Python web framework
• Svelte: Cybernetically enhanced web apps

🗄️ Database Support

Express.js Databases

• MongoDB: NoSQL database with Mongoose ODM
• PostgreSQL: Relational database with Sequelize ORM
• Supabase: Open-source Firebase alternative
• AWS DynamoDB: Serverless NoSQL database (with SAM template)

🎨 Features & Integrations

Next.js Features

• App Router: Next.js 13+ App Router
• Pages Router: Traditional Pages Router
• TypeScript: Full TypeScript support
• Tailwind CSS: Utility-first CSS framework
• Prisma: Modern database toolkit
• shadcn/ui: Re-usable component library
• t3: Type-safe full-stack development with tRPC

React Features

• TypeScript: Type-safe development
• Tailwind CSS: Utility-first styling
• Vite: Fast build tool

🏗️ Generated Project Structure

After generation, your project will include:

my-project/
├── README.md           # Project documentation
├── package.json        # Dependencies and scripts
├── .env.example        # Environment variables template
├── .gitignore          # Git ignore rules
├── tsconfig.json       # TypeScript config (if applicable)
├── tailwind.config.js  # Tailwind config (if applicable)
└── src/                # Source code
    ├── components/     # Reusable components
    ├── pages/          # Pages (Next.js Pages Router)
    ├── app/            # App directory (Next.js App Router)
    ├── lib/            # Utility functions
    └── ...

🚀 Next Steps

After creating your project:

cd my-project
# For JS/TS: You will be prompted to install dependencies interactively with your choice of npm, yarn, pnpm, or bun (auto-detected)
# For Python: pip install -r requirements.txt
# For Go: go mod tidy
npm run dev  # or python run.py for Python projects

🖥️ Editor and Package Manager Selection

After project generation (in interactive mode):

• Editor Selection: Choose from Visual Studio Code, Cursor, Sublime Text, Atom, Vim, or Nano. The selection table shows an 'Installed?' column (✅/❌) so you can only select editors that are available on your system.
• Package Manager Selection: For JS/TS projects, you are prompted to install dependencies. Choose from npm, yarn, pnpm, or bun. Only installed package managers are shown.

Example editor selection table:

#	Editor	Command	Installed?
1	Visual Studio Code	code	✅
2	Cursor	cursor	✅
3	Sublime Text	subl	❌
4	Atom	atom	❌
5	Vim	vim	✅
6	Nano	nano	✅

If you select an editor that is not installed, you will be prompted to choose again.

Example package manager selection:

#	Package Manager	Installed?
1	npm	✅
2	yarn	❌
3	pnpm	✅
4	bun	❌

Only installed package managers are available for selection.

🔧 Development

Local Development Setup

# Clone the repository
git clone https://github.com/yourusername/appgen.git
cd appgen

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Upgrade pip
pip install --upgrade pip

# Install development dependencies (includes pre-commit hooks)
make install-dev

# Test the CLI
appgen --help
appgen list-frameworks

Development Commands

make help              # Show all available commands
make install           # Install package in development mode
make install-dev       # Install development dependencies
make test              # Run tests with coverage
make lint              # Run linting checks
make format            # Format code
make security          # Run security checks
make clean             # Clean build artifacts
make build             # Build package
make ci                # Run all CI checks locally
make pre-commit        # Run pre-commit hooks on all files

Code Quality Tools

• Black: Code formatting
• isort: Import sorting
• flake8: Linting
• mypy: Type checking
• bandit: Security checks
• pre-commit: Git hooks for code quality
• commitizen: Conventional commit messages

Testing

# Test project generation
appgen create --framework flask --dir test-flask
appgen create --framework express --dir test-express --db mongodb

# Clean up test projects
rm -rf test-flask test-express

Building for Distribution

# Build package
python -m build

# Install from local build
pip install dist/appgen-*.whl

# Test installed package
appgen --help

Contributing

We welcome contributions! Please see our Contributing Guide for detailed information.

Quick start:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Install development dependencies (make install-dev)
4. Make your changes
5. Run tests (make test) and linting (make lint)
6. Commit using conventional commits (cz commit)
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

CI/CD Pipeline

We use GitHub Actions for continuous integration:

• Tests: Run on Python 3.8-3.12
• Linting: Code style and type checking
• Security: Automated security scans
• Integration Tests: Test all framework generations
• Build: Package building and validation
• Release: Automated PyPI publishing on tags

See .github/workflows/ for workflow details.

🐛 Troubleshooting

Common Issues

CLI not found after installation:

# Reinstall in editable mode
pip uninstall appgen -y
pip install -e .

Virtual environment issues:

# Remove and recreate virtual environment
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Permission errors:

# Use user installation
pip install --user appgen

📝 License

MIT License - see LICENSE file for details.

🤝 Support

• 📖 Documentation
• 🐛 Report Issues
• 💡 Request Features
• ⭐ Star the Project
• 💬 Discussions

🙏 Acknowledgments

• Built with Typer for CLI
• Beautiful UI with Rich
• Inspired by modern project generators

---

Happy coding! 🎉