⚡ Vite-Spark

Lightning-fast Full-Stack project generator — Frontend + Backend in seconds!

Vite Spark is a zero-config CLI that scaffolds production-ready React frontends and Node.js backends with authentication, TypeScript/JavaScript support, and optional Tailwind CSS — all in one command.

✨ Features

• ⚡ Blazing Fast — Built on Vite for instant HMR and optimized builds
• 🌐 Full-Stack Support — Create frontend, backend, or both together
• 🎯 Production-Ready Templates — Minimal or auth-ready setups
• 🔷 TypeScript or JavaScript — Full support for both
• 🎨 Optional Tailwind CSS — Integrated and configured automatically
• 🔐 Secure Authentication — HttpOnly cookies, JWT, bcrypt, RBAC
• 🔧 Node.js Backend — Express + MongoDB with middleware & error handling
• 📦 Monorepo Support — Run frontend + backend with one command
• 📝 Smart Git Integration — Initialize in root or separate folders
• 🎭 Non-Interactive by Default — Fast defaults, interactive when needed
• 🛡️ Safe Overwrites — Always prompts before replacing existing files

🚀 Quick Start

Option 1: NPX (No Installation Required) ⭐ Recommended

# Frontend only (default)
npx vite-spark my-app

# Full-stack (frontend + backend)
npx vite-spark my-app --with-backend

# Backend only
npx vite-spark my-api --backend-only

# Interactive mode (asks questions)
npx vite-spark -q

# TypeScript full-stack with Tailwind
npx vite-spark my-saas --with-backend -l ts --twd -i

Option 2: Global Installation

# Install once
npm install -g vite-spark

# Use anywhere
vite-spark my-app
vite-spark my-api --backend-only
vite-spark my-project --with-backend

📋 What Can You Create?

🎨 Frontend Only (Default)

npx vite-spark my-app

Creates:

my-app/
├── src/
│   ├── context/      # Auth & Theme contexts
│   ├── App.jsx
│   └── main.jsx
├── package.json
└── vite.config.js

🔧 Backend Only

npx vite-spark my-api --backend-only

Creates:

my-api/
├── Controllers/      # Admin, Auth, Factory, Error, User
├── Models/          # User model with soft-delete
├── Routes/          # Auth & Admin routes
├── Utils/           # APIFeatures, AppError, CatchAsync, etc.
├── plugins/         # Soft-delete plugin
├── App.js
└── config.js

Backend Features:

• ✅ Express.js + MongoDB + Mongoose
• ✅ JWT authentication with HttpOnly cookies
• ✅ Role-Based Access Control (Admin/User)
• ✅ Soft-delete functionality
• ✅ Factory pattern CRUD operations
• ✅ Email service (Nodemailer)
• ✅ File upload (Multer)
• ✅ Security (Helmet, Rate limiting, CORS)
• ✅ Error handling middleware

🌐 Full-Stack (Frontend + Backend)

npx vite-spark my-project --with-backend

Creates:

my-project/
├── frontend/         # React app
├── backend/          # Node.js API
├── package.json      # Root (monorepo scripts)
└── README.md         # Setup instructions

Monorepo Features:

• ✅ Run both servers with npm run dev
• ✅ Install all deps with npm run install:all
• ✅ Shared Git repository (optional)
• ✅ Coordinated development workflow

🎨 CLI Options

Quick Examples

# Frontend with TypeScript + Tailwind
npx vite-spark my-app -l ts --twd -i

# Backend only
npx vite-spark my-api --backend-only -i

# Full-stack with everything
npx vite-spark my-saas --with-backend -l ts --twd -i

# Interactive mode
npx vite-spark -q

# Minimal (just files)
npx vite-spark my-app -n

All Available Flags

Project Type

| Flag | Description | Example | |------|-------------|---------| | --with-backend | Create full-stack (frontend + backend) | --with-backend | | --backend-only | Create backend only | --backend-only | | (none) | Frontend only (default) | - |

Frontend Options

| Flag | Description | Default | Example | |------|-------------|---------|---------| | -l, --lang <js\|ts> | Language (JavaScript/TypeScript) | js | -l ts | | -t, --template <basic\|Auth> | Template preset | Auth | -t basic | | --twd, --tailwind | Add Tailwind CSS | false | --twd |

Backend Options

| Flag | Description | Default | Example | |------|-------------|---------|---------| | -b, --backend-template <template> | Backend template | node | -b node |

Full-Stack Options

| Flag | Description | Default | Example | |------|-------------|---------|---------| | --monorepo | Create root package.json | true | --monorepo | | --no-monorepo | Skip monorepo setup | - | --no-monorepo | | --git-in-root | Git in root folder | true | --git-in-root | | --no-git-in-root | Git in separate folders | - | --no-git-in-root |

Common Options

| Flag | Description | Default | Example | |------|-------------|---------|---------| | -g, --git | Initialize Git | false | -g | | -i, --install | Install dependencies | false | -i | | -s, --start | Start dev server | false | -s | | -q, --questions | Interactive mode | false | -q | | -n, --no-extras | Minimal setup | - | -n |

