🎯 Why nodejs-fs?

Stop wasting hours setting up the same backend infrastructure. nodejs-fs generates a complete, production-ready Express.js + MongoDB backend with authentication, security, and best practices baked in.

Perfect for:

• 🏃‍♂️ Hackathons and MVPs
• 📚 Learning full-stack development
• 🎓 Teaching backend architecture
• 🚀 Rapid prototyping
• 💼 Freelance projects

✨ Features

🔐 Security First

• JWT authentication
• Bcrypt password hashing
• Rate limiting & brute force protection
• Helmet.js security headers
• CORS configuration
• Cookie parser

⚡ Production Ready

• Express 5.x (latest)
• Environment-based config
• Winston logging
• Global error handling
• Joi validation
• MongoDB connection pooling
• Compression middleware

🛠️ Developer Experience

• Clean MVC architecture
• RESTful API design
• Node.js watch mode (no nodemon)
• Email templates
• Image upload & processing
• Comprehensive documentation

🚀 Quick Start

Get your backend up and running in 60 seconds:

# Create your project with npx (no installation needed)
npx create-nodejs-fs my-awesome-api

# Navigate to your project
cd my-awesome-api

# Configure environment
cp .env.example .env
# Edit .env with your MongoDB URI and JWT secret

# Start developing
npm run dev

That's it! You now have a fully-functional backend with auth, CRUD operations, and more. 🎉

📦 Installation & Usage

Option 1: Use with npx (Recommended)

No installation required - just run:

npx create-nodejs-fs my-project-name

Option 2: Install Globally

npm install -g nodejs-fs
create-nodejs-fs my-project-name

What Happens Next

The CLI will automatically:

1. Create the project structure
2. Copy all template files
3. Install dependencies (npm install)
4. Set up your backend with all configurations

Available Options

create-nodejs-fs <project-name> [options]

Options:
  --no-install    Skip npm install
  --git           Initialize git repository
  --verbose       Show detailed logs
  -v, --version   Output version number
  -h, --help      Display help

📁 What's Included

Complete Project Structure

your-project/
├── 📂 src/
│   ├── 📂 config/           # Configuration files
│   │   ├── cloudinary.js    # Image hosting setup
│   │   ├── db.js            # MongoDB connection
│   │   └── logger.js        # Winston logger config
│   │
│   ├── 📂 controllers/      # Business logic
│   │   ├── authController.js      # Auth operations
│   │   └── productController.js   # CRUD operations
│   │
│   ├── 📂 middlewares/      # Custom middleware
│   │   ├── auth.js          # JWT verification
│   │   ├── errorHandler.js  # Global error handler
│   │   ├── rateLimiter.js   # Rate limiting
│   │   └── validate.js      # Input validation
│   │
│   ├── 📂 models/           # Database schemas
│   │   ├── User.js          # User model + methods
│   │   └── Product.js       # Product model
│   │
│   ├── 📂 routes/           # API routes
│   │   ├── authRoutes.js    # /api/auth/*
│   │   ├── productRoutes.js # /api/products/*
│   │   └── index.js         # Route aggregator
│   │
│   ├── 📂 utils/            # Helper functions
│   │   ├── imageProcessor.js  # Image upload/resize
│   │   ├── mailer.js          # Email sending
│   │   └── slugifyUtil.js     # URL-friendly slugs
│   │
│   ├── app.js              # Express app configuration
│   └── index.js            # Server entry point
│
├── .env.example            # Environment template
├── package.json
└── README.md              # Complete documentation

🔋 Tech Stack & Dependencies

Core Framework:

• Express.js ^5.1.0 - Modern, fast web framework (Express 5)
• Mongoose ^8.x - MongoDB object modeling

Security:

• bcrypt - Password hashing with salt
• jsonwebtoken - JWT token generation & verification
• helmet - Security HTTP headers
• express-rate-limit - Brute force protection
• cors - Cross-origin resource sharing

Utilities:

• nodemailer - Email sending (password reset, notifications)
• cloudinary - Cloud image hosting & transformation
• sharp - High-performance image processing
• multer - Multipart/form-data file upload
• joi - Schema validation & sanitization
• winston - Comprehensive logging
• slugify - URL-friendly string conversion
• compression - Gzip compression middleware
• cookie-parser - Parse cookies
• dotenv - Environment variable management

