create-bdpamke-react-scaffold 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# create-bdpamke-react-scaffold
+
+Scaffold generator for a BDPA React full-stack starter built with Vite, Express, Tailwind CSS, and shadcn/ui.
+
+Use this package to create a new project from the BDPA scaffold template without cloning the repository manually.
+
+## Usage
+
+```bash
+npx create-bdpamke-react-scaffold my-app
+```
+
+To generate into the current empty directory:
+
+```bash
+npx create-bdpamke-react-scaffold .
+```
+
+or:
+
+```bash
+npx create-bdpamke-react-scaffold --use-current-dir
+```
+
+This creates a new project directory containing the scaffold template.
+
+## What You Get
+
+The generated project includes:
+
+- Vite + React frontend
+- Express backend in `server/`
+- Tailwind CSS configuration
+- shadcn/ui component scaffold
+- starter docs and example guides
+- image assets and app structure ready to customize
+
+## Quick Start
+
+If you generated into a new directory:
+
+```bash
+cd my-app
+npm install
+npm run dev:all
+```
+
+If you generated into the current directory, skip the `cd` step.
+
+## Optional Git Setup
+
+```bash
+git init
+git add .
+git commit -m "Initial commit"
+```
+
+## Notes
+
+- The generated app is a starter scaffold, not a published component library.
+- The template is intended to be customized after generation.
+- Run `npm run dev:all` in the generated project to start both the frontend and backend together.

package/bin/create-bdpamke-react-scaffold.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+function printUsage() {
+  console.log("Usage: create-bdpamke-react-scaffold <project-directory>");
+  console.log("       create-bdpamke-react-scaffold .");
+  console.log("       create-bdpamke-react-scaffold --use-current-dir");
+}
+
+function normalizePackageName(value) {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-_]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .replace(/-{2,}/g, "-") || "bdpa-react-scaffold-app";
+}
+
+function updateJsonFile(filePath, updater) {
+  const raw = fs.readFileSync(filePath, "utf8");
+  const parsed = JSON.parse(raw);
+  const updated = updater(parsed);
+  fs.writeFileSync(filePath, `${JSON.stringify(updated, null, 2)}\n`, "utf8");
+}
+
+const args = process.argv.slice(2);
+const targetArg = args[0];
+const useCurrentDir = targetArg === "." || targetArg === "--use-current-dir";
+
+if (!targetArg || targetArg === "-h" || targetArg === "--help") {
+  printUsage();
+  process.exit(targetArg ? 0 : 1);
+}
+
+if (args.length > 1) {
+  console.error("Too many arguments provided.");
+  printUsage();
+  process.exit(1);
+}
+
+const cwd = process.cwd();
+const templateDir = path.resolve(__dirname, "..", "template");
+const targetDir = useCurrentDir ? cwd : path.resolve(cwd, targetArg);
+const projectName = path.basename(targetDir);
+const normalizedPackageName = normalizePackageName(projectName);
+
+if (fs.existsSync(targetDir)) {
+  const existing = fs.readdirSync(targetDir);
+  if (existing.length > 0) {
+    console.error(`Target directory is not empty: ${targetDir}`);
+    process.exit(1);
+  }
+} else {
+  fs.mkdirSync(targetDir, { recursive: true });
+}
+
+fs.cpSync(templateDir, targetDir, { recursive: true });
+
+updateJsonFile(path.join(targetDir, "package.json"), (pkg) => ({
+  ...pkg,
+  name: normalizedPackageName,
+  version: "0.1.0"
+}));
+
+const packageLockPath = path.join(targetDir, "package-lock.json");
+
+if (fs.existsSync(packageLockPath)) {
+  updateJsonFile(packageLockPath, (lockfile) => {
+    const updated = {
+      ...lockfile,
+      name: normalizedPackageName,
+      version: "0.1.0"
+    };
+
+    if (updated.packages && updated.packages[""]) {
+      updated.packages[""] = {
+        ...updated.packages[""],
+        name: normalizedPackageName,
+        version: "0.1.0"
+      };
+    }
+
+    return updated;
+  });
+}
+
+console.log(`Created project in ${targetDir}`);
+console.log("");
+console.log("Next steps:");
+if (!useCurrentDir) {
+  console.log(`  cd ${path.relative(cwd, targetDir) || "."}`);
+}
+console.log("  npm install");
+console.log("  npm run dev:all");
+console.log("");
+console.log("Optional git setup:");
+console.log("  git init");
+console.log("  git add .");
+console.log('  git commit -m "Initial commit"');

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "create-bdpamke-react-scaffold",
+  "version": "1.0.0",
+  "description": "Scaffold generator for a BDPA React full-stack starter with Vite, Express, Tailwind CSS, and shadcn/ui.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lxdavis9lxd/create-bdpamke-react-scaffoldfullstack-basic.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lxdavis9lxd/create-bdpamke-react-scaffoldfullstack-basic/issues"
+  },
+  "homepage": "https://github.com/lxdavis9lxd/create-bdpamke-react-scaffoldfullstack-basic#readme",
+  "bin": {
+    "create-bdpamke-react-scaffold": "bin/create-bdpamke-react-scaffold.js"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "keywords": [
+    "bdpa",
+    "react",
+    "vite",
+    "express",
+    "scaffold",
+    "generator",
+    "create-app",
+    "starter",
+    "template",
+    "boilerplate",
+    "full-stack",
+    "tailwindcss",
+    "shadcn-ui"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/template/.env.example

@@ -0,0 +1,6 @@
+# React / Vite client
+VITE_API_BASE_URL=http://localhost:5000
+
+# Express server
+PORT=5000
+CLIENT_ORIGIN=http://localhost:3000

package/template/FUNCTIONS_EXAMPLES.md

@@ -0,0 +1,480 @@
+# Functions Examples
+
+This guide explains what functions are in JavaScript and shows common patterns you will use in general JavaScript, Node.js, and server code.
+
+## See also
+
+For React-specific examples with `props` and `useEffect`, see `REACT_PROPS_USEEFFECT.md`.
+
+## 1. What a function is
+
+A function is a reusable block of code.
+
+You define it once, then call it whenever you need that logic.
+
+Functions help you:
+
+- avoid repeating code
+- organize logic
+- make code easier to read
+- pass behavior into other code
+
+## 2. Basic function declaration
+
+```js
+function sayHello() {
+  console.log("Hello");
+}
+
+sayHello();
+```
+
+What happens:
+
+- `sayHello` is the function name
+- the code inside `{}` runs when you call it
+- `sayHello()` calls the function
+
+## 3. Function with parameters
+
+Parameters let you pass values into a function.
+
+```js
+function greet(name) {
+  console.log("Hello, " + name);
+}
+
+greet("Ada");
+greet("Grace");
+```
+
+Here:
+
+- `name` is the parameter
+- `"Ada"` and `"Grace"` are arguments
+
+## 4. Function that returns a value
+
+A function can give a value back using `return`.
+
+```js
+function add(a, b) {
+  return a + b;
+}
+
+const total = add(2, 3);
+console.log(total);
+```
+
+What happens:
+
+- `add(2, 3)` returns `5`
+- that returned value is stored in `total`
+
+## 5. Function expression
+
+You can store a function in a variable.
+
+```js
+const multiply = function (a, b) {
+  return a * b;
+};
+
+console.log(multiply(4, 5));
+```
+
+This is called a function expression.
+
+## 6. Arrow function
+
+Arrow functions are a shorter syntax.
+
+```js
+const subtract = (a, b) => {
+  return a - b;
+};
+
+console.log(subtract(10, 4));
+```
+
+Shorter version when there is only one expression:
+
+```js
+const square = (number) => number * number;
+
+console.log(square(6));
+```
+
+## 7. Function with no parameters
+
+```js
+const showMessage = () => {
+  console.log("This function takes no arguments.");
+};
+
+showMessage();
+```
+
+## 8. Function with one parameter
+
+```js
+const double = (value) => value * 2;
+
+console.log(double(8));
+```
+
+## 9. Function with default values
+
+Default values are used when no argument is passed.
+
+```js
+function greetUser(name = "friend") {
+  return "Hello, " + name;
+}
+
+console.log(greetUser());
+console.log(greetUser("Jordan"));
+```
+
+## 10. Function passed as a callback
+
+A callback is a function passed into another function.
+
+```js
+function processUserInput(callback) {
+  const name = "Taylor";
+  callback(name);
+}
+
+processUserInput(function (value) {
+  console.log("Received:", value);
+});
+```
+
+Arrow function version:
+
+```js
+processUserInput((value) => {
+  console.log("Received:", value);
+});
+```
+
+## 11. Functions in array methods
+
+Functions are often passed into `.map()`, `.filter()`, and `.forEach()`.
+
+### `map`
+
+```js
+const numbers = [1, 2, 3];
+const doubled = numbers.map((number) => number * 2);
+
+console.log(doubled);
+```
+
+### `filter`
+
+```js
+const numbers = [1, 2, 3, 4, 5];
+const evenNumbers = numbers.filter((number) => number % 2 === 0);
+
+console.log(evenNumbers);
+```
+
+### `forEach`
+
+```js
+const names = ["Ada", "Grace", "Linus"];
+
+names.forEach((name) => {
+  console.log(name);
+});
+```
+
+## 12. Function that returns an object
+
+```js
+function createUser(email, role) {
+  return {
+    email,
+    role,
+  };
+}
+
+const user = createUser("user@example.com", "admin");
+console.log(user);
+```
+
+This is useful when building structured data.
+
+## 13. Async functions
+
+An `async` function lets you use `await`.
+
+```js
+async function getHealth() {
+  const response = await fetch("/api/health");
+  const data = await response.json();
+  return data;
+}
+```
+
+Using it:
+
+```js
+getHealth().then((result) => {
+  console.log(result);
+});
+```
+
+Or inside another async function:
+
+```js
+async function run() {
+  const result = await getHealth();
+  console.log(result);
+}
+
+run();
+```
+
+## 14. Server-side function example
+
+This matches the kind of code used in Express routes.
+
+```js
+function validateEmail(email) {
+  if (!email || typeof email !== "string") {
+    throw new Error("Email is required.");
+  }
+
+  return email.includes("@");
+}
+
+console.log(validateEmail("user@example.com"));
+```
+
+This function:
+
+- checks input
+- throws an error if the input is invalid
+- returns `true` or `false`
+
+## 15. Function that calls another function
+
+Functions are often combined.
+
+```js
+function formatName(name) {
+  return name.trim().toUpperCase();
+}
+
+function greetFormattedName(name) {
+  const cleanName = formatName(name);
+  return "Hello, " + cleanName;
+}
+
+console.log(greetFormattedName("  ada  "));
+```
+
+This helps break large tasks into smaller pieces.
+
+## 16. Pure functions
+
+A pure function:
+
+- gives the same output for the same input
+- does not change values outside itself
+
+```js
+function toCelsius(fahrenheit) {
+  return (fahrenheit - 32) * (5 / 9);
+}
+```
+
+Pure functions are easier to test and reuse.
+
+## 17. Impure function example
+
+```js
+let total = 0;
+
+function addToTotal(value) {
+  total += value;
+}
+```
+
+This changes outside state, so it is not pure.
+
+Impure functions are not always wrong, but they require more care.
+
+## 18. Common mistakes
+
+### Mistake: forgetting to call the function
+
+Wrong:
+
+```js
+console.log(add);
+```
+
+Correct:
+
+```js
+console.log(add(2, 3));
+```
+
+### Mistake: forgetting `return`
+
+Wrong:
+
+```js
+function add(a, b) {
+  a + b;
+}
+```
+
+Correct:
+
+```js
+function add(a, b) {
+  return a + b;
+}
+```
+
+### Mistake: calling the function immediately
+
+Wrong:
+
+```js
+runTask();
+```
+
+when you meant to pass the function itself somewhere.
+
+Correct:
+
+```js
+runTask;
+```
+
+or pass it as a callback where needed.
+
+## 19. When to use each style
+
+### Function declaration
+
+Use when:
+
+- you want a named reusable function
+- you want clear readability
+- you define general-purpose logic
+
+```js
+function calculateTotal(price, tax) {
+  return price + tax;
+}
+```
+
+### Function expression
+
+Use when:
+
+- you want to store a function in a variable
+- you want to pass it around
+
+```js
+const calculateTotal = function (price, tax) {
+  return price + tax;
+};
+```
+
+### Arrow function
+
+Use when:
+
+- you want shorter syntax
+- you are writing callbacks
+- you want consistency in modern JavaScript code
+
+```js
+const calculateTotal = (price, tax) => price + tax;
+```
+
+## 20. Summary
+
+Functions are one of the most important parts of JavaScript.
+
+They let you:
+
+- group logic
+- reuse code
+- respond to events
+- process data
+- call APIs
+- structure backend and utility code
+
+Examples in this guide covered:
+
+- function declarations
+- parameters and return values
+- function expressions
+- arrow functions
+- callbacks
+- async functions
+- array method callbacks
+- server-side validation functions
+- pure and impure functions
+
+A simple rule:
+
+- if you want reusable logic, put it in a function
+- if the code should run later, pass a function
+- if you need a result back, `return` a value
+
+- you want to store a function in a variable
+- you want to pass it around
+
+```js
+const calculateTotal = function (price, tax) {
+  return price + tax;
+};
+```
+
+### Arrow function
+
+Use when:
+
+- you want shorter syntax
+- you are writing callbacks
+- you want consistency in modern React code
+
+```js
+const calculateTotal = (price, tax) => price + tax;
+```
+
+## 22. Summary
+
+Functions are one of the most important parts of JavaScript.
+
+They let you:
+
+- group logic
+- reuse code
+- respond to events
+- process data
+- call APIs
+- structure React components and server code
+
+Common patterns you will use often:
+
+- `function name() {}`
+- `const name = function () {}`
+- `const name = () => {}`
+- `async function name() {}`
+
+A simple rule:
+
+- if you want reusable logic, put it in a function
+- if the code should run later, pass a function
+- if you need a result back, `return` a value