stack-starter-cli 1.0.0 → 1.1.0

package/README.md

@@ -1,33 +1,186 @@
-# starter-cli
+# stack-starter-cli
 
-A simple CLI tool to quickly create full stack starter projects.
+A simple CLI tool to quickly create starter projects for frontend, backend, or full stack development.
+
+It helps you create project folders, install dependencies, and generate starter files in a few commands.
+
+---
 
 ## Features
 
-- HTML / CSS / JavaScript starter
-- React.js starter using Vite
-- Node.js backend using Express
-- Automatic starter files and folder structure
+* HTML / CSS / JavaScript starter
+* React starter using Vite
+* Node.js backend using Express
+* Custom backend port support
+* Automatic `.env` file creation
+* Package manager choice: npm, yarn, or pnpm
+* Ready-to-use starter folder structure
+
+---
+
+## Install
+
+Install globally from npm:
+
+```bash
+npm install -g stack-starter-cli
+```
+
+After installing, use the command:
+
+```bash
+stack-starter
+```
+
+---
+
+## Basic Usage
+
+### Interactive mode
+
+```bash
+stack-starter
+```
+
+The CLI will ask for project details step by step.
+
+---
+
+### Create a project with only project name
+
+```bash
+stack-starter my-app
+```
+
+The CLI will ask the remaining questions.
+
+---
+
+## Frontend and Backend Commands
+
+### React + Node.js
+
+```bash
+stack-starter my-app --react --node
+```
+
+### HTML + Node.js
+
+```bash
+stack-starter my-app --html --node
+```
+
+### React only
+
+```bash
+stack-starter my-app --react
+```
+
+### HTML only
+
+```bash
+stack-starter my-app --html
+```
+
+### Node.js only
 
-## Run locally
+```bash
+stack-starter my-app --node
+```
+
+---
+
+## Version 1.1.0 Features
+
+### Custom backend port
+
+```bash
+stack-starter my-app --react --node --port 8000
+```
+
+If no port is given, the default port is `5000`.
+
+If the selected port is invalid or already in use, the CLI shows a clear message.
+
+---
+
+### Package manager selection
+
+### npm
+
+```bash
+stack-starter my-app --react --node --pm npm
+```
+
+### yarn
+
+```bash
+stack-starter my-app --react --node --pm yarn
+```
+
+### pnpm
+
+```bash
+stack-starter my-app --react --node --pm pnpm
+```
+
+If the selected package manager is not installed, the CLI will stop and show a message.
+
+---
+
+## Generated Project Structure
+
+Example for full stack projects:
+
+```text
+my-app/
+  client/
+  server/
+  .gitignore
+  README.md
+```
+
+---
+
+## Help
+
+Show help:
 
 ```bash
-npm install
-node bin/index.js
+stack-starter --help
+```
 
-After that:
+Show version:
 
-git add .
-git commit -m "Add README"
+```bash
+stack-starter --version
 ```
 
+---
+
+## Example Commands
+
 ```bash
-shortcuts:
-- stack-starter
-- stack-starter my-app
-- stack-starter my-app --react
-- stack-starter my-app --html
-- stack-starter my-app --react --node
-- stack-starter my-app --html --node
-- stack-starter --help
-- stack-starter --version
+stack-starter
+stack-starter my-app
+stack-starter my-app --react
+stack-starter my-app --html
+stack-starter my-app --react --node
+stack-starter my-app --html --node
+stack-starter my-app --react --node --port 8000
+stack-starter my-app --react --node --pm npm
+```
+
+---
+
+## Notes
+
+* The project folder name must be unique.
+* If the folder already exists, the CLI will stop before asking setup questions.
+* For backend projects, a `.env` file is created automatically.
+
+---
+
+## License
+
+MIT

package/bin/index.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 // -----------------------------
 // Required packages
@@ -6,22 +6,25 @@
 const inquirer = require("inquirer").default;
 const fs = require("fs");
 const path = require("path");
+const net = require("net");
 const { execSync } = require("child_process");
 
 // -----------------------------
-// starter --help and --version
+// Help / Version
 // -----------------------------
 const packageJson = require("../package.json");
 
 if (process.argv.includes("--help") || process.argv.includes("-h")) {
   console.log(`
-starter - project scaffolding CLI
+stack-starter - project scaffolding CLI
 
 Usage:
-  starter
-  starter my-app
-  starter my-app --react --node
-  starter my-app --html
+  stack-starter
+  stack-starter my-app
+  stack-starter my-app --react --node
+  stack-starter my-app --html
+  stack-starter my-app --react --node --port 8000
+  stack-starter my-app --react --node --pm pnpm
 
 Options:
   --help, -h       Show help
@@ -29,11 +32,8 @@ Options:
   --react          Use React.js (Vite)
   --html           Use HTML / CSS / JavaScript
   --node           Use Node.js (Express)
-
-What it can create:
-  • HTML / CSS / JavaScript starter
-  • React.js (Vite) starter
-  • Node.js (Express) backend
+  --port           Custom backend port
+  --pm             Package manager (npm, yarn, pnpm)
 `);
   process.exit(0);
 }
@@ -55,8 +55,14 @@ const useReact = process.argv.includes("--react");
 const useHtml = process.argv.includes("--html");
 const useNode = process.argv.includes("--node");
 
+const portIndex = process.argv.indexOf("--port");
+const cliPort = portIndex !== -1 ? process.argv[portIndex + 1] : null;
+
+const pmIndex = process.argv.indexOf("--pm");
+const cliPackageManager = pmIndex !== -1 ? process.argv[pmIndex + 1] : null;
+
 // -----------------------------
-// Resolve CLI-selected frontend/backend
+// Resolve frontend/backend
 // -----------------------------
 let cliFrontend = null;
 let cliBackend = null;
@@ -65,8 +71,30 @@ if (useReact) cliFrontend = "React.js (Vite)";
 if (useHtml) cliFrontend = "HTML / CSS / JavaScript";
 if (useNode) cliBackend = "Node.js (Express)";
 
+// if user explicitly chooses only frontend
+if ((useReact || useHtml) && !useNode) {
+  cliBackend = "None";
+}
+
+// if user explicitly chooses only backend
+if (useNode && !useReact && !useHtml) {
+  cliFrontend = "None";
+}
+
+// -----------------------------
+// Early duplicate folder check
+// -----------------------------
+if (cliProjectName) {
+  const earlyProjectPath = path.join(process.cwd(), cliProjectName);
+
+  if (fs.existsSync(earlyProjectPath)) {
+    console.log("\nA project with this name already exists.");
+    process.exit(0);
+  }
+}
+
 // -----------------------------
-// Helper: copy template files
+// Helper: copy template
 // -----------------------------
 function copyTemplate(source, destination) {
   const content = fs.readFileSync(source, "utf-8");
@@ -74,7 +102,54 @@ function copyTemplate(source, destination) {
 }
 
 // -----------------------------
-// Ask user for project details
+// Helper: package manager installed?
+// -----------------------------
+function isPackageManagerInstalled(pm) {
+  try {
+    execSync(`${pm} --version`, {
+      stdio: "ignore",
+      shell: process.env.ComSpec,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// -----------------------------
+// Early package manager check
+// -----------------------------
+if (cliPackageManager) {
+  if (!["npm", "yarn", "pnpm"].includes(cliPackageManager)) {
+    console.log("\nInvalid package manager. Use npm, yarn, or pnpm.");
+    process.exit(0);
+  }
+
+  if (!isPackageManagerInstalled(cliPackageManager)) {
+    console.log(`\n${cliPackageManager} is not installed on this machine.`);
+    process.exit(0);
+  }
+}
+
+// -----------------------------
+// Helper: check free port
+// -----------------------------
+function isPortFree(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+
+    server.once("error", () => resolve(false));
+
+    server.once("listening", () => {
+      server.close(() => resolve(true));
+    });
+
+    server.listen(port);
+  });
+}
+
+// -----------------------------
+// Prompt
 // -----------------------------
 inquirer
   .prompt([
@@ -113,46 +188,87 @@ inquirer
       default: 1,
       when: !cliBackend,
     },
-  ])
-  .then((answers) => {
-    if (cliProjectName) {
-      answers.projectName = cliProjectName;
-    }
+    {
+      name: "port",
+      message: "Enter backend port:",
+      default: cliPort || "5000",
+      when(answers) {
+        return (
+          !cliPort &&
+          (cliBackend === "Node.js (Express)" ||
+            answers.backend === "Node.js (Express)")
+        );
+      },
+      validate(input) {
+        if (!/^[0-9]+$/.test(input)) {
+          return "Entered wrong port number format. Example: 8000";
+        }
 
-    if (cliFrontend) {
-      answers.frontend = cliFrontend;
-    }
+        const port = Number(input);
 
-    if (cliBackend) {
-      answers.backend = cliBackend;
-    }
+        if (port < 1 || port > 65535) {
+          return "Port must be between 1 and 65535.";
+        }
 
-    if (!answers.frontend) {
-      answers.frontend = "None";
-    }
+        return true;
+      },
+    },
+    {
+      name: "packageManager",
+      message: "Choose package manager:",
+      type: "rawlist",
+      choices: ["npm", "yarn", "pnpm"],
+      default: 0,
+      when: !cliPackageManager,
+    },
+  ])
+  .then(async (answers) => {
+    if (cliProjectName) answers.projectName = cliProjectName;
+    if (cliFrontend) answers.frontend = cliFrontend;
+    if (cliBackend) answers.backend = cliBackend;
 
-    if (!answers.backend) {
-      answers.backend = "None";
-    }
+    if (!answers.frontend) answers.frontend = "None";
+    if (!answers.backend) answers.backend = "None";
 
-    const projectPath = path.join(process.cwd(), answers.projectName);
+    answers.packageManager =
+      cliPackageManager || answers.packageManager || "npm";
 
     // -----------------------------
-    // Prevent duplicate folder names
+    // Late duplicate check (manual prompt project name)
     // -----------------------------
+    const projectPath = path.join(process.cwd(), answers.projectName);
+
     if (fs.existsSync(projectPath)) {
       console.log("\nA project with this name already exists.");
       return;
     }
 
     // -----------------------------
-    // Create root project folder
+    // Port validation
     // -----------------------------
-    fs.mkdirSync(projectPath);
+    if (answers.backend === "Node.js (Express)") {
+      answers.port = Number(cliPort || answers.port || 5000);
+
+      if (!/^[0-9]+$/.test(String(answers.port))) {
+        console.log("\nEntered wrong port number format. Example: 8000");
+        return;
+      }
+
+      const free = await isPortFree(answers.port);
+
+      if (!free) {
+        console.log(
+          `\nSomething is already running on port ${answers.port}. Choose another port.`
+        );
+        return;
+      }
+    }
 
     // -----------------------------
-    // Base project files
+    // Create project root
     // -----------------------------
+    fs.mkdirSync(projectPath);
+
     fs.writeFileSync(
       path.join(projectPath, ".gitignore"),
       "node_modules\n.env\ndist\n.vite\n.DS_Store\ncoverage"
@@ -164,7 +280,7 @@ inquirer
     );
 
     // =====================================================
-    // BACKEND SETUP
+    // BACKEND
     // =====================================================
     if (answers.backend === "Node.js (Express)") {
       const serverPath = path.join(projectPath, "server");
@@ -174,6 +290,8 @@ inquirer
       console.log("\nSetting up backend...");
 
       try {
+        const pm = answers.packageManager;
+
         execSync("npm init -y", {
           cwd: serverPath,
           stdio: "inherit",
@@ -191,35 +309,68 @@ inquirer
           };
 
           fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
+        }
 
-          console.log("✅ Scripts added to package.json");
+        if (pm === "npm") {
+          execSync("npm install express cors dotenv", {
+            cwd: serverPath,
+            stdio: "inherit",
+            shell: process.env.ComSpec,
+          });
+
+          execSync("npm install -D nodemon", {
+            cwd: serverPath,
+            stdio: "inherit",
+            shell: process.env.ComSpec,
+          });
         }
 
-        execSync("npm install express cors dotenv", {
-          cwd: serverPath,
-          stdio: "inherit",
-          shell: process.env.ComSpec,
-        });
+        if (pm === "yarn") {
+          execSync("yarn add express cors dotenv", {
+            cwd: serverPath,
+            stdio: "inherit",
+            shell: process.env.ComSpec,
+          });
+
+          execSync("yarn add -D nodemon", {
+            cwd: serverPath,
+            stdio: "inherit",
+            shell: process.env.ComSpec,
+          });
+        }
 
-        execSync("npm install -D nodemon", {
-          cwd: serverPath,
-          stdio: "inherit",
-          shell: process.env.ComSpec,
-        });
+        if (pm === "pnpm") {
+          execSync("pnpm add express cors dotenv", {
+            cwd: serverPath,
+            stdio: "inherit",
+            shell: process.env.ComSpec,
+          });
+
+          execSync("pnpm add -D nodemon", {
+            cwd: serverPath,
+            stdio: "inherit",
+            shell: process.env.ComSpec,
+          });
+        }
 
         copyTemplate(
           path.join(__dirname, "..", "templates", "server", "index.js"),
           path.join(serverPath, "index.js")
         );
+
+        fs.writeFileSync(
+          path.join(serverPath, ".env"),
+          `PORT=${answers.port}`
+        );
       } catch (error) {
         console.log("\n❌ Backend setup failed.");
-        console.log("Check npm installation or internet connection.");
+        console.log("Check package manager installation or internet connection.");
         return;
       }
     }
 
     // =====================================================
-    // FRONTEND SETUP - HTML / CSS / JS
+    // HTML FRONTEND
     // =====================================================
     if (answers.frontend === "HTML / CSS / JavaScript") {
       const clientPath = path.join(projectPath, "client");
@@ -267,10 +418,14 @@ inquirer
       );
 
       if (answers.backend === "Node.js (Express)") {
-        copyTemplate(
+        let script = fs.readFileSync(
           path.join(__dirname, "..", "templates", "html", "script.js"),
-          path.join(clientPath, "script.js")
+          "utf8"
         );
+
+        script = script.replace(/5000/g, answers.port);
+
+        fs.writeFileSync(path.join(clientPath, "script.js"), script);
       } else {
         fs.writeFileSync(
           path.join(clientPath, "script.js"),
@@ -286,7 +441,7 @@ messageEl.textContent = "No backend selected. Frontend is ready.";`
     }
 
     // =====================================================
-    // FRONTEND SETUP - REACT
+    // REACT FRONTEND
     // =====================================================
     else if (answers.frontend === "React.js (Vite)") {
       const clientPath = path.join(projectPath, "client");
@@ -308,13 +463,15 @@ messageEl.textContent = "No backend selected. Frontend is ready.";`
           shell: process.env.ComSpec,
         });
 
-        console.log("✅ React installation complete!");
-
         if (answers.backend === "Node.js (Express)") {
-          copyTemplate(
+          let appCode = fs.readFileSync(
             path.join(__dirname, "..", "templates", "react", "App.jsx"),
-            path.join(clientPath, "src", "App.jsx")
+            "utf8"
           );
+
+          appCode = appCode.replace(/5000/g, answers.port);
+
+          fs.writeFileSync(path.join(clientPath, "src", "App.jsx"), appCode);
         }
       } catch (error) {
         console.log("\n❌ React setup failed.");
@@ -324,7 +481,7 @@ messageEl.textContent = "No backend selected. Frontend is ready.";`
     }
 
     // =====================================================
-    // FINAL INSTRUCTIONS
+    // FINAL
     // =====================================================
     console.log(`\n✅ Project "${answers.projectName}" created successfully!`);
 
@@ -334,7 +491,7 @@ messageEl.textContent = "No backend selected. Frontend is ready.";`
     ) {
       console.log("\nRun backend:");
       console.log(`cd ${answers.projectName}/server`);
-      console.log("npm run dev");
+      console.log(`${answers.packageManager} run dev`);
 
       console.log("\nThen open frontend:");
       console.log(`${answers.projectName}/client/index.html`);
@@ -344,7 +501,7 @@ messageEl.textContent = "No backend selected. Frontend is ready.";`
     ) {
       console.log("\nRun backend:");
       console.log(`cd ${answers.projectName}/server`);
-      console.log("npm run dev");
+      console.log(`${answers.packageManager} run dev`);
 
       console.log("\nOpen another terminal and run frontend:");
       console.log(`cd ${answers.projectName}/client`);
@@ -359,6 +516,6 @@ messageEl.textContent = "No backend selected. Frontend is ready.";`
     } else if (answers.backend === "Node.js (Express)") {
       console.log("\nRun backend:");
       console.log(`cd ${answers.projectName}/server`);
-      console.log("npm run dev");
+      console.log(`${answers.packageManager} run dev`);
     }
-  });
+  });

package/package.json

@@ -1,30 +1,43 @@
 {
   "name": "stack-starter-cli",
-  "version": "1.0.0",
-  "description": "CLI to generate frontend and backend starter projects",
+  "version": "1.1.0",
+  "description": "CLI tool to quickly scaffold HTML, React, and Node.js starter projects.",
   "main": "bin/index.js",
   "bin": {
     "stack-starter": "./bin/index.js"
   },
   "files": [
     "bin",
-    "templates"
+    "templates",
+    "README.md"
   ],
   "scripts": {
     "start": "node bin/index.js"
   },
   "keywords": [
     "cli",
-    "starter",
     "scaffold",
-    "node",
+    "starter",
+    "boilerplate",
+    "fullstack",
+    "frontend",
+    "backend",
     "react",
-    "express"
+    "vite",
+    "express",
+    "node"
   ],
   "author": "SACHITH KASA",
   "license": "MIT",
   "type": "commonjs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SACHITH31/starter_cli"
+  },
+  "engines": {
+    "node": ">=18"
+  },
   "dependencies": {
     "inquirer": "^13.4.2"
   }
-}
+}