create-stackflow 1.0.0 → 1.0.1

package/README.md

@@ -1,142 +1,449 @@
 # create-stackflow
 
-Professional interactive npm CLI for generating modern full-stack MERN applications.
+Professional interactive npm CLI for generating modern full-stack MERN and modern web applications.
 
 ```bash
 npx create-stackflow
 ```
 
-## What It Generates
+---
 
-- Root npm workspace with `frontend` and `backend` packages.
-- React/Vite or Next.js frontend using the official generator.
-- JavaScript or TypeScript project files.
-- Tailwind CSS, shadcn-style component folders, dark mode, toast notifications, loading states.
-- Auth screens, protected dashboard route, Axios service layer, and CRUD task UI.
-- Express/MongoDB backend with JWT auth, bcryptjs, cookies, CORS, helmet, rate limiting, dotenv, Mongoose, and CRUD APIs.
-- Optional Swagger, Socket.IO, Winston, Morgan, Cloudinary, and multer upload structure.
+# Overview
 
-## CLI Architecture
+`create-stackflow` is a modern developer-focused CLI tool that automatically generates scalable full-stack applications with production-ready architecture.
+
+The goal of StackFlow is to reduce repetitive setup time and instantly generate:
+
+- Frontend
+- Backend
+- Authentication
+- CRUD modules
+- Dashboard UI
+- API setup
+- Database connection
+- Protected routes
+- Upload system
+- Validation
+- Modern folder structure
+
+Everything is generated automatically with interactive prompts.
+
+---
+
+# Perfect For
+
+`create-stackflow` is ideal for:
+
+- MERN Stack developers
+- Full-stack developers
+- SaaS starters
+- Admin dashboard projects
+- Startup MVPs
+- CRUD applications
+- Authentication systems
+- Portfolio projects
+- Client projects
+- Rapid prototyping
+- Agency development workflows
+
+---
+
+# What StackFlow Generates
+
+## Frontend
+
+Supports:
+
+- React + Vite
+- Next.js
+
+Features:
+
+- JavaScript or TypeScript
+- Tailwind CSS
+- Shadcn UI
+- React Router DOM
+- Zustand / Redux Toolkit / Context API
+- React Hook Form
+- Zod / Yup validation
+- Axios API layer
+- TanStack Query
+- Protected routes
+- Dark mode
+- Toast notifications
+- Framer Motion
+- Charts
+- Drag & drop uploads
+
+---
+
+## Backend
+
+Supports:
+
+- Express.js
+- Fastify
+- NestJS
+
+Features:
+
+- MongoDB
+- PostgreSQL
+- MySQL
+- SQLite
+- Mongoose / Prisma / Sequelize / Drizzle / TypeORM
+- JWT Authentication
+- bcryptjs / argon2
+- multer
+- Cloudinary
+- Cloudflare R2
+- AWS S3
+- UploadThing
+- Swagger Docs
+- Socket.IO
+- Winston / Morgan / Pino logging
+- Nodemailer
+- AWS SES
+- SendGrid
+- Mailgun
+- Postmark
+
+---
+
+# Generated Features
+
+StackFlow automatically generates:
+
+- Login page
+- Register page
+- Forgot password
+- Reset password
+- Role-based authentication
+- Refresh token support
+- Dashboard UI
+- CRUD APIs
+- CRUD frontend pages
+- API service layer
+- Validation structure
+- Auth middleware
+- Upload structure
+- Environment variables
+- MongoDB connection
+- Loading states
+- Toast notifications
+- Reusable component architecture
+
+---
+
+# Generated Project Structure
 
 ```text
-src/
-  cli.js                  # Commander entrypoint and bin target
-  commands/
-    create.js             # Main orchestration and success/error handling
-  generators/
-    root.js               # Root workspace, README, .gitignore
-    frontend.js           # Official frontend scaffolding + StackFlow overlay
-    backend.js            # Express/MongoDB API templates
-  utils/
-    prompts.js            # Inquirer setup questions
-    names.js              # Project naming helpers
-    template.js           # Small template writer utilities
+my-app/
+│
+├── frontend/
+│
+├── backend/
+│
+├── package.json
+│
+├── .gitignore
+│
+└── README.md
 ```
 
