{"id":48577819,"url":"https://github.com/amanbig/create-nextpy-app","last_synced_at":"2026-04-08T16:03:39.623Z","repository":{"id":311793877,"uuid":"1045026262","full_name":"Amanbig/create-nextpy-app","owner":"Amanbig","description":"A powerful command-line tool for creating full-stack applications with NextJS frontend and Python backend. Choose between FastAPI for traditional routing or RunAPI for Next.js-inspired file-based routing.","archived":false,"fork":false,"pushed_at":"2025-12-27T18:55:06.000Z","size":153,"stargazers_count":5,"open_issues_count":1,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-30T02:44:33.097Z","etag":null,"topics":["fastapi","git","hacktoberfest","javascript","nextjs","python","tailwindcss","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/create-nextpy-app","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Amanbig.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-26T14:47:05.000Z","updated_at":"2026-02-05T09:57:48.000Z","dependencies_parsed_at":"2025-08-26T22:37:02.414Z","dependency_job_id":"d5488fb7-1a3a-4225-8bd0-557e04a02e0f","html_url":"https://github.com/Amanbig/create-nextpy-app","commit_stats":null,"previous_names":["amanbig/create-nextpy-app","amanbig/nextpython-cli"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/Amanbig/create-nextpy-app","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Amanbig%2Fcreate-nextpy-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Amanbig%2Fcreate-nextpy-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Amanbig%2Fcreate-nextpy-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Amanbig%2Fcreate-nextpy-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Amanbig","download_url":"https://codeload.github.com/Amanbig/create-nextpy-app/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Amanbig%2Fcreate-nextpy-app/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31562697,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","git","hacktoberfest","javascript","nextjs","python","tailwindcss","typescript"],"created_at":"2026-04-08T16:03:38.562Z","updated_at":"2026-04-08T16:03:39.615Z","avatar_url":"https://github.com/Amanbig.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![backtool](https://socialify.git.ci/Amanbig/create-nextpy-app/image?font=Source+Code+Pro\u0026language=1\u0026name=1\u0026owner=1\u0026pattern=Brick+Wall\u0026theme=Dark)\n\n# NextPy CLI\n\nA powerful command-line tool for creating full-stack applications with NextJS frontend and Python backend. Choose between **FastAPI** for traditional routing or **RunAPI** for Next.js-inspired file-based routing.\n\n## 🚀 Quick Start\n\n```bash\n# Using npx (recommended)\nnpx create-nextpy-app\n\n# Or install globally\nnpm install -g create-next```bash\n# Clone the repository\ngit clone https://github.com/Amanbig/create-nextpy-app.git\ncd create-nextpy-app\n\n# Install dependencies\nnpm install\n\n# Test locally\nnpm link\ncreate-nextpy-app --help\n```te-nextpy-app\n```\n\n## ✨ Features\n\n- 🎯 **Interactive Setup**: Guided project creation with prompts\n- 📁 **Dual Backend Options**: \n  - **FastAPI**: Traditional routing with explicit route definitions\n  - **RunAPI**: File-based routing inspired by Next.js (routes folder structure)\n- 🌐 **Full-Stack Integration**: Complete NextJS + Python backend communication\n- 🔄 **API Routes**: Pre-configured NextJS API routes that proxy to Python backend\n- 🎨 **Styling Options**: Optional Tailwind CSS integration\n- 💻 **Language Support**: JavaScript or TypeScript for frontend\n- 🚀 **Development Ready**: Concurrent dev servers with npm scripts\n- 📝 **Demo Included**: Simple GET request demo to test backend connectivity\n- 📝 **Language Choice**: Support for both TypeScript and JavaScript\n- 🔧 **Cross-Platform**: Works on Windows, macOS, and Linux\n- 🐍 **Python Detection**: Automatically detects `python` or `python3` commands\n- 📦 **Package Scripts**: Convenient npm scripts to run both frontend and backend\n- 📚 **Documentation**: Comprehensive README files for each component\n- 🎉 **Demo Components**: Sample components showing frontend-backend communication\n- 🛡️ **Robust Error Handling**: Graceful handling of missing dependencies\n- 🔄 **Git Integration**: Automatic git initialization with fallback handling\n- 📋 **Smart Releases**: Automated publishing only when version changes\n\n## 📋 Usage\n\n### Interactive Mode (Recommended)\n\n```bash\nnpx create-nextpy-app\n```\n\nThe CLI will prompt you for:\n- Project name\n- Language choice (TypeScript or JavaScript)\n- Tailwind CSS preference\n- API framework choice (FastAPI or RunAPI)\n\n### Command Line Options\n\n```bash\nnpx create-nextpy-app [options]\n\nOptions:\n  -p, --project \u003cname\u003e     Specify project name\n  -l, --language \u003ctype\u003e    Specify language (JavaScript, TypeScript)\n  -t, --tailwind \u003ctype\u003e    Specify whether to use tailwind (Yes, No)\n  -r, --api \u003ctype\u003e         Specify API framework (FastAPI, RunAPI)\n  -f, --force             Force overwrite of existing files without prompting\n  -h, --help              Display help for command\n  -V, --version           Display version number\n```\n\n### Examples\n\n```bash\n# Create TypeScript project with Tailwind CSS and RunAPI\nnpx create-nextpy-app -p my-app -l TypeScript -t Yes -r RunAPI\n\n# Create JavaScript project with FastAPI (traditional routing)\nnpx create-nextpy-app -p my-api -l JavaScript -t No -r FastAPI\n\n# Quick setup with RunAPI (file-based routing like Next.js)\nnpx create-nextpy-app -p my-runapi-app -r RunAPI\nnpx create-nextpy-app --project my-app --language TypeScript --tailwind Yes\n\n# Create JavaScript project without Tailwind CSS\nnpx create-nextpy-app -p simple-app -l JavaScript -t No\n\n# Interactive mode (prompts for all options)\nnpx create-nextpy-app\n```\n\n## 📁 Generated Project Structure\n\n```\nmy-project/\n├── package.json              # Root package.json with convenient scripts\n├── README.md                 # Project documentation\n├── frontend/                 # NextJS application\n│   ├── src/\n│   │   ├── app/\n│   │   │   ├── api/\n│   │   │   │   └── backend/\n│   │   │   │       └── route.ts/js    # API route to Python backend\n│   │   │   ├── page.tsx/jsx           # Main page with demo\n│   │   │   └── layout.tsx/jsx         # Root layout\n│   │   ├── components/\n│   │   │   └── BackendDemo.tsx/jsx    # Demo component\n│   │   └── lib/\n│   │       └── api.ts/js              # API utilities\n│   ├── .env.local                     # Environment variables\n│   ├── package.json                   # Frontend dependencies\n│   └── README.md                      # Frontend documentation\n└── backend/                           # Python backend (FastAPI or RunAPI)\n    ├── app.py (FastAPI)              # FastAPI server\n    │   OR                            \n    ├── routes/ (RunAPI)              # RunAPI file-based routes\n    │   ├── index.py                  # GET /\n    │   └── api/                      # API routes\n    ├── main.py (RunAPI)              # RunAPI app entry point\n    ├── requirements.txt               # Python dependencies  \n    ├── package.json                   # Cross-platform npm scripts\n    ├── .env                           # Backend environment variables\n    ├── .gitignore                     # Git ignore rules\n    ├── venv/                          # Python virtual environment\n    └── README.md                      # Backend documentation\n```\n\n## 🔄 Backend Architecture: FastAPI vs RunAPI\n\nChoose the backend framework that best fits your development style:\n\n### FastAPI (Traditional Routing)\nPerfect for developers who prefer explicit route definitions and traditional API structures.\n\n```python\n# backend/app.py\nfrom fastapi import FastAPI\n\napp = FastAPI()\n\n@app.get(\"/\")\ndef read_root():\n    return {\"message\": \"Hello from FastAPI!\"}\n\n@app.get(\"/api/users\")\ndef get_users():\n    return {\"users\": []}\n\n@app.post(\"/api/users\")\ndef create_user(user: dict):\n    return {\"created\": user}\n```\n\n**FastAPI Benefits:**\n- ✅ Explicit route definitions\n- ✅ Mature ecosystem\n- ✅ Extensive documentation\n- ✅ Built-in OpenAPI/Swagger docs\n- ✅ Great for complex API logic\n\n### RunAPI (File-based Routing)\nPerfect for developers who love Next.js and want the same intuitive file-based routing for APIs.\n\n```\nbackend/\n├── routes/\n│   ├── index.py          # GET /\n│   └── api/\n│       ├── users.py      # GET,POST /api/users  \n│       └── users/\n│           └── [id].py   # GET,PUT,DELETE /api/users/{id}\n└── main.py\n```\n\n```python\n# backend/routes/index.py\nfrom runapi import JSONResponse\n\nasync def get():\n    return JSONResponse({\"message\": \"Hello from RunAPI!\"})\n\n# backend/routes/api/users.py  \nfrom runapi import JSONResponse, Request\n\nasync def get():\n    return JSONResponse({\"users\": []})\n\nasync def post(request: Request):\n    body = await request.json()\n    return JSONResponse({\"created\": body})\n```\n\n**RunAPI Benefits:**\n- ✅ File structure = API structure\n- ✅ Next.js-inspired developer experience\n- ✅ Dynamic routes with `[id].py` syntax\n- ✅ Built on FastAPI (same performance)\n- ✅ Perfect for developers familiar with Next.js\n\n### When to Choose Which?\n\n| Choose FastAPI | Choose RunAPI |\n|----------------|---------------|\n| Traditional API development | Next.js-style file routing |\n| Complex route logic | Clean, organized structure |\n| Team familiar with FastAPI | Team loves Next.js approach |\n| Existing FastAPI codebase | New projects |\n| Need maximum control | Want rapid development |\n\n## 🎯 What Gets Created\n\n### Frontend (NextJS)\n- ⚡ **NextJS 15** with App Router\n- 🎨 **Tailwind CSS** (optional)\n- 📝 **TypeScript/JavaScript** support\n- 🔄 **API Routes** that proxy to Python backend\n- 🧩 **Demo Component** with simple GET request example\n- 📱 **Responsive Design** with modern UI\n- ⚠️ **Error Handling** with user feedback\n- 🔧 **ESLint** configuration\n\n### Backend (FastAPI or RunAPI)\n- 🚀 **FastAPI**: Traditional routing with automatic OpenAPI docs\n- 📁 **RunAPI**: File-based routing inspired by Next.js\n- 🌐 **CORS** configured for NextJS frontend  \n- 🐍 **Virtual Environment** automatically created\n- 📦 **Dependencies** installed automatically\n- 🔄 **Hot Reload** with development server\n- 🔧 **Cross-Platform** npm scripts\n- 📝 **Sample GET Endpoint** for testing connectivity\n\n### Project Root\n- 📦 **Convenient Scripts** to run both frontend and backend\n- 📚 **Comprehensive Documentation**\n- 🔧 **Cross-Platform Compatibility**\n- 🎯 **Single Command Setup**\n\n## 🚀 Generated npm Scripts\n\nAfter creating a project, you can use these convenient scripts:\n\n### Root Directory\n```bash\n# Run both frontend and backend together\nnpm run dev\n\n# Run only frontend\nnpm run frontend\n\n# Run only backend  \nnpm run backend\n\n# Build frontend for production\nnpm run build\n\n# Install all dependencies\nnpm run install:all\n```\n\n### Frontend Directory\n```bash\ncd frontend\n\n# Development server\nnpm run dev\n\n# Production build\nnpm run build\n\n# Production server\nnpm start\n\n# Linting\nnpm run lint\n```\n\n### Backend Directory\n```bash\ncd backend\n\n# Development with hot reload\nnpm run dev              # Works for both FastAPI and RunAPI\n\n# FastAPI: Traditional uvicorn server\nnpm start               # uvicorn app:app --host 0.0.0.0 --port 8000\n\n# RunAPI: Built-in dev server with file watching\n# (npm run dev automatically uses 'runapi dev' for RunAPI projects)\n\n# Production server\nnpm start               # Uses 'runapi start' (no reload)\n\n# Install Python dependencies\nnpm run install\n```\n\n## 🛠️ System Requirements\n\n### Required\n- **Node.js** 18.0.0 or higher\n- **npm** 8.0.0 or higher\n- **Python** 3.8 or higher\n\n### Optional\n- **Git** (for version control - automatically initialized if available)\n\n## 🌍 Cross-Platform Support\n\nThe CLI automatically detects your operating system and uses appropriate commands:\n\n| Platform | Python Command | Virtual Environment | Package Manager |\n|----------|---------------|-------------------|-----------------|\n| **Windows** | `python` | `venv\\Scripts\\` | `pip` |\n| **macOS** | `python3` | `venv/bin/` | `pip3` |\n| **Linux** | `python3` | `venv/bin/` | `pip3` |\n\n## 🎨 Architecture\n\nThe generated application follows this architecture pattern:\n\n```\n┌─────────────┐    ┌──────────────────┐    ┌─────────────────────┐\n│   Frontend  │───▶│ NextJS API Routes│───▶│   Python Backend    │\n│   (React)   │    │   (/api/backend) │    │ (FastAPI / RunAPI)  │\n└─────────────┘    └──────────────────┘    └─────────────────────┘\n```\n\n### Benefits of This Architecture\n\n1. **🔒 Security**: Frontend never directly exposes backend URLs\n2. **🔧 Flexibility**: Add authentication, rate limiting, etc. in API routes\n3. **📝 Type Safety**: Full TypeScript support throughout\n4. **⚡ Performance**: Server-side request processing\n5. **🌍 Environment Management**: Different backend URLs per environment\n\n## 🚨 Troubleshooting\n\n### Common Issues\n\n#### 1. Python Not Found\n```bash\nError: Python not found. Please install Python and ensure it's in your PATH.\n```\n**Solution**: Install Python from [python.org](https://python.org) and add to PATH\n\n#### 2. Git Not Available\n```bash\n⚠️ Git not found or failed to initialize. You can initialize git manually later with: git init\n```\n**Solution**: This is not an error! The CLI continues without git and you can:\n- Install Git from [git-scm.com](https://git-scm.com)\n- Initialize git manually later: `cd your-project \u0026\u0026 git init`\n- The project works perfectly without git\n\n#### 3. Virtual Environment Creation Failed\n```bash\nError: python -m venv venv\n```\n**Solutions**:\n- Ensure Python is properly installed\n- Try `python3 -m venv venv` manually\n- Check Python version: `python --version`\n\n#### 4. RunAPI Installation Failed\n```bash\nError: Failed to install runapi\n```\n**Solutions**:\n- Ensure Python virtual environment is activated\n- Try manual installation: `pip install runapi`\n- Check Python version compatibility (3.8+)\n\n#### 5. RunAPI Init Command Failed\n```bash\nError: runapi init command failed\n```\n**Solutions**:\n- Ensure RunAPI is properly installed: `pip list | grep runapi`\n- Try running manually: `python -m runapi init .`\n- Check virtual environment is activated\n\n#### 6. File-based Routes Not Loading (RunAPI)\n**Symptoms**: Routes in `routes/` folder not accessible\n**Solutions**:\n- Ensure files follow naming convention: `index.py`, `users.py`, `[id].py`\n- Check that functions are properly exported: `async def get():`\n- Verify `main.py` exists and creates RunAPI app\n- Restart the development server: `runapi dev`\n\n#### 7. NextJS Creation Timeout\n```bash\nNextJS creation timed out.\n```\n**Solutions**:\n- Check internet connection\n- Clear npm cache: `npm cache clean --force`\n- Try manual creation with provided command\n\n#### 8. Port Already in Use\n```bash\nError: Port 3000/8000 already in use\n```\n**Solutions**:\n- Kill existing processes on those ports\n- Change ports in configuration files\n\n### Error Handling Features\n\nThe CLI includes robust error handling for common scenarios:\n\n- **🐍 Python Detection**: Automatically tries `python` then `python3`\n- **🔄 Git Graceful Fallback**: Continues without git if not available\n- **⏱️ Timeout Management**: Handles slow network connections\n- **🔧 Cross-Platform**: Adapts commands for your operating system\n- **📝 Clear Messages**: Provides helpful error messages and solutions\n- **🔧 Framework Detection**: Automatically configures for FastAPI or RunAPI\n- **📁 File Structure Validation**: Ensures proper RunAPI route structure\n\n### Getting Help\n\n1. **Check the logs**: The CLI provides detailed error messages\n2. **Manual setup**: Use the manual setup instructions if CLI fails\n3. **Clear cache**: Clear npm cache and try again\n4. **Check system requirements**: Ensure all requirements are met\n5. **Framework-specific help**:\n   - FastAPI: Check [FastAPI documentation](https://fastapi.tiangolo.com/)\n   - RunAPI: Check [RunAPI repository](https://github.com/Amanbig/runapi)\n6. **Test backend directly**: Visit `http://localhost:8000` to check if backend is running\n7. **Test API routes**: Visit `http://localhost:3000/api/backend` to test NextJS → Python connection\n\n## 🔧 Development\n\n### Building from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/Amanbig/create-nextpy-app.git\ncd create-nextpy-app\n\n# Install dependencies\nnpm install\n\n# Test locally\nnpm link\ncreate-nextpy-app --help\n```\n\n### Release Workflow\n\nThe project includes an automated release workflow with smart version detection:\n\n#### 🚀 Automated Publishing\n- **Triggers**: Only when `package.json` version is changed on main branch\n- **Publishes to**:\n  - [npmjs.com](https://www.npmjs.com/package/create-nextpy-app)\n  - [GitHub Packages](https://github.com/Amanbig/create-nextpy-app/packages)\n- **Creates**: Automatic GitHub releases with changelogs\n\n#### 📋 Release Process\n1. Update version in `package.json`:\n   ```bash\n   npm version patch  # or minor, major\n   ```\n2. Push to main branch:\n   ```bash\n   git push \u0026\u0026 git push --tags\n   ```\n3. GitHub Actions automatically:\n   - Detects version change\n   - Builds and tests the package\n   - Publishes to npm and GitHub Packages\n   - Creates a GitHub release\n\n#### 🛡️ Safety Features\n- **Version Change Detection**: Only publishes when version actually changes\n- **Dual Publishing**: Available on both npm and GitHub Packages\n- **Dynamic Scoping**: Automatically creates scoped packages for GitHub\n- **Release Notes**: Auto-generated with installation instructions\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## 📚 Documentation\n\nEach generated project includes comprehensive documentation:\n\n- **Project README**: Overview and quick start guide\n- **Frontend README**: NextJS-specific documentation  \n- **Backend README**: Framework-specific documentation\n  - **FastAPI**: Traditional API development with OpenAPI docs\n  - **RunAPI**: File-based routing guide with examples\n- **API Documentation**: Auto-generated docs\n  - **FastAPI**: Swagger UI at `/docs` and ReDoc at `/redoc`\n  - **RunAPI**: Built-in documentation with route discovery\n\n## 🎯 Use Cases\n\n### Perfect For\n- 🚀 **Rapid Prototyping**: Quickly create full-stack prototypes\n- 📚 **Learning Projects**: Learn NextJS + Python integration\n- 🏢 **Startup MVPs**: Fast MVP development with file-based routing\n- 🎓 **Educational**: Teaching full-stack development\n- 🔬 **Experimentation**: Try new ideas quickly\n- 🎯 **Next.js Developers**: Familiar file-based routing for APIs\n\n### Example Projects\n- **Data Dashboards**: Frontend visualization with Python data processing\n- **API Wrappers**: NextJS frontend for existing Python APIs\n- **Machine Learning Apps**: ML models in Python with React frontend\n- **CRUD Applications**: Database operations with modern UI\n- **Microservices**: RunAPI for clean, organized API structure\n- **E-commerce APIs**: File-based routes for products, users, orders\n\n## 🔮 Roadmap\n\n### Core Features\n- [ ] Database integration options (PostgreSQL, MongoDB)\n- [ ] Authentication templates (JWT, OAuth)\n- [ ] Deployment configurations (Docker, Vercel, AWS)\n- [ ] Testing setup (Jest, Pytest)\n- [ ] CI/CD pipeline templates\n- [ ] Additional frontend frameworks (Vue, Svelte)\n\n### RunAPI Enhancements\n- [ ] WebSocket support for real-time features\n- [ ] Middleware templates (rate limiting, caching)\n- [ ] Dynamic route templates with advanced patterns\n- [ ] RunAPI plugin system integration\n- [ ] Background task examples with RunAPI\n- [ ] Database ORM integration examples\n\n### FastAPI Enhancements  \n- [ ] Advanced FastAPI templates with dependencies\n- [ ] FastAPI middleware examples\n- [ ] Custom response models and validation\n- [ ] FastAPI background tasks integration\n\n## 📄 License\n\nMIT License - see LICENSE file for details\n\n## 🤝 Contributing\n\nContributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.\n\n## 📞 Support\n\n- 📧 **Email**: [amanpreetsinghjhiwant7@gmail.com]\n- 🐛 **Issues**: [GitHub Issues](https://github.com/Amanbig/create-nextpy-app/issues)\n- 💬 **Discussions**: [GitHub Discussions](https://github.com/Amanbig/create-nextpy-app/discussions)\n\n---\n\n**Made with ❤️ for developers who want to build full-stack applications quickly and efficiently.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famanbig%2Fcreate-nextpy-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famanbig%2Fcreate-nextpy-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famanbig%2Fcreate-nextpy-app/lists"}