📦 Templates

Frontend Templates

🎯 Basic — Minimal React Starter

• Vite + React
• Hot Module Replacement
• ESLint configuration
• Basic routing example

npx vite-spark my-app -t basic

🔐 Auth — Production-Ready Authentication (Default)

• Context-based auth (AuthContext + useAuth)
• HttpOnly cookies (XSS protection)
• Login/Signup/Logout pages
• Protected routes
• Theme switcher (ThemeContext)
• Form validation
• Error handling

npx vite-spark my-app -t Auth

Backend Templates

🔧 Node.js — Express + MongoDB (Default)

• RESTful API architecture
• User authentication & authorization
• JWT with HttpOnly cookies
• Role-Based Access Control (Admin/User)
• Soft-delete plugin (users can be restored)
• Factory pattern CRUD operations
• Email service (Nodemailer)
• File upload (Multer)
• Security headers (Helmet)
• Rate limiting
• CORS configuration
• MongoDB with Mongoose

npx vite-spark my-api --backend-only

Coming Soon:

• Node.js Basic (minimal setup)
• PHP (Laravel/Slim)
• Python (FastAPI)

🎯 Real-World Examples

SaaS Application (Full-Stack TypeScript)

npx vite-spark my-saas --with-backend -l ts --twd -g -i
cd my-saas
npm run dev  # Runs both frontend & backend

REST API (Backend Only)

npx vite-spark my-api --backend-only -i
cd my-api
npm run dev  # Runs on http://localhost:3000

Landing Page (Frontend Only)

npx vite-spark landing -t basic --twd -i
cd landing
npm run dev  # Runs on http://localhost:5173

Rapid Prototyping (No Install)

# Create structure, install later
npx vite-spark prototype --with-backend -n

cd prototype
npm run install:all
npm run dev

🔐 Full-Stack Authentication Flow

How It Works

1. Frontend sends login request to backend
2. Backend verifies credentials, creates JWT
3. Backend sets JWT as HttpOnly cookie
4. Frontend receives user data (no token in response)
5. Frontend makes authenticated requests (cookie sent automatically)
6. Backend verifies JWT from cookie

Frontend Setup

// Using AuthContext
import { useAuth } from './context/AuthContext';

function MyComponent() {
  const { user, isAuthenticated, login, logout } = useAuth();

  return (
    <div>
      {isAuthenticated ? (
        <p>Welcome, {user.name}!</p>
      ) : (
        <button onClick={() => login({ email, password })}>
          Login
        </button>
      )}
    </div>
  );
}

Backend Setup

1. Create .env in backend folder:

NODE_ENV=development
PORT=3000
MONGODB_URI=mongodb://localhost:27017/myapp
JWT_SECRET=your-super-secret-key-min-32-chars
JWT_EXPIRES_IN=7d
CLIENT_URL=http://localhost:5173

2. API Endpoints Available:

POST   /api/v1/auth/signup       # Register
POST   /api/v1/auth/login        # Login
GET    /api/v1/auth/logout       # Logout
GET    /api/v1/auth/verify       # Verify token
PATCH  /api/v1/auth/updateme     # Update profile
GET    /api/v1/admin/users       # Get all users (admin)

3. Start MongoDB:

# Local MongoDB
mongod

# Or use MongoDB Atlas (cloud)

Environment Variables

Frontend .env:

VITE_API_BASE_URL=http://localhost:3000/api/v1

Backend .env:

NODE_ENV=development
PORT=3000
MONGODB_URI=mongodb://localhost:27017/myapp
JWT_SECRET=your-super-secret-key-change-in-production
JWT_EXPIRES_IN=7d
CLIENT_URL=http://localhost:5173
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
[email protected]
EMAIL_PASS=your-app-password

📚 Documentation

Frontend Documentation

• Vite Documentation
• React Documentation
• Tailwind CSS

Backend Documentation

• Detailed backend docs: See backend/README.md (auto-generated)
• Express.js Documentation
• MongoDB Documentation
• Mongoose Documentation

Full-Stack Guides

• Auth integration guide (in project README)
• CORS configuration
• Deployment instructions
• API documentation

🐛 Troubleshooting

Frontend Issues

Tailwind not working:

# Verify import in src/index.css
@import "tailwindcss";

# Restart dev server
npm run dev

Port 5173 in use:

npx kill-port 5173
# Or
npm run dev -- --port 3000

Backend Issues

MongoDB connection failed:

# Check if MongoDB is running
mongod --version

# Or use MongoDB Atlas cloud database

Port 3000 in use:

npx kill-port 3000
# Or change PORT in .env

Full-Stack Issues

CORS errors:

// Backend: Check CLIENT_URL in .env matches frontend
CLIENT_URL=http://localhost:5173

// Backend: Ensure credentials enabled
app.use(cors({ origin: CLIENT_URL, credentials: true }));