Development:

• Node.js >=18.0.0 - Built-in watch mode with --watch flag
• morgan - HTTP request logger

⚙️ Configuration Guide

Essential Environment Variables

# Server Configuration
PORT=5000                                    # Server port
NODE_ENV=development                         # development | production

# Database
MONGODB_URI=mongodb://localhost:27017/mydb  # MongoDB connection string

# JWT Authentication
JWT_SECRET=your-256-bit-secret-key          # Strong random string
JWT_EXPIRE=7d                               # Token expiration (7d, 24h, etc.)
JWT_COOKIE_EXPIRE=7                         # Cookie expiration in days

Optional Features

# Email Service (for password reset)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
[email protected]
SMTP_PASSWORD=your-app-specific-password
[email protected]
FROM_NAME=Your App Name

# Cloudinary (for image uploads)
CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-api-key
CLOUDINARY_API_SECRET=your-api-secret

# Frontend URL (for CORS and email links)
CLIENT_URL=http://localhost:3000

Quick Setup Tips

MongoDB Options:

• 🖥️ Local: Install MongoDB Community Server
• ☁️ Cloud: Use MongoDB Atlas (free tier available)

Email Service:

• Use Gmail with App Password
• Or try SendGrid, Mailgun, AWS SES

Image Hosting:

• Sign up at Cloudinary (free tier: 25GB storage, 25GB bandwidth)

🎯 Use Cases

Perfect for building:

• 🛍️ E-commerce APIs - Product management, user auth, order processing
• 📱 Mobile App Backends - REST API for iOS/Android apps
• 💬 Social Platforms - User profiles, posts, comments, likes
• 📰 Blog/CMS Systems - Content management with authentication
• 🎓 Learning Management - Course platforms, student portals
• 🏢 Business Applications - CRM, inventory management, booking systems
• 🎮 Gaming Backends - Player data, leaderboards, achievements

🛡️ Security Best Practices

Our template implements enterprise-grade security:

| Security Layer | Implementation | |---------------|----------------| | 🔐 Authentication | JWT tokens with secure secret key | | 🔒 Password Storage | Bcrypt hashing (10 salt rounds) | | 🛡️ HTTP Headers | Helmet.js (XSS, clickjacking, etc.) | | 🚦 Rate Limiting | Max 100 requests per 15 min per IP | | ✅ Validation | Joi schema validation on all inputs | | 🌐 CORS | Configurable allowed origins | | 🍪 Cookies | HttpOnly, Secure, SameSite flags | | 📝 Logging | Winston for security audits | | 🗜️ Compression | Gzip compression for responses |

📖 Available Scripts

npm run dev      # Start with Node.js watch mode (auto-reload)
npm start        # Start production server

🤝 Contributing

We welcome contributions! Here's how you can help:

1. 🐛 Report bugs - Open an issue
2. 💡 Suggest features - Share your ideas
3. 🔧 Submit PRs - Fork, code, and create pull requests
4. ⭐ Star the repo - Show your support

📄 License

MIT © MERN Stack Hero

Free to use for personal and commercial projects.

💬 Support & Community

Need help? We've got you covered:

• 📚 Documentation: GitHub Wiki
• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• ⭐ Star us on GitHub to stay updated

🗺️ Roadmap

Coming soon:

• [ ] TypeScript template option
• [ ] GraphQL API template
• [ ] WebSocket support
• [ ] Redis caching integration
• [ ] Stripe payment integration
• [ ] Social OAuth (Google, GitHub, Facebook)
• [ ] Swagger/OpenAPI documentation
• [ ] Docker configuration
• [ ] CI/CD templates (GitHub Actions, GitLab CI)
• [ ] Testing setup (Jest, Supertest)

⭐ If nodejs-fs helped you, please star the repo! ⭐

Made with ❤️ by MERN Stack Hero

Report Bug · Request Feature · Contribute

📚 API Documentation

🔐 Authentication Endpoints

