create-butterfly-app-v2 1.0.0

package/README.md

@@ -0,0 +1,152 @@
+# create-butterfly-app
+
+Scaffold a full-stack **Node.js + React + Tailwind + MySQL** project in seconds.
+
+```bash
+npx create-butterfly-app my-project
+cd my-project
+npm run dev
+```
+
+---
+
+## Why this exists
+
+If you have an **exam or assignment** that requires a working full-stack web app — with a backend API, a database, and a modern frontend — but you **don't know how to set it all up from scratch**, this boilerplate is for you.
+
+Instead of spending hours wiring up Express, configuring Vite, installing Tailwind, connecting MySQL — writing boilerplate config files you don't understand — you get a **ready-to-run project** with one command.
+
+You only need to know:
+1. **That XAMPP must be running** (start Apache & MySQL from the XAMPP Control Panel)
+2. **How to create a database** (open phpMyAdmin, click "New", type your project name, click "Create")
+3. **How to run `npm run dev`** in the terminal
+
+That's it.
+
+---
+
+## What you get
+
+```
+my-project/
+├── backend/
+│   ├── server.js       # Express server, starts on port 5000
+│   ├── config/db.js    # MySQL connection via XAMPP
+│   └── routes/api.js   # /api/users GET + POST
+├── frontend/
+│   ├── src/App.jsx     # React UI with Tailwind styling
+│   ├── src/main.jsx    # React entry point
+│   ├── vite.config.js  # Dev server + proxy to backend
+│   ├── tailwind.config.js
+│   └── postcss.config.js
+├── .env                # DB credentials (user=root, password=blank)
+└── package.json        # Runs both backend & frontend together
+```
+
+---
+
+## How to use it in an exam / project
+
+### Step 1 — Start XAMPP
+
+Open **XAMPP Control Panel** → click **Start** next to **Apache** and **MySQL**.
+
+### Step 2 — Create the database
+
+Open your browser, go to `http://localhost/phpmyadmin`:
+- Click **New** (left sidebar)
+- Type your project name as the database name
+- Click **Create** (no tables needed — the API will create them if you want, or you can add a table manually)
+
+### Step 3 — Create the project
+
+```bash
+npx create-butterfly-app my-exam-project
+cd my-exam-project
+```
+
+### Step 4 — Start the app
+
+```bash
+npm run dev
+```
+
+This starts:
+- **Backend** on `http://localhost:5000`
+- **Frontend** on `http://localhost:5173` (opens in browser automatically)
+
+### Step 5 — Add a users table (required for the demo)
+
+Go to `http://localhost/phpmyadmin`, select your database, and run this SQL:
+
+```sql
+CREATE TABLE users (
+  id INT AUTO_INCREMENT PRIMARY KEY,
+  name VARCHAR(100) NOT NULL,
+  email VARCHAR(100) NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+Now the app works — add users from the browser UI, see them stored in MySQL.
+
+---
+
+## Why this is effective when you don't know code
+
+| Problem | Solution |
+|--------|----------|
+| "I don't know how to set up a Node.js server" | `server.js` is pre-written with Express |
+| "I don't know how to connect to MySQL" | `config/db.js` connects automatically using `.env` |
+| "I don't know React or Tailwind" | `App.jsx` gives you a styled working UI |
+| "I can't configure Vite" | `vite.config.js` is ready with API proxy |
+| "I don't understand npm" | One command installs everything |
+| "I don't know how to run two servers at once" | `concurrently` runs both with `npm run dev` |
+
+The boilerplate handles **every configuration detail**. You focus only on:
+- **Modifying the HTML/JSX** if you want to change the page layout
+- **Adding SQL queries** in `routes/api.js` if you need more features
+- **Changing the CSS** with Tailwind utility classes if you want different colors
+
+Everything else works out of the box.
+
+---
+
+## Testing locally without publishing
+
+```bash
+# From the create-butterfly-app folder
+npm link
+create-butterfly-app my-test
+```
+
+---
+
+## Publishing your own version
+
+```bash
+cd create-butterfly-app
+npm login
+npm publish
+```
+
+Then anyone can run:
+
+```bash
+npx create-butterfly-app any-project-name
+```
+
+---
+
+## Important notes for exams
+
+- **XAMPP must be running** before you start the app
+- The `.env` file assumes default XAMPP credentials (`root` / blank password / port 3306) — change if yours is different
+- The app runs on **port 5000** (backend) and **port 5173** (frontend) — make sure these are free
+- If the frontend can't reach the backend, check that the proxy in `vite.config.js` matches the backend port
+
+---
+
+## License
+
+MIT — use it for anything, including exams.

package/cli.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+const projectName = process.argv[2] || "my-fullstack-app";
+const targetDir = path.resolve(process.cwd(), projectName);
+const templateDir = path.join(__dirname, "templates", "fullstack");
+
+if (fs.existsSync(targetDir)) {
+  console.error(`Error: Directory "${projectName}" already exists.`);
+  process.exit(1);
+}
+
+console.log(`\n  Creating ${projectName}...\n`);
+
+function copyRecursive(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyRecursive(srcPath, destPath);
+    } else {
+      let content = fs.readFileSync(srcPath, "utf-8");
+      content = content.replace(/__PROJECT_NAME__/g, projectName);
+      fs.writeFileSync(destPath, content);
+    }
+  }
+}
+
+copyRecursive(templateDir, targetDir);
+console.log(`  Created project at: ${targetDir}\n`);
+
+try {
+  console.log("  Installing backend dependencies...");
+  execSync("npm install", { cwd: path.join(targetDir, "backend"), stdio: "inherit" });
+  console.log("  Installing frontend dependencies...");
+  execSync("npm install", { cwd: path.join(targetDir, "frontend"), stdio: "inherit" });
+  console.log("  Installing root dependencies...");
+  execSync("npm install", { cwd: targetDir, stdio: "inherit" });
+} catch {
+  console.log("\n  Run 'npm install' in each folder manually if install failed.");
+}
+
+console.log(`\n  Done! Run these commands:\n`);
+console.log(`    cd ${projectName}`);
+console.log(`    npm run dev        # starts both backend & frontend\n`);

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "create-butterfly-app-v2",
+  "version": "1.0.0",
+  "description": "Scaffold a full-stack Node.js + React + Tailwind + MySQL project",
+  "bin": {
+    "create-butterfly-app": "cli.js"
+  },
+  "files": [
+    "cli.js",
+    "templates/"
+  ],
+  "license": "MIT"
+}