// Frontend: Ensure credentials included
fetch(url, { credentials: 'include' });

Auth not persisting:

1. Check browser cookies (DevTools → Application → Cookies)
2. Verify JWT_SECRET is set in backend .env
3. Ensure credentials: 'include' in frontend fetch requests
4. Check backend sets HttpOnly cookie correctly

📊 Comparison

| Feature | Vite Spark | Create React App | Vite CLI | Next.js | Express Generator | |---------|-----------|------------------|----------|---------|-------------------| | Frontend | ✅ | ✅ | ✅ | ✅ | ❌ | | Backend | ✅ | ❌ | ❌ | ✅ (API routes) | ✅ | | Full-Stack | ✅ | ❌ | ❌ | ✅ | ❌ | | Speed | ⚡⚡⚡ | ⚡ | ⚡⚡⚡ | ⚡⚡ | ⚡⚡ | | Setup Time | < 30s | ~ 2min | ~ 1min | ~ 1min | ~ 30s | | Auth Template | ✅ | ❌ | ❌ | ❌ | ❌ | | TypeScript | ✅ Auto | ✅ Manual | ✅ Manual | ✅ Auto | ❌ | | Tailwind | ✅ Auto | ❌ Manual | ❌ Manual | ❌ Manual | ❌ | | MongoDB | ✅ | ❌ | ❌ | ❌ | ❌ | | Monorepo | ✅ | ❌ | ❌ | N/A | ❌ |

📝 Quick Reference

# FRONTEND ONLY
npx vite-spark my-app                    # Default (JS + Auth)
npx vite-spark my-app -l ts --twd -i    # TS + Tailwind + Install
npx vite-spark my-app -t basic -n       # Minimal

# BACKEND ONLY
npx vite-spark my-api --backend-only    # Node.js + MongoDB
npx vite-spark my-api --backend-only -i # With install

# FULL-STACK
npx vite-spark my-app --with-backend         # JS full-stack
npx vite-spark my-app --with-backend -l ts   # TS full-stack
npx vite-spark my-app --with-backend -l ts --twd -i  # Everything

# INTERACTIVE
npx vite-spark -q                       # Asks all questions

# AFTER CREATION
cd my-app
npm install                             # If not auto-installed
npm run dev                             # Start dev server

# FULL-STACK AFTER CREATION
cd my-project
npm run install:all                     # Install all dependencies
npm run dev                             # Run both frontend & backend

🎉 Changelog

Version 2.0.0 (Current) 🆕

Major Features:

• 🌐 Full-Stack Support — Create frontend + backend together
• 🔧 Backend Templates — Node.js + Express + MongoDB
• 📦 Monorepo Setup — Run both with one command
• 🔐 Production-Ready Auth — Complete authentication system
• 🛡️ Soft Delete — Users can be restored
• 📝 Separate Git Init — Root or individual folders

Frontend:

• React 18 + Vite 5
• TypeScript/JavaScript support
• Auth & Basic templates
• Tailwind CSS v4 support

Backend:

• Express.js + MongoDB
• JWT authentication
• Role-Based Access Control
• Soft-delete plugin
• Factory pattern CRUD
• Email service (Nodemailer)
• File upload (Multer)
• Security best practices

Breaking Changes:

• Removed ReactRouter and both frontend templates
• Changed default template to Auth
• -q flag now required for interactive mode

💡 Tips & Tricks

Global Installation for Frequent Use

npm install -g vite-spark

# Then use anywhere
vite-spark my-app
vite-spark my-api --backend-only

Create Bash Alias

# Add to ~/.bashrc or ~/.zshrc
alias spark='npx vite-spark'
alias spark-full='npx vite-spark --with-backend -l ts --twd -i'
alias spark-api='npx vite-spark --backend-only -i'

# Usage
spark my-app
spark-full my-saas
spark-api my-api

Script for Multiple Projects

#!/bin/bash
# create-projects.sh

npx vite-spark frontend -l ts --twd -n &
npx vite-spark backend --backend-only -n &
wait

echo "✅ Projects created! Installing dependencies..."

cd frontend && npm install &
cd backend && npm install &
wait

echo "✅ Ready to code!"

🤝 Contributing

We welcome contributions! Here's how:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes
4. Test thoroughly
5. Commit: git commit -m "Add my feature"
6. Push: git push origin feature/my-feature
7. Open a Pull Request

Adding New Backend Templates

1. Create template folder in templates/Backend/
2. Update buildConfig() in index.js
3. Add to backend template choices
4. Test thoroughly
5. Submit PR

📄 License

MIT © Krish Patel

📞 Support

• 📖 Documentation: GitHub Wiki
• 💬 Discussions: GitHub Discussions
• 🐛 Bug Reports: GitHub Issues
• 📧 Email: [email protected]

⭐ Star Us!

If Vite Spark saved you time, please give us a star on GitHub! ⭐

Made with 💙 by developers, for developers.

Happy coding! ⚡