🧙‍♂️ StackWizard CLI

> Create production-ready full-stack applications in seconds!


StackWizard is a powerful CLI tool that generates complete, production-ready full-stack applications with a single command. Get a fully configured project with FastAPI backend, React frontend, PostgreSQL database, and Docker Compose orchestration - all following industry best practices.

✨ Features

$3

- 🚀 FastAPI Backend - Modern Python web API with async support, JWT authentication, and 100% type hints
- ⚛️ React Frontend - Choose between Material-UI or Tailwind CSS for your UI
- 🐘 PostgreSQL Database - Production-ready database with Alembic migrations
- 🐳 Docker Compose - Complete containerized development environment with health checks

$3

- 🔐 Authentication System - JWT-based auth with secure password hashing & refresh tokens
- 🛡️ Security Middleware - Rate limiting, CSRF protection, security headers
- 🏗️ Service Layer Architecture - Clean separation with Service/Repository patterns
- 📚 API Documentation - Auto-generated Swagger/OpenAPI documentation

$3

- 🧪 Comprehensive Testing - Cypress E2E tests, unit tests, Docker validation
- 🎭 Visual Testing - Watch Cypress tests run in real-time
- 🛠️ Pre-Push Validation - Automatic Docker & dependency verification
- 📊 Test Orchestration - Makefile & custom orchestrator for test management
- 🎯 Best Practices - Clean architecture, type safety, and production-ready configuration

🚀 Quick Start

$3

Clone and run directly:

``bash


Clone the repository

git clone https://github.com/rafeekpro/stackwizard.git
cd stackwizard
npm install

Run the generator

npm start

or

node src/index.js
`

$3

Install from NPM registry:

`bash


Global installation

npm install -g @rafeekpro/stackwizard

Or use npx directly

npx @rafeekpro/stackwizard my-awesome-app
`

$3

Install from GitHub Packages registry:

`bash


Configure npm to use GitHub registry for @rafeekpro scope

npm config set @rafeekpro:registry https://npm.pkg.github.com

Install globally

npm install -g @rafeekpro/stackwizard
`

> Note: Both NPM and GitHub Packages are now live with version 1.0.0!

📋 Usage

$3

Simply run the command and follow the interactive prompts:

`bash


From cloned repository

npm start

Or after global installation

stackwizard

Or use npx directly (no installation needed!)