-## Workflow
+---
+
+# Backend API Architecture
+
+StackFlow uses a scalable modular API architecture.
 
-1. Print a branded CLI banner.
-2. Ask setup questions with defaults for project, frontend folder, backend folder, framework, language, UI, state, validation, auth, and optional backend features.
-3. Validate the project name with npm naming rules.
-4. Create the root workspace package.
-5. Run the official frontend generator:
-   - Vite for React.
-   - `create-next-app` for Next.js.
-6. Persist frontend dependencies using `latest`, then install them unless `--skip-install` is passed.
-7. Overlay frontend auth, CRUD, API services, reusable components, protected routes, dark mode, and dashboard UI.
-8. Generate backend structure, env files, models, controllers, routes, middleware, services, and optional integrations.
-9. Install backend and root dependencies unless skipped.
-10. Show clean next-step instructions.
+## Main Route File
 
-## Implementation Order
+Example:
 
-1. CLI entrypoint and prompts.
-2. Root workspace generator.
-3. Official frontend generator integration.
-4. Backend API generator.
-5. Frontend auth/dashboard overlay.
-6. Dependency persistence and install strategy.
-7. Smoke tests and generated-app build tests.
-8. npm packaging metadata.
+```js
+router.use("/auth", authRoutes);
+
+router.use("/users", userRoutes);
+
+router.use("/products", productRoutes);
+```
+
+The main route file combines all module routes.
+
+---
+
+## Separate Module Routes
+
+Each module contains its own dedicated route file.
+
+Example:
+
+```js
+router.get("/");
+router.post("/");
+router.put("/:id");
+router.delete("/:id");
+```
+
+This keeps the codebase:
+- clean
+- scalable
+- maintainable
+- enterprise-ready
+
+---
+
+# Interactive Setup Questions
+
+StackFlow asks setup questions like:
+
+```bash
+? Frontend framework?
+❯ React
+  Next.js
+
+? Language?
+❯ TypeScript
+  JavaScript
+
+? Database?
+❯ MongoDB
+  PostgreSQL
+
+? Authentication strategy?
+❯ JWT
+  Session Auth
+```
+
+Everything is configured automatically based on user selections.
+
+---
+
+# Local Development Workflow
+
+## Create Project
+
+```bash
+npx create-stackflow
+```
 
-## Template Strategy
+---
 
-The current implementation keeps templates close to their generators so the package stays compact. As the project grows, move each template into a dedicated folder:
+## Start Project
+
+```bash
+cd my-app
+
+npm run dev
+```
+
+---
+
+# Local MongoDB
+
+Default MongoDB connection:
+
+```env
+MONGO_URI=mongodb://127.0.0.1:27017/myapp
+```
+
+---
+
+# Root Development Scripts
+
+StackFlow automatically configures:
+
+```bash
+npm run dev
+```
+
+This starts:
+- frontend
+- backend
+
+simultaneously using `concurrently`.
+
+---
+
+# CLI Architecture
 
 ```text
-src/templates/
-  frontend/
-    react/
-    next/
-  backend/
-    base/
-    optional/
+src/
+│
+├── cli.js
+│
+├── commands/
+│
+├── generators/
+│
+├── templates/
+│
+├── prompts/
+│
+├── utils/
+│
+└── constants/
 ```
 
-Use placeholder replacement for stable values such as project name, database name, and enabled features. Keep feature generators modular so future stacks like Docker, Prisma, PostgreSQL, Redis, BullMQ, SaaS starters, AI starters, and React Native can be added without rewriting the base flow.
+---
+
+# StackFlow Workflow
+
+1. Ask setup questions
+2. Validate project name
+3. Create frontend
+4. Create backend
+5. Install dependencies
+6. Configure Tailwind
+7. Configure Shadcn
+8. Configure backend
+9. Configure database
+10. Generate auth
+11. Generate CRUD
+12. Configure routes
+13. Generate dashboard
+14. Create env files
+15. Start project automatically
+
+---
+
+# Dependency Strategy
+
+StackFlow uses latest stable versions automatically.
+
+Examples:
+
+- `vite@latest`
+- `create-next-app@latest`
+
+Dependencies are dynamically installed based on selected features.
 