| Method | Endpoint | Description | Auth Required | |--------|----------|-------------|---------------| | POST | /api/auth/register | Register new user | ❌ | | POST | /api/auth/login | Login user | ❌ | | POST | /api/auth/forgot-password | Request password reset | ❌ | | POST | /api/auth/reset-password/:token | Reset password with token | ❌ | | GET | /api/auth/me | Get current user profile | ✅ |

📦 Product Endpoints

| Method | Endpoint | Description | Auth Required | |--------|----------|-------------|---------------| | GET | /api/products | Get all products (paginated) | ❌ | | GET | /api/products/:id | Get single product | ❌ | | POST | /api/products | Create new product | ✅ | | PUT | /api/products/:id | Update product | ✅ | | DELETE | /api/products/:id | Delete product | ✅ |

Register a new user:

curl -X POST http://localhost:5000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "[email protected]",
    "password": "securePassword123"
  }'

Login:

curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securePassword123"
  }'

Create a product (with auth):

curl -X POST http://localhost:5000/api/products \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "name": "Awesome Product",
    "description": "This is an awesome product",
    "price": 99.99,
    "category": "Electronics"
  }'

Configuration

After generating your project, create a .env file based on .env.example:

# Server
PORT=5000
NODE_ENV=development

# Database
MONGODB_URI=mongodb://localhost:27017/your-database

# JWT
JWT_SECRET=your-super-secret-jwt-key
JWT_EXPIRE=7d
JWT_COOKIE_EXPIRE=7

# Email
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
[email protected]
SMTP_PASSWORD=your-email-password
[email protected]
FROM_NAME=Your App Name

# Cloudinary
CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-api-key
CLOUDINARY_API_SECRET=your-api-secret

# Client URL
CLIENT_URL=http://localhost:3000

🎓 Getting Started Guide

Step 1: Create Your Project

npx create-nodejs-fs my-awesome-api
# Or if installed globally:
create-nodejs-fs my-awesome-api

The CLI accepts a project name as an argument (no interactive prompts).

Available options:

• --no-install - Skip dependency installation
• --git - Initialize git repository
• --verbose - Show detailed logs

Step 2: Navigate to Your Project

cd my-awesome-api

Step 3: Configure Environment

cp .env.example .env

Edit .env with your credentials:

# Minimum required configuration
MONGODB_URI=mongodb://localhost:27017/your-database
JWT_SECRET=your-super-secret-key-change-this
PORT=5000

Step 4: Start Developing

npm run dev

Your API is now running at http://localhost:5000 🚀

Uses Node.js built-in --watch flag (Node 18+) - no nodemon needed!

Step 5: Test Your API

# Health check
curl http://localhost:5000

# Register a user
curl -X POST http://localhost:5000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name":"Test User","email":"[email protected]","password":"password123"}'

📊 What You Get Out of the Box

| Feature | Included | Configuration Required | |---------|----------|------------------------| | ✅ Express.js Server | ✓ | Minimal | | ✅ MongoDB + Mongoose | ✓ | Connection string only | | ✅ JWT Authentication | ✓ | Secret key only | | ✅ Password Hashing | ✓ | None | | ✅ Input Validation | ✓ | None | | ✅ Error Handling | ✓ | None | | ✅ Security Headers | ✓ | None | | ✅ Rate Limiting | ✓ | Optional tuning | | ✅ CORS | ✓ | Optional tuning | | ✅ Email Service | ✓ | SMTP credentials | | ✅ Image Upload | ✓ | Cloudinary credentials | | ✅ Logging | ✓ | None | | ✅ API Documentation | ✓ | None |

🆚 Why Choose nodejs-fs?

❌ Hours of setup

❌ Security gaps

❌ No auth included

❌ Basic structure

❌ No best practices

⚠️ Minimal setup

❌ No database

❌ No authentication

❌ Outdated patterns

⚠️ Basic only

⚠️ Overengineered

⚠️ Too opinionated

❌ Steep learning curve

⚠️ Hard to modify

⚠️ Limited docs

✅ 60-second setup

✅ Production-ready

✅ Full auth system

✅ Modern patterns

✅ Well documented

✅ Easy to customize

✅ Actively maintained

📁 What's Included