package/templates/fullstack/backend/config/db.js

@@ -0,0 +1,13 @@
+const mysql = require("mysql2/promise");
+
+const pool = mysql.createPool({
+  host: process.env.DB_HOST || "localhost",
+  user: process.env.DB_USER || "root",
+  password: process.env.DB_PASSWORD || "",
+  database: process.env.DB_NAME || "__PROJECT_NAME__",
+  port: process.env.DB_PORT || 3306,
+  waitForConnections: true,
+  connectionLimit: 10,
+});
+
+module.exports = pool;

package/templates/fullstack/backend/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "__PROJECT_NAME__-backend",
+  "private": true,
+  "scripts": {
+    "dev": "nodemon server.js"
+  },
+  "dependencies": {
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.7",
+    "express": "^4.21.1",
+    "mysql2": "^3.11.5"
+  },
+  "devDependencies": {
+    "nodemon": "^3.1.9"
+  }
+}

package/templates/fullstack/backend/routes/api.js

@@ -0,0 +1,26 @@
+const router = require("express").Router();
+const db = require("../config/db");
+
+router.get("/users", async (req, res) => {
+  try {
+    const [rows] = await db.query("SELECT * FROM users");
+    res.json(rows);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+router.post("/users", async (req, res) => {
+  const { name, email } = req.body;
+  try {
+    const [result] = await db.query(
+      "INSERT INTO users (name, email) VALUES (?, ?)",
+      [name, email]
+    );
+    res.status(201).json({ id: result.insertId, name, email });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+module.exports = router;

package/templates/fullstack/backend/server.js

@@ -0,0 +1,26 @@
+require("dotenv").config({ path: "../.env" });
+const express = require("express");
+const cors = require("cors");
+const db = require("./config/db");
+
+const app = express();
+const PORT = process.env.PORT || 5000;
+
+app.use(cors());
+app.use(express.json());
+
+app.get("/api/health", (req, res) => {
+  res.json({ status: "ok", project: "__PROJECT_NAME__" });
+});
+
+app.use("/api", require("./routes/api"));
+
+db.query("SELECT 1")
+  .then(() => {
+    console.log("MySQL connected");
+    app.listen(PORT, () => console.log(`Backend on http://localhost:${PORT}`));
+  })
+  .catch((err) => {
+    console.error("MySQL connection failed:", err.message);
+    process.exit(1);
+  });

package/templates/fullstack/frontend/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>__PROJECT_NAME__</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

package/templates/fullstack/frontend/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "__PROJECT_NAME__-frontend",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.3.4",
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.17",
+    "vite": "^6.0.6"
+  }
+}

package/templates/fullstack/frontend/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

package/templates/fullstack/frontend/src/App.jsx

@@ -0,0 +1,86 @@
+import { useState, useEffect } from "react";
+
+function App() {
+  const [users, setUsers] = useState([]);
+  const [name, setName] = useState("");
+  const [email, setEmail] = useState("");
+  const [status, setStatus] = useState("");
+
+  useEffect(() => {
+    fetch("/api/health")
+      .then((r) => r.json())
+      .then((d) => setStatus(d.status))
+      .catch(() => setStatus("no connection"));
+  }, []);
+
+  useEffect(() => {
+    fetch("/api/users")
+      .then((r) => r.json())
+      .then(setUsers)
+      .catch(console.error);
+  }, []);
+
+  const addUser = async (e) => {
+    e.preventDefault();
+    const res = await fetch("/api/users", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name, email }),
+    });
+    if (res.ok) {
+      const user = await res.json();
+      setUsers((prev) => [...prev, user]);
+      setName("");
+      setEmail("");
+    }
+  };
+
+  return (
+    <div className="min-h-screen bg-gray-100 flex flex-col items-center p-6">
+      <h1 className="text-4xl font-bold text-blue-600 mb-2">__PROJECT_NAME__</h1>
+      <p className="text-gray-500 mb-6">Backend: {status}</p>
+
+      <form onSubmit={addUser} className="flex gap-2 mb-6">
+        <input
+          className="border rounded px-3 py-2"
+          placeholder="Name"
+          value={name}
+          onChange={(e) => setName(e.target.value)}
+          required
+        />
+        <input
+          className="border rounded px-3 py-2"
+          type="email"
+          placeholder="Email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          required
+        />
+        <button className="bg-blue-600 text-white rounded px-4 py-2 hover:bg-blue-700">
+          Add User
+        </button>
+      </form>
+
+      <table className="w-full max-w-lg bg-white rounded shadow">
+        <thead>
+          <tr className="border-b bg-gray-50">
+            <th className="p-2 text-left">ID</th>
+            <th className="p-2 text-left">Name</th>
+            <th className="p-2 text-left">Email</th>
+          </tr>
+        </thead>
+        <tbody>
+          {users.map((u) => (
+            <tr key={u.id} className="border-b">
+              <td className="p-2">{u.id}</td>
+              <td className="p-2">{u.name}</td>
+              <td className="p-2">{u.email}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
+export default App;

package/templates/fullstack/frontend/src/index.css

@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;

package/templates/fullstack/frontend/src/main.jsx

@@ -0,0 +1,10 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import App from "./App";
+import "./index.css";
+
+createRoot(document.getElementById("root")).render(
+  <StrictMode>
+    <App />
+  </StrictMode>
+);

package/templates/fullstack/frontend/tailwind.config.js

@@ -0,0 +1,8 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: ["./index.html", "./src/**/*.{js,jsx}"],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+};

package/templates/fullstack/frontend/vite.config.js

@@ -0,0 +1,12 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 5173,
+    proxy: {
+      "/api": "http://localhost:5000",
+    },
+  },
+});

package/templates/fullstack/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "__PROJECT_NAME__",
+  "private": true,
+  "scripts": {
+    "dev": "concurrently \"npm run dev --prefix backend\" \"npm run dev --prefix frontend\"",
+    "backend": "npm run dev --prefix backend",
+    "frontend": "npm run dev --prefix frontend"
+  },
+  "devDependencies": {
+    "concurrently": "^9.1.0"
+  }
+}