-## Dependency Strategy
+---
 
-- Generated `package.json` files use `latest` for app dependencies so npm resolves current stable versions at generation time.
-- Official generators are invoked with `vite@latest` and `create-next-app@latest`.
-- `--skip-install` still writes dependency declarations, so users can run `npm install` later.
-- Root `npm run dev` uses npm workspaces and `concurrently`.
+# Auth Strategy
 
-## Auth Strategy
+Generated authentication system includes:
 
-- Backend creates users with hashed passwords via bcryptjs.
-- Login/register return JWT and set an HTTP-only cookie.
-- Protected API routes use cookie or bearer token auth.
-- Frontend stores the token for Authorization headers and redirects unauthenticated users away from protected pages.
+- JWT authentication
+- Password hashing
+- Protected APIs
+- Protected frontend routes
+- HTTP-only cookies
+- Refresh tokens
+- Role-based access
 
-## CRUD Strategy
+---
 
-- Backend includes a `Task` model scoped to the authenticated user.
-- API exposes list, create, update, and delete routes.
-- Frontend dashboard consumes the API through a service layer and shows loading, empty, create, and delete states.
+# CRUD Strategy
 
-## Local Testing
+StackFlow automatically generates:
+
+## Backend
+
+- Models
+- Controllers
+- Routes
+- Middleware
+- Validation
+
+## Frontend
+
+- Forms
+- Tables
+- Dashboard pages
+- API services
+- Loading states
+
+---
+
+# Why StackFlow?
+
+StackFlow helps developers:
+
+- save setup time
+- avoid repetitive boilerplate
+- follow scalable architecture
+- build production-ready projects faster
+- maintain consistent code structure
+
+---
+
+# Recommended Stack
+
+## Frontend
+
+- React / Next.js
+- Tailwind CSS
+- Shadcn UI
+- Zustand
+- Axios
+- React Hook Form
+- Zod
+
+---
+
+## Backend
+
+- Express.js
+- MongoDB
+- Mongoose
+- JWT
+- bcryptjs
+- multer
+- Cloudinary
+
+---
+
+# Future Roadmap
+
+Planned future support:
+
+- SaaS starters
+- AI application starters
+- React Native
+- Prisma
+- PostgreSQL
+- Redis
+- BullMQ
+- Docker
+- Admin generators
+- Visual generators
+
+---
+
+# Local Testing
 
 ```bash
 npm run smoke
-node ./src/cli.js demo-stackflow --yes --skip-install
-cd demo-stackflow
-npm install
-npm run build --workspace frontend
-npm run build --workspace backend
+
+node ./src/cli.js
 ```
 
-For a full interactive test:
+---
+
+# Publishing
 
 ```bash
-node ./src/cli.js
+npm publish --access public
 ```
 
-## Publishing
+---
 
-1. Confirm `package.json` name is available on npm.
-2. Run `npm pack --dry-run`.
-3. Log in with `npm login`.
-4. Publish with `npm publish --access public`.
-5. Test from a separate folder:
+# Install Globally
 
 ```bash
-npx create-stackflow@latest
+npx create-stackflow
 ```
 
-## Naming Conventions
+---
+
+# License
+
+MIT
 
-- CLI package: `create-stackflow`.
-- Generated root package: kebab-case project name.
-- Folders: default `frontend` and `backend`, user configurable.
-- Backend files: `*.controller`, `*.routes`, `*.middleware`, `*.service`, `*.model`.
-- Frontend files: feature-first folders under `features`, shared primitives under `components/ui`, API utilities under `lib`.
+---
 
-## Best Practices
+# Author
 
-- Prefer official framework generators for baseline correctness.
-- Keep generated code understandable for beginners.
-- Keep feature generation modular and composable.
-- Store env defaults locally but never commit real secrets in generated apps.
-- Use npm workspaces for simple root-level development.
-- Keep optional integrations isolated so they can be removed or expanded cleanly.
+StackFlow CLI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stackflow",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Interactive CLI for generating modern full-stack MERN applications.",
   "type": "module",
   "bin": {