create-bdpamke-react-scaffold 1.0.0

package/template/HOWTOadd a page.md

@@ -0,0 +1,166 @@
+# How-To Guides
+
+## How to Add a New Page
+
+1. **Create the page component** in `src/pages/`:
+
+```jsx
+// src/pages/Dashboard.jsx
+import React from "react";
+import Container from "../components/layout/Container";
+import { Card, CardContent } from "@/components/ui/card";
+
+export default function Dashboard() {
+  return (
+    <Container>
+      <h1 className="text-3xl font-bold mb-6">Dashboard</h1>
+      <Card>
+        <p>Welcome to your dashboard!</p>
+      </Card>
+    </Container>
+  );
+}
+```
+
+2. **Add the route** in `src/App.jsx`:
+
+```jsx
+import { BrowserRouter, Routes, Route } from "react-router-dom";
+import Dashboard from "./pages/Dashboard";
+// ... other imports
+
+function App() {
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route path="/" element={<Home />} />
+        <Route path="/dashboard" element={<Dashboard />} />
+        {/* Add your new route here */}
+      </Routes>
+    </BrowserRouter>
+  );
+}
+```
+
+3. **Add navigation link** (optional) in `src/components/ui/Navbar.jsx` or `Sidebar.jsx`:
+
+```jsx
+import { Link } from "react-router-dom";
+
+<Link to="/dashboard" className="text-gray-700 hover:text-blue-600">
+  Dashboard
+</Link>
+```
+
+## How to Make a REST API Call
+
+The scaffold includes an Axios-based API client in `src/utils/api.js` with built-in CRUD methods.
+
+### Basic API Configuration
+
+Set your API base URL in a `.env` file:
+
+```bash
+VITE_API_BASE_URL=https://api.example.com
+```
+
+### Making API Calls
+
+```jsx
+import { useState, useEffect } from "react";
+import api from "../utils/api";
+
+function MyComponent() {
+  const [data, setData] = useState([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+
+  // GET request - Fetch all items
+  useEffect(() => {
+    const fetchData = async () => {
+      setLoading(true);
+      try {
+        const response = await api.getAll("/students");
+        setData(response.data);
+      } catch (err) {
+        setError(err.message);
+      } finally {
+        setLoading(false);
+      }
+    };
+    fetchData();
+  }, []);
+
+  // GET request - Fetch single item
+  const fetchStudent = async (id) => {
+    try {
+      const response = await api.getById("/students", id);
+      console.log(response.data);
+    } catch (err) {
+      console.error(err);
+    }
+  };
+
+  // POST request - Create new item
+  const createStudent = async () => {
+    try {
+      const newStudent = { name: "Ada Lovelace", grade: "A" };
+      const response = await api.create("/students", newStudent);
+      setData([...data, response.data]);
+    } catch (err) {
+      setError(err.message);
+    }
+  };
+
+  // PUT request - Update item
+  const updateStudent = async (id) => {
+    try {
+      const updates = { name: "Grace Hopper" };
+      const response = await api.update(`/students/${id}`, updates);
+      setData(data.map(item => item.id === id ? response.data : item));
+    } catch (err) {
+      setError(err.message);
+    }
+  };
+
+  // DELETE request - Remove item
+  const deleteStudent = async (id) => {
+    try {
+      await api.delete(`/students/${id}`);
+      setData(data.filter(item => item.id !== id));
+    } catch (err) {
+      setError(err.message);
+    }
+  };
+
+  return (
+    <div>
+      {loading && <p>Loading...</p>}
+      {error && <p className="text-red-500">Error: {error}</p>}
+      {/* Render your data here */}
+    </div>
+  );
+}
+```
+
+### Available API Methods
+
+- `api.getAll(endpoint)` - GET all items
+- `api.getById(endpoint, id)` - GET single item
+- `api.create(endpoint, data)` - POST new item
+- `api.update(endpoint, data)` - PUT update item
+- `api.delete(endpoint)` - DELETE item
+- `api.setToken(token)` - Set authorization token
+
+### Custom API Client
+
+Create a custom client for different base URLs:
+
+```js
+import { ApiClient } from "./utils/api";
+
+const adminApi = new ApiClient("https://admin.example.com");
+adminApi.setToken("your-jwt-token");
+
+const response = await adminApi.getAll("/users");
+```

package/template/REACT_PROPS_USEEFFECT.md