npx @rafeekpro/stackwizard
`

You'll be asked to configure:
- 📝 Project name
- 🎨 UI library (Material-UI or Tailwind CSS)
- 🗄️ Database configuration
- 🔌 Port settings
- ✅ Additional features (Git initialization, dependency installation)

$3

Skip the prompts with command-line options:

`bash
node src/index.js --name my-app --ui mui --skip-git
`

#### Available Options

`
Options:
-V, --version Output version number
-n, --name Project name
-u, --ui UI library (mui or tailwind)
-s, --skip-git Skip git initialization
-i, --install Install dependencies after creation
-q, --quick Quick mode - use all defaults
-h, --help Display help
`

$3

Generate a project with all defaults in seconds:

`bash
node src/index.js --quick --name my-app
`

🏗️ Generated Project Structure

`
your-project/
├── backend/ # FastAPI backend application
│ ├── app/
│ │ ├── api/ # API endpoints
│ │ ├── core/ # Core configuration & security
│ │ ├── crud/ # Database operations
│ │ ├── models/ # SQLAlchemy models
│ │ ├── schemas/ # Pydantic schemas
│ │ └── main.py # Application entry point
│ ├── alembic/ # Database migrations
│ ├── tests/ # Backend tests
│ └── Dockerfile # Production-ready Dockerfile
├── frontend/ # React frontend application
│ ├── src/
│ │ ├── components/ # Reusable UI components
│ │ ├── pages/ # Page components
│ │ ├── services/ # API service layer
│ │ └── App.js # Main application component
│ ├── public/ # Static assets
│ └── Dockerfile # Production-ready Dockerfile
├── database/ # Database initialization
├── docker-compose.yml # Docker orchestration
├── .env # Environment configuration
└── README.md # Project documentation
`

🎯 What You Get

$3

- ✅ RESTful API with async/await support
- ✅ SQLAlchemy ORM with Alembic migrations
- ✅ JWT authentication & authorization
- ✅ Request validation with Pydantic
- ✅ CORS configuration
- ✅ Health check endpoints
- ✅ Comprehensive error handling
- ✅ 100% type hints for better IDE support

$3

- ✅ Modern React with Hooks
- ✅ React Router for navigation
- ✅ Axios with request/response interceptors
- ✅ Authentication context & protected routes
- ✅ Responsive design
- ✅ Material-UI or Tailwind CSS styling
- ✅ Environment-based configuration

$3

- ✅ PostgreSQL 15 with optimal settings
- ✅ Database migrations with Alembic
- ✅ Connection pooling
- ✅ Automated backup support
- ✅ Health monitoring

$3

- ✅ Multi-stage Dockerfiles for optimal image size
- ✅ Docker Compose with health checks
- ✅ Hot-reload for development
- ✅ Production-ready configuration
- ✅ Optional Redis & Nginx services

🚀 Running Your Generated Project

After generation, start your full-stack application with:

`bash
cd your-project
docker-compose up -d
`

Your application will be available at:
- 🌐 Frontend: http://localhost:3000
- 🚀 Backend API: http://localhost:8000
- 📚 API Documentation: http://localhost:8000/docs

🛠️ Development Workflow

$3

Backend Development:
`bash
cd backend
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload
`

Frontend Development:
`bash
cd frontend
npm install
npm start
`

$3

`bash


Create a new migration

alembic revision --autogenerate -m "Description"

Apply migrations

alembic upgrade head
`

🧪 Testing & Validation

$3

Watch your tests run in real-time:

`bash


Install Cypress

make cypress-install

Test MUI template visually

make cypress-mui

Test Tailwind template visually

make cypress-tailwind
`

$3

Ensure everything works before pushing to GitHub:

`bash


Full validation (recommended)

npm run validate:full

Quick validation

npm run validate:quick

Install git hooks for automatic validation

npm run install-hooks
`

$3

Run comprehensive tests with a single command:

`bash


Using Makefile

make test-all # Run all tests
make pre-commit # Pre-commit checks
make docker-build-test # Test Docker builds

Using orchestrator

npm run test:orchestrate # Smart mode
npm run test:orchestrate:full # Full test suite
``

📦 System Requirements

- Node.js 16.0.0 or higher
- npm 7.0.0 or higher
- Docker & Docker Compose (for running generated projects)
- Python 3.11+ (for local backend development)

🤝 Contributing

Contributions are welcome! Feel free to:
- Report bugs and request features via GitHub Issues
- Submit pull requests with improvements
- Share feedback and suggestions

📄 License

MIT © Rafał Łagowski

👨‍💻 Author

Rafał Łagowski - Full-Stack Developer
- GitHub: @rafeekpro
- NPM: @rafeekpro

🙏 Technologies Used

This project leverages modern, production-ready technologies:
- FastAPI - High-performance Python web framework
- React - Component-based UI library
- PostgreSQL - Enterprise-grade database
- Docker - Container orchestration
- SQLAlchemy - Python SQL toolkit and ORM
- Alembic - Database migration tool
- Material-UI - React component library
- Tailwind CSS - Utility-first CSS framework

📞 Contact & Support

- 🐛 Bug Reports: GitHub Issues
- 💡 Feature Requests: GitHub Discussions
- 📦 NPM Package: @rafeekpro/stackwizard
- 📦 GitHub Package: @rafeekpro/stackwizard
- 👤 Developer: Rafał Łagowski

---

Created with ❤️ by Rafał Łagowski

Full-Stack Developer | Open Source Contributor


NPM •
GitHub •
Profile