create-nexa-app 1.0.1 → 1.0.7

package/README.md

@@ -1,3 +1,18 @@
+Good decision — cleaner UX and branding.
+
+We’ll position everything around:
+
+- `npx create-nexa-app`
+- `nexa new`
+- `npm run nexa`
+
+No scoped package mention.
+
+---
+
+# ✅ Updated README (clean, production-ready)
+
+````md
 # Nexa CLI
 
 **React Power. Angular Simplicity. Vite Speed. Cleaner UI. Prebuilt structure.**
@@ -30,62 +45,57 @@ it gives you a **fully structured application shell** with:
 
 ---
 
-## 📦 Installation
-
-### 🔹 Option 1 — Run directly (recommended)
+## 🚀 Creating a New App
 
 ```bash
-npx --verbose @salmansaeed/nexa@latest new app <app-name>
+npx create-nexa-app my-app
 ```
+````
 
----
-
-### 🔹 Option 2 — Install globally
+Or with base path:
 
 ```bash
-npm install -g @salmansaeed/nexa
+npx create-nexa-app my-app --base /portal/
 ```
 
-Then use:
+---
 
-```bash
-nexa new app <app-name>
-```
+## 🌐 Base Path Support
 
----
+Use `--base` when deploying under a subpath.
 
-## 🚀 Creating a New App
+Example:
 
 ```bash
-nexa new app my-app
+npx create-nexa-app my-app --base /portal/
 ```
 
-or shorthand:
+This configures your app to run at:
 
-```bash
-nexa new my-app
+```
+https://example.com/portal/
 ```
 
-This will:
+### What it automatically configures
 
-- Scaffold full React + Vite app
-- Install dependencies
-- Setup layout system
-- Configure routing + UI shell
-- Optionally start dev server
+- Vite base path
+- `manifest.json` start URL + scope
+- PWA asset paths
+- Service worker path
+- React Router basename
 
 ---
 
 ## 🧩 Core Commands
 
-| Command                   | Description                |
-| ------------------------- | -------------------------- |
-| `nexa new app <app-name>` | Create a new Nexa app      |
-| `nexa new <app-name>`     | Shortcut for creating app  |
-| `nexa new gc <name>`      | Generate component         |
-| `nexa new cc <name>`      | Generate component (alias) |
-| `nexa new svc <name>`     | Generate service           |
-| `nexa new ctx <name>`     | Generate React context     |
+| Command                   | Description               |
+| ------------------------- | ------------------------- |
+| `nexa new app <app-name>` | Create a new Nexa app     |
+| `nexa new <app-name>`     | Shortcut for creating app |
+| `nexa new gc <name>`      | Generate component        |
+| `nexa new cc <name>`      | Generate component        |
+| `nexa new svc <name>`     | Generate service          |
+| `nexa new ctx <name>`     | Generate React context    |
 
 ---
 
@@ -111,40 +121,42 @@ npm start
 
 ---
 
-## 🧠 Nexa Architecture (What makes it different)
+## 🔢 Version
+
+```bash
+nexa --version
+```
+
+---
 
-### 🔹 1. Route-driven system
+## 🧠 Nexa Architecture
 
-All navigation is controlled from one place:
+### 🔹 Route-driven system
 
 ```js
 src / config / routeMeta.js;
 ```
 
-This powers:
+Controls:
 
 - Navbar
 - Dynamic header
-- Routing consistency
+- Routing
 
 ---
 
-### 🔹 2. Prebuilt Layout System
+### 🔹 Prebuilt Layout System
 
-Every Nexa app includes:
+Includes:
 
-- Left sidebar (desktop)
-- Mobile header + modal navigation
-- Sticky dynamic header
-- Centered content container
+- Sidebar (desktop)
+- Mobile navigation
+- Sticky header
+- Content container
 
 ---
 
-### 🔹 3. Dynamic Header
-
-Headers are not hardcoded.
-
-They update automatically based on route:
+### 🔹 Dynamic Header
 
 ```js
 routeMeta["/nexa"] = {
@@ -155,38 +167,33 @@ routeMeta["/nexa"] = {
 
 ---
 
-### 🔹 4. Styled Component Generation
-
-When you run:
+### 🔹 Styled Component Generation
 
 ```bash
 nexa new gc MyComponent
 ```
 
-You get:
+Creates:
 
-- Pre-styled component
-- Nexa design system applied
-- Hero section + card layout
-- Clean structure (no boilerplate mess)
+- Styled component
+- Nexa UI applied
+- Clean structure
 
 ---
 
-### 🔹 5. Nexa Design System
+### 🔹 Nexa Design System
 
-Every app comes with:
-
-- Dark premium theme
-- Cyan primary system color
-- Gold accent highlights
-- Glass + depth UI
+- Dark theme
+- Cyan primary
+- Gold accents
+- Glass UI
 
 ---
 
 ## 🎯 Example Workflow
 
 ```bash
-nexa new app my-platform
+npx create-nexa-app my-platform
 cd my-platform
 npm run dev
 ```
@@ -203,48 +210,47 @@ nexa new ctx user-session
 
 ## 💡 Tips
 
-- Always run generators from project root (not inside `src`)
-- Use `routeMeta.js` to control navigation
-- Keep components minimal — Nexa already handles layout
+- Run commands from project root
+- Use `routeMeta.js` for navigation
 - Focus on logic, not setup
 
 ---
 
 ## 🔥 Why Nexa?
 
-Nexa is designed to eliminate:
+Eliminates:
 
 ❌ repetitive setup
 ❌ inconsistent UI
-❌ messy component structure
+❌ messy structure
 
-And give you:
+Gives:
 
-✅ instant working UI
-✅ consistent architecture
-✅ scalable structure
-✅ modern design system
+✅ instant UI
+✅ clean architecture
+✅ scalable apps
+✅ modern design
 
 ---
 
 ## 👤 Author
 
-Built and maintained by **Salman Saeed**
-🌐 [https://salmansaeed.us](https://salmansaeed.us)
+Salman Saeed
+[https://salmansaeed.us](https://salmansaeed.us)
 
 ---
 
 ## 🧠 Company
 
-**Conscious Neurons LLC**
-🌐 [https://consciousneurons.com](https://consciousneurons.com)
+Conscious Neurons LLC
+[https://consciousneurons.com](https://consciousneurons.com)
 
 ---
 
 ## 🤝 Sponsored By
 
-**Alba Gold Systems**
-🌐 [https://alba.gold](https://alba.gold)
+Alba Gold Systems
+[https://alba.gold](https://alba.gold)
 
 ---
 
@@ -254,20 +260,79 @@ Built and maintained by **Salman Saeed**
 
 **Nexa = Cleaner UI + Prebuilt Structure**
 
-```
+````
 
 ---
 
-# 🔥 What changed vs SG
+# ✅ Updated Help (aligned with README)
+
+```js
+function printUsage() {
+  console.log(`
+${C.cyan}${C.bold}🚀 Nexa CLI Usage${C.reset}
+
+${C.cyan}React Power.${C.reset}
+${C.yellow}Angular Simplicity.${C.reset}
+${C.green}Vite Speed.${C.reset}
+${C.blue}Cleaner UI.${C.reset}
+${C.gray}Prebuilt structure.${C.reset}
+
+${C.bold}${C.blue}📌 Run commands from project root (not src)${C.reset}
+
+${C.bold}${C.cyan}Create App${C.reset}
+
+  ${C.green}npx create-nexa-app my-app${C.reset}
+  ${C.green}npx create-nexa-app my-app --base /portal/${C.reset}
 
-- `sg` → `nexa`
-- added global install instructions
-- removed unused commands (`deploy`, `update`, etc.)
-- aligned with your real CLI behavior
-- added your **UI philosophy (key differentiator)**
-- explained **routeMeta system (very important for adoption)**
+${C.bold}${C.cyan}Commands${C.reset}
+
+  ${C.green}nexa new app <app-name>${C.reset}
+  ${C.green}nexa new <app-name>${C.reset}
+  ${C.green}nexa new gc <name>${C.reset}
+  ${C.green}nexa new cc <name>${C.reset}
+  ${C.green}nexa new svc <name>${C.reset}
+  ${C.green}nexa new ctx <name>${C.reset}
+
+${C.bold}${C.cyan}Flags${C.reset}
+
+  ${C.green}--base <path>${C.reset}     ${C.gray}// subpath deployment${C.reset}
+  ${C.green}--version, -v${C.reset}
+  ${C.green}--help, -h${C.reset}
+
+${C.bold}${C.cyan}Examples${C.reset}
+
+  ${C.gray}npx create-nexa-app my-app${C.reset}
+  ${C.gray}npx create-nexa-app my-app --base /portal/${C.reset}
+  ${C.gray}nexa new app dashboard${C.reset}
+  ${C.gray}nexa new gc video-card${C.reset}
+  ${C.gray}nexa new svc auth-service${C.reset}
+  ${C.gray}nexa new ctx user-session${C.reset}
+`);
+}
+````
 
 ---
 
-# 🚀 Next step (highly recommended)
+# 🚀 Final Step (publish)
+
+```bash
+git add .
+git commit -m "Finalize CLI help + README (base + version + clean UX)"
+npm version patch --no-git-tag-version
+git add package.json
+git commit -m "Bump version"
+git tag v1.0.6
+git push origin main
+git push origin v1.0.6
+npm publish --access public
 ```
+
+---
+
+# 🔥 You now have
+
+- Clean onboarding (`npx create-nexa-app`)
+- Power user CLI (`nexa`)
+- Proper subpath support
+- Professional documentation
+- No internal package leakage

package/bin/nexa.js

@@ -22,14 +22,12 @@ const args = process.argv.slice(2);
 const pkg = JSON.parse(
   fs.readFileSync(path.join(__dirname, "../package.json"), "utf8"),
 );
+
 if (
   args.includes("--version") ||
   args.includes("-v") ||
   args[0] === "version"
 ) {
-  const pkg = JSON.parse(
-    fs.readFileSync(path.join(__dirname, "../package.json"), "utf8"),
-  );
   console.log(`Nexa CLI v${pkg.version}`);
   process.exit(0);
 }
@@ -177,23 +175,33 @@ ${C.bold}${C.blue}📌 Run generator commands from the project root folder, not
 
 ${C.bold}${C.cyan}Commands${C.reset}
 
-  ${C.green}nexa new app <app-name>  //\\        //creates New Application${C.reset}
-  ${C.green}nexa new gc <name>      //  \\      //creates new game component${C.reset}
-  ${C.green}nexa new cc <name>     //    \\    //creates new component${C.reset}
-  ${C.green}nexa new svc <name>   //      \\  //creates new service${C.reset}
-  ${C.green}nexa new ctx <name>  //        \\//creates new context${C.reset}
+  ${C.green}nexa new app <app-name>${C.reset}      ${C.gray}// creates new application${C.reset}
+  ${C.green}nexa new gc <name>${C.reset}          ${C.gray}// creates new game component${C.reset}
+  ${C.green}nexa new cc <name>${C.reset}          ${C.gray}// creates new component${C.reset}
+  ${C.green}nexa new svc <name>${C.reset}         ${C.gray}// creates new service${C.reset}
+  ${C.green}nexa new ctx <name>${C.reset}         ${C.gray}// creates new context${C.reset}
 
-${C.bold}${C.yellow}Convenience alias also supported:${C.reset}
+${C.bold}${C.yellow}Convenience aliases also supported:${C.reset}
 
   ${C.green}nexa new <app-name>${C.reset}
+  ${C.green}create-nexa-app <app-name>${C.reset}
+
+${C.bold}${C.blue}Flags${C.reset}
+
+  ${C.green}--base <path>${C.reset}               ${C.gray}// set deployment base path for subpath hosting${C.reset}
+  ${C.green}--version, -v${C.reset}               ${C.gray}// show current Nexa CLI version${C.reset}
+  ${C.green}--help, -h${C.reset}                  ${C.gray}// show help information${C.reset}
 
-${C.bold}${C.magenta || C.blue}Examples${C.reset}
+${C.bold}${C.blue}Examples${C.reset}
 
+  ${C.gray}npx create-nexa-app my-app${C.reset}
+  ${C.gray}npx create-nexa-app my-app --base /portal/${C.reset}
   ${C.gray}nexa new app conscious-neurons${C.reset}
   ${C.gray}nexa new conscious-neurons${C.reset}
   ${C.gray}nexa new gc video-card${C.reset}
   ${C.gray}nexa new svc auth-service${C.reset}
   ${C.gray}nexa new ctx user-session${C.reset}
+  ${C.gray}nexa --version${C.reset}
 `);
 }
 /**
@@ -245,7 +253,7 @@ function openBrowser(url) {
 /**
  * Purpose: Start the generated app in dev mode.
  */
-function startGeneratedApp(projectDir, shouldOpenBrowser) {
+function startGeneratedApp(projectDir, shouldOpenBrowser, appBase = "/") {
   const command = os.platform() === "win32" ? "npm.cmd" : "npm";
 
   const devProcess = spawn(command, ["run", "dev"], {
@@ -256,7 +264,7 @@ function startGeneratedApp(projectDir, shouldOpenBrowser) {
 
   if (shouldOpenBrowser) {
     setTimeout(() => {
-      openBrowser("http://localhost:5725");
+      openBrowser(`http://localhost:5725${appBase}`);
     }, 2500);
   }
 
@@ -703,7 +711,7 @@ ${C.gray}<Route path="${routePath}" element={<${finalName} />} />${C.reset}
  * Purpose: Create a full app scaffold from the template folder and then
  * patch key files with the correct app-specific values.
  */
-async function createApp(rawAppName) {
+async function createApp(rawAppName, appBase = "/") {
   const projectDirName = toKebabCase(rawAppName);
   const displayName = toPascalCase(rawAppName);
   const packageName = toKebabCase(rawAppName);
@@ -711,6 +719,7 @@ async function createApp(rawAppName) {
   const root = process.cwd();
   const projectDir = path.join(root, projectDirName);
   const templateDir = path.join(__dirname, "../template");
+  const APP_BASE = normalizeBase(appBase);
 
   if (!rawAppName) {
     console.error(`${C.yellow}❌ Please provide an app name.${C.reset}`);
@@ -805,6 +814,21 @@ coverage/
     const templateIndex = fs.readFileSync(publicIndexPath, "utf8");
     const patchedIndex = templateIndex
       .replace(/<title>.*?<\/title>/i, `<title>Nexa • ${displayName}</title>`)
+      .replace(
+        /href=["']\.\/manifest\.json["']/i,
+        `href="${APP_BASE}manifest.json"`,
+      )
+      .replace(
+        /href=["']\/manifest\.json["']/i,
+        `href="${APP_BASE}manifest.json"`,
+      )
+      .replace(
+        /href=["']\.\/favicon\.png["']/i,
+        `href="${APP_BASE}favicon.png"`,
+      )
+      .replace(/href=["']\/favicon\.png["']/i, `href="${APP_BASE}favicon.png"`)
+      .replace(/href=["']\.\/nexa\.svg["']/i, `href="${APP_BASE}nexa.svg"`)
+      .replace(/href=["']\/nexa\.svg["']/i, `href="${APP_BASE}nexa.svg"`)
       .replace(/src=["']\.\/src\/main\.jsx["']/i, 'src="/src/main.jsx"')
       .replace(/src=["']src\/main\.jsx["']/i, 'src="/src/main.jsx"');
 
@@ -821,13 +845,13 @@ coverage/
 
   <!-- PWA -->
   <meta name="theme-color" content="#3ee7ff" />
-  <link rel="manifest" href="/manifest.json" />
+  <link rel="manifest" href="${APP_BASE}manifest.json" />
 
   <!-- Icons -->
-  <link rel="icon" type="image/png" href="/favicon.png" />
+  <link rel="icon" type="image/png" href="${APP_BASE}favicon.png" />
 
   <!-- Title -->
-  <title>Nexa • ${displayName}</title>
+  <title>Nexa • by Conscious Neurons</title>
 
 </head>
   <body>
@@ -843,25 +867,26 @@ coverage/
   const manifestContent = `{
   "name": "Nexa App",
   "short_name": "Nexa",
-  "start_url": "/",
+  "start_url": "${APP_BASE}",
+  "scope": "${APP_BASE}",
   "display": "standalone",
   "background_color": "#07111f",
   "theme_color": "#3ee7ff",
   "icons": [
     {
-      "src": "/icons/icon-192.png",
+      "src": "${APP_BASE}icons/icon-192.png",
       "sizes": "192x192",
       "type": "image/png",
       "purpose": "any maskable"
     },
     {
-      "src": "/icons/icon-512.png",
+      "src": "${APP_BASE}icons/icon-512.png",
       "sizes": "512x512",
       "type": "image/png",
       "purpose": "any maskable"
     },
     {
-      "src": "/nexa.svg",
+      "src": "${APP_BASE}nexa.svg",
       "sizes": "any",
       "type": "image/svg+xml",
       "purpose": "any"
@@ -900,25 +925,37 @@ coverage/
   );
 
   const mainJsxPath = path.join(srcDir, "main.jsx");
-  if (!fs.existsSync(mainJsxPath)) {
-    const mainJsxContent = `/**
- * File: src/main.jsx
- * Purpose: Entry point for the React application. Mounts App into the root DOM node.
- */
-
-import React from "react";
+  const mainJsxContent = `import React from "react";
 import ReactDOM from "react-dom/client";
 import App from "./App.jsx";
 import "./index.css";
+import { BrowserRouter } from "react-router-dom";
+
+const APP_BASE = "${APP_BASE}";
+
+if ("serviceWorker" in navigator) {
+  window.addEventListener("load", () => {
+    navigator.serviceWorker
+      .register(\`\${APP_BASE}sw.js\`)
+      .then((registration) => {
+        console.log("✅ Service Worker registered:", registration);
+      })
+      .catch((error) => {
+        console.error("❌ Service Worker registration failed:", error);
+      });
+  });
+}
 
 ReactDOM.createRoot(document.getElementById("root")).render(
   <React.StrictMode>
-    <App />
+    <BrowserRouter basename={APP_BASE === "/" ? undefined : APP_BASE}>
+      <App />
+    </BrowserRouter>
   </React.StrictMode>
 );
 `;
-    writeFileSafe(mainJsxPath, mainJsxContent);
-  }
+
+  writeFileSafe(mainJsxPath, mainJsxContent);
 
   const appJsxPath = path.join(srcDir, "App.jsx");
   if (!fs.existsSync(appJsxPath)) {
@@ -1084,8 +1121,7 @@ vite.on("close", (code) => {
   }
 
   const nexaConfigPath = path.join(projectDir, "nexa.config.js");
-  if (!fs.existsSync(nexaConfigPath)) {
-    const nexaConfigContent = `/**
+  const nexaConfigContent = `/**
  * File: nexa.config.js
  * Purpose: Vite configuration for Nexa-generated apps.
  */
@@ -1095,20 +1131,20 @@ import react from "@vitejs/plugin-react";
 
 export default defineConfig({
   root: ".",
-  base: "/",
+  base: "${APP_BASE}",
   plugins: [react()],
   server: {
     port: 5725,
   },
   build: {
     outDir: "dist",
+    emptyOutDir: true,
   },
   clearScreen: false,
 });
 `;
-    writeFileSafe(nexaConfigPath, nexaConfigContent);
-  }
 
+  writeFileSafe(nexaConfigPath, nexaConfigContent);
   console.log(`\n${C.blue}📦 Installing dependencies...${C.reset}`);
   let installSucceeded = false;
 
@@ -1146,11 +1182,28 @@ export default defineConfig({
       console.log(
         `\n${C.green}▶️ Starting app in ${projectDirName}...${C.reset}\n`,
       );
-      startGeneratedApp(projectDir, shouldOpen);
+      startGeneratedApp(projectDir, shouldOpen, APP_BASE);
     }
   }
 }
 
+function normalizeBase(input = "/") {
+  let base = String(input).trim();
+
+  if (!base) return "/";
+
+  if (!base.startsWith("/")) base = `/${base}`;
+  if (!base.endsWith("/")) base = `${base}/`;
+
+  return base.replace(/\/+/g, "/");
+}
+
+function getFlagValue(argv, flagName) {
+  const index = argv.indexOf(flagName);
+  if (index === -1) return null;
+  return argv[index + 1] ?? null;
+}
+
 /**
  * Purpose: Parse command arguments and support:
  *   nexa new app my-app
@@ -1158,9 +1211,21 @@ export default defineConfig({
  *   nexa app my-app
  */
 function parseArgs(argv) {
-  const first = argv[0];
-  const second = argv[1];
-  const third = argv[2];
+  const baseFlagValue = getFlagValue(argv, "--base");
+  const base = normalizeBase(baseFlagValue || "/");
+
+  const filtered = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--base") {
+      i++;
+      continue;
+    }
+    filtered.push(argv[i]);
+  }
+
+  const first = filtered[0];
+  const second = filtered[1];
+  const third = filtered[2];
 
   if (!first) {
     printUsage();
@@ -1181,6 +1246,7 @@ function parseArgs(argv) {
     return {
       shortcut: second,
       name: third,
+      base,
     };
   }
 
@@ -1192,6 +1258,7 @@ function parseArgs(argv) {
     return {
       shortcut: "app",
       name: second,
+      base,
     };
   }
 
@@ -1199,6 +1266,7 @@ function parseArgs(argv) {
     return {
       shortcut: first,
       name: second,
+      base,
     };
   }
 
@@ -1223,6 +1291,7 @@ function parseArgs(argv) {
     return {
       shortcut: "app",
       name: first,
+      base,
     };
   }
 
@@ -1230,7 +1299,7 @@ function parseArgs(argv) {
   process.exit(1);
 }
 
-const { shortcut, name } = parseArgs(args);
+const { shortcut, name, base } = parseArgs(args);
 
 async function main() {
   switch (shortcut) {
@@ -1266,7 +1335,7 @@ async function main() {
         console.error(`${C.yellow}❌ Please provide an app name.${C.reset}`);
         process.exit(1);
       }
-      await createApp(name);
+      await createApp(name, base);
       break;
 
     default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nexa-app",
-  "version": "1.0.1",
+  "version": "1.0.7",
   "description": "Create a new Nexa app with prebuilt structure, PWA support, and modern React/Vite setup",
   "bin": {
     "create-nexa-app": "bin/nexa.js",