@@ -0,0 +1,210 @@
+# React Props and useEffect
+
+This guide explains two core React concepts:
+
+- `props`
+- `useEffect`
+
+## See also
+
+For plain JavaScript function examples, see `FUNCTIONS_EXAMPLES.md`.
+
+## 1. What props are
+
+Props are values passed from a parent component to a child component.
+
+They let components share data and behavior.
+
+## 2. Basic props example
+
+```jsx
+function WelcomeMessage(props) {
+  return <h1>Hello, {props.name}</h1>;
+}
+
+export default function App() {
+  return <WelcomeMessage name="Ada" />;
+}
+```
+
+Here:
+
+- `name` is a prop
+- the parent passes it in
+- the child reads it
+
+## 3. Destructured props example
+
+```jsx
+function WelcomeMessage({ name, role }) {
+  return (
+    <div>
+      <h1>Hello, {name}</h1>
+      <p>Role: {role}</p>
+    </div>
+  );
+}
+
+export default function App() {
+  return <WelcomeMessage name="Grace" role="Engineer" />;
+}
+```
+
+This is the most common style in React.
+
+## 4. Passing a function as a prop
+
+Parents can pass functions to children.
+
+```jsx
+function ChildButton({ onPress }) {
+  return <button onClick={onPress}>Click Me</button>;
+}
+
+export default function Parent() {
+  function handlePress() {
+    console.log("Button clicked in child.");
+  }
+
+  return <ChildButton onPress={handlePress} />;
+}
+```
+
+This is useful because child components can trigger logic owned by the parent.
+
+## 5. What useEffect is
+
+`useEffect` is a React hook used for side effects.
+
+Examples of side effects:
+
+- fetching API data
+- setting up timers
+- listening for browser events
+- updating browser state outside the render
+
+Basic syntax:
+
+```jsx
+import { useEffect } from "react";
+
+useEffect(() => {
+  console.log("Effect ran");
+}, []);
+```
+
+The second argument is the dependency array.
+
+## 6. Run once when the component loads
+
+```jsx
+import { useEffect } from "react";
+
+export default function Page() {
+  useEffect(() => {
+    console.log("Component mounted");
+  }, []);
+
+  return <p>Page loaded</p>;
+}
+```
+
+This runs once after the first render.
+
+## 7. Fetch data with useEffect
+
+```jsx
+import { useEffect, useState } from "react";
+
+export default function HealthCheck() {
+  const [data, setData] = useState(null);
+  const [error, setError] = useState("");
+
+  useEffect(() => {
+    const loadHealth = async () => {
+      try {
+        const response = await fetch("/api/health");
+        const result = await response.json();
+        setData(result);
+      } catch (err) {
+        setError("Failed to load health status.");
+      }
+    };
+
+    loadHealth();
+  }, []);
+
+  if (error) return <p>{error}</p>;
+  if (!data) return <p>Loading...</p>;
+
+  return <pre>{JSON.stringify(data, null, 2)}</pre>;
+}
+```
+
+This is a common pattern for loading server data when a component appears.
+
+## 8. Run when a value changes
+
+```jsx
+import { useEffect, useState } from "react";
+
+export default function SearchExample() {
+  const [query, setQuery] = useState("");
+
+  useEffect(() => {
+    if (!query) return;
+    console.log("Search query changed:", query);
+  }, [query]);
+
+  return (
+    <input
+      value={query}
+      onChange={(event) => setQuery(event.target.value)}
+      placeholder="Search"
+    />
+  );
+}
+```
+
+This effect runs every time `query` changes.
+
+## 9. Cleanup example
+
+```jsx
+import { useEffect } from "react";
+
+export default function TimerExample() {
+  useEffect(() => {
+    const id = setInterval(() => {
+      console.log("Tick");
+    }, 1000);
+
+    return () => {
+      clearInterval(id);
+    };
+  }, []);
+
+  return <p>Timer running</p>;
+}
+```
+
+The function returned by `useEffect` is cleanup logic.
+
+It runs when:
+
+- the component is removed
+- or before the effect runs again
+
+## 10. Summary
+
+Use `props` when:
+
+- a parent needs to pass data to a child
+- a parent needs to pass a function to a child
+
+Use `useEffect` when:
+
+- code should run after render
+- you need to fetch data
+- you need timers or subscriptions
+- you need cleanup logic

package/template/REGISTRATION_FLOW.md

@@ -0,0 +1,268 @@
+# Registration Flow: Send Email and Password to the Server
+
+This guide shows how to:
+
+1. Create a registration page in React
+2. Send `email` and `password` to the server
+3. Call the server-side encryption function
+4. Hash the password on the server
+5. Prove it works by printing the encrypted password in the server console
+
+Note: logging password hashes is only for development proof. Do not keep that log in production.
+
+## 1. Use the existing server-side password utility
+
+The server already has a password utility in:
+
+- `server/utils/password.js`
+
+It exports:
+
+- `hashPassword(password)`
+- `verifyPassword(password, hash)`
+- `getPasswordStrength(password)`
+- `getPasswordStrengthLabel(password)`
+
+That means the registration flow should hash the password on the server, not in React.
+
+## 2. Update the server registration route
+
+In `server/server.js`, import `hashPassword` from the server utility.
+
+Example:
+
+```js
+"use strict";
+const express = require("express");
+const cors = require("cors");
+const { ApiClient } = require("./utils/apiClient");
+const { hashPassword } = require("./utils/password");
+
+const app = express();
+const PORT = 5000;
+```
+
+Then add a registration route like this:
+
+```js
+app.post("/api/register", async (req, res) => {
+  const { email, password } = req.body;
+
+  if (!email || typeof email !== "string") {
+    return res.status(400).json({ error: "Email is required." });
+  }
+
+  if (!password || typeof password !== "string") {
+    return res.status(400).json({ error: "Password is required." });
+  }
+
+  try {
+    const hashedPassword = await hashPassword(password);
+
+    // Development proof only.
+    console.log("Registered email:", email);
+    console.log("Encrypted password:", hashedPassword);
+
+    // In a real app, save email + hashedPassword to the database here.
+    return res.status(201).json({
+      message: "Registration received.",
+      email,
+      hashedPassword,
+    });
+  } catch (error) {
+    return res.status(500).json({ error: error.message || "Registration failed." });
+  }
+});
+```
+
+## 3. Create a React registration page
+
+Create a page such as `src/pages/Register.jsx`.
+
+Example:
+
+```jsx
+import { useState } from "react";
+
+export default function Register() {
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [result, setResult] = useState(null);
+  const [error, setError] = useState("");
+
+  const handleSubmit = async (event) => {
+    event.preventDefault();
+    setError("");
+    setResult(null);
+
+    try {
+      const response = await fetch("/api/register", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ email, password }),
+      });
+
+      const data = await response.json();
+
+      if (!response.ok) {
+        throw new Error(data.error || "Request failed");
+      }
+
+      setResult(data);
+    } catch (err) {
+      setError(err.message);
+    }
+  };
+
+  return (
+    <main className="min-h-screen px-6 py-12">
+      <div className="mx-auto max-w-md">
+        <h1 className="mb-6 text-2xl font-bold">Register</h1>
+
+        <form onSubmit={handleSubmit} className="space-y-4">
+          <div>
+            <label htmlFor="email" className="block text-sm font-medium">
+              Email
+            </label>
+            <input
+              id="email"
+              type="email"
+              value={email}
+              onChange={(e) => setEmail(e.target.value)}
+              className="mt-1 w-full rounded border px-3 py-2"
+              required
+            />
+          </div>
+
+          <div>
+            <label htmlFor="password" className="block text-sm font-medium">
+              Password
+            </label>
+            <input
+              id="password"
+              type="password"
+              value={password}
+              onChange={(e) => setPassword(e.target.value)}
+              className="mt-1 w-full rounded border px-3 py-2"
+              required
+            />
+          </div>
+
+          <button
+            type="submit"
+            className="rounded bg-slate-900 px-4 py-2 text-white"
+          >
+            Submit Registration
+          </button>
+        </form>
+
+        {error ? <p className="mt-4 text-red-600">{error}</p> : null}
+
+        {result ? (
+          <pre className="mt-4 overflow-auto rounded bg-slate-100 p-4 text-sm">
+            {JSON.stringify(result, null, 2)}
+          </pre>
+        ) : null}
+      </div>
+    </main>
+  );
+}
+```
+
+## 4. Add the route in React
+
+In `src/App.jsx`, add the page route.
+
+Example:
+
+```jsx
+import { Route, Routes } from "react-router-dom";
+import Home from "./pages/Home.jsx";
+import Register from "./pages/Register.jsx";
+
+export default function App() {
+  return (
+    <Routes>
+      <Route path="/" element={<Home />} />
+      <Route path="/register" element={<Register />} />
+    </Routes>
+  );
+}
+```
+
+## 5. Why the frontend can call `/api/register`
+
+This project already proxies `/api` requests from Vite to the Express server.
+
+That setup is in:
+
+- `vite.config.mts`
+
+Because of that, this frontend request works during development:
+
+```js
+fetch("/api/register", {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({ email, password }),
+});
+```
+
+It will be forwarded to the Express server running on port `5000`.
+
+## 6. What proves the encryption worked
+
+When the form is submitted:
+
+1. React sends the plain-text `email` and `password` to `POST /api/register`
+2. The server receives them
+3. The server calls `hashPassword(password)`
+4. The server logs the hashed value with `console.log`
+
+Expected server console output will look similar to this:
+
+```txt
+Registered email: user@example.com
+Encrypted password: $2a$10$w3Pj7x8nK8D2r9M0T6Qv4eM9K5h7sX2mN1aB3cD4eF5gH6iJ7kL8m
+```
+
+The value beginning with `$2a$10$` or `$2b$10$` is a bcrypt hash, which proves the password was encrypted on the server.
+
+## 7. Quick test steps
+
+1. Start the stack:
+
+```bash
+npm run dev:all
+```
+
+2. Open the app in the browser.
+
+3. Go to `/register`.
+
+4. Enter an email and password.
+
+5. Submit the form.
+
+6. Check the server terminal.
+
+You should see the email and encrypted password in the server console.
+
+## 8. Important production note
+
+For production, remove this line after testing:
+
+```js
+console.log("Encrypted password:", hashedPassword);
+```
+
+In production, you should:
+
+- Hash the password on the server
+- Save only the hash to the database
+- Never log plain-text passwords
+- Usually avoid logging password hashes too