@meghpatel-007/next-starter 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2025 ShadcnStore
+Copyright (c) 2026 Megh Patel
+
+The dashboard code included in this package's template/ directory is derived from
+shadcn-dashboard-landing-template by ShadcnStore, published under the MIT License
+(https://github.com/shadcnstore/shadcn-dashboard-landing-template). Megh Patel's
+copyright covers the CLI scaffolding tool and modifications to the template.
+
+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

@@ -1,3 +1,132 @@
-# Temporary Holding Version
+# @meghpatel-007/next-starter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A modern Next.js dashboard starter with shadcn/ui, TypeScript, and Tailwind CSS — scaffolded from one command.
+
+```bash
+npx @meghpatel-007/next-starter my-app
+```
+
+Creates a complete, independently installable Next.js 16 project: app router, dashboard pages, auth page layouts, theme customizer, landing page, and a full shadcn/ui component set.
+
+## Screenshots
+
+Light and dark dashboards, plus landing-page previews (hosted in the repo):
+
+- [Dark dashboard](https://github.com/MeghPatel-007/Next-starter/raw/main/template/public/dashboard.png)
+- [Light dashboard](https://github.com/MeghPatel-007/Next-starter/raw/main/template/public/dashboard-light.png)
+- [Dashboard 2](https://github.com/MeghPatel-007/Next-starter/raw/main/template/public/dashboard-dark.png)
+
+## Requirements
+
+- Node.js **20.12 or newer** (`node --version`)
+- Optional: Git for repo initialization, and npm/pnpm/Bun for dependency installation
+
+## Usage
+
+```bash
+# npm
+npx @meghpatel-007/next-starter my-app
+
+# pnpm
+pnpm dlx @meghpatel-007/next-starter my-app
+
+# Bun
+bunx @meghpatel-007/next-starter my-app
+```
+
+Interactive setup asks three questions when not passed as flags:
+
+1. Whether to install dependencies (default: yes).
+2. Which package manager to use — npm, pnpm, or Bun. Your choice is pre-selected when it matches the runner (`npx` → npm, `pnpm dlx` → pnpm, `bunx` → Bun).
+3. Whether to initialize a Git repository (default: yes, `git init` only — no auto commit).
+
+Non-interactive use:
+
+```bash
+npx @meghpatel-007/next-starter my-app --no-install --no-git
+npx @meghpatel-007/next-starter my-app --install --pm pnpm --git
+```
+
+Full options:
+
+```text
+--pm <npm|pnpm|bun>       install dependencies with this package manager
+--install / --no-install  install template dependencies
+--git / --no-git          initialize a Git repository
+--version, -v
+--help, -h
+```
+
+Project names must be valid npm package names (lowercase, no spaces, no leading dot/underscore, scoped names like `@acme/my-app` are allowed). Invalid names are rejected with a reason; they are never silently rewritten.
+
+## Destination rules
+
+- The project is created inside your current working directory.
+- An existing non-empty directory is **never** overwritten or deleted.
+- Interrupted runs leave partial files behind; delete the folder yourself to retry.
+
+## Generated project structure
+
+```text
+my-app/
+├── src/
+│   ├── app/                 # App Router: landing, (auth), (dashboard) route groups
+│   ├── components/          # shadcn/ui components, theme customizer, app sidebar
+│   ├── components/ui/       # shadcn primitives (button, chart, dialog, …)
+│   ├── config/              # site branding (src/config/site.ts) + theme data
+│   ├── contexts/ hooks/ lib/ types/ utils/
+│   └── proxy.ts             # middleware-style proxy (redirects /login, /register, /auth/*)
+├── public/                  # demo images and favicon
+├── components.json          # shadcn/ui configuration
+├── next.config.ts · tsconfig.json · eslint.config.mjs · postcss.config.mjs
+├── package.json             # renamed to your project name; template deps intact
+└── .gitignore
+```
+
+## Development commands (inside the generated project)
+
+```bash
+npm run dev        # or: pnpm dev / bun dev
+npm run build      # production build (Next.js 16 + Turbopack)
+npm run start      # serve the production build
+npm run lint       # ESLint
+```
+
+## What's included
+
+- **Dashboards**: two dashboard layouts with charts, data tables, and stat cards
+- **Pages**: tasks, users, calendar, chat, mail, settings (account/appearance/billing/connections/notifications), pricing, FAQs
+- **Auth pages**: three sign-in, sign-up, and forgot-password layouts plus error pages (forbidden, not-found, unauthorized, maintenance)
+- **Landing page**: hero, features, pricing, testimonials, FAQ, contact, CTA
+- **Theme system**: dark/light mode, sidebar themes, a theme customizer with preset palettes
+
+All dashboard/chat/mail/user data behind these pages is **local JSON mock data** — no backend, no real authentication, and the sign-in/sign-up pages are layout demos only, not working integrations.
+
+## Technology stack
+
+- Next.js 16 (App Router, Turbopack), React 19.3
+- Tailwind CSS 4 · shadcn/ui (base-nova style) · lucide-react icons
+- TypeScript, ESLint, PostCSS
+- @tanstack/react-table, recharts, react-hook-form + zod, @dnd-kit, zustand
+
+## Customization
+
+- Brand name, repo links and description: edit `src/config/site.ts` in the generated project.
+- Colors/typography: `src/app/globals.css` and the theme presets in `src/utils/*-theme-presets.ts`.
+- Sidebar items: `src/contexts/sidebar-config.ts`.
+- Layouts and page content: `src/app/**` — plain React code, no hidden generators.
+
+## License and attribution
+
+MIT. The template derives from [shadcn-dashboard-landing-template](https://github.com/shadcnstore/shadcn-dashboard-landing-template) by ShadcnStore (MIT, © 2025); the CLI tooling and template modifications are © 2026 Megh Patel. The upstream [License.md](https://github.com/shadcnstore/shadcn-dashboard-landing-template/blob/main/License.md) is preserved in each generated project.
+
+## Contributing
+
+Issues and pull requests are welcome at the [repository](https://github.com/MeghPatel-007/Next-starter). For local development: `npm test` runs the package verification suite (CLI startup, name/destination validation, a full scaffold into a temp folder, tarball inspection, and a packed-tarball run).
+
+## Known limitations
+
+- Windows, macOS, and Linux are supported; the template itself is tested on Windows 11 with Node 24.
+- Git initialization requires the `git` CLI on `PATH`.
+- The bundled Bun/pnpm/npm lockfiles are deliberately absent — the first install in your project produces its own lockfile.
+- Demo integrations (chat, mail, notifications, reports) run entirely on mock data.

package/bin/index.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { runCli } from "../src/cli.js";
+import process from "node:process";
+
+runCli().catch((error) => {
+  console.error(error?.message ?? error);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@meghpatel-007/next-starter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "A modern Next.js dashboard starter with shadcn/ui, TypeScript and Tailwind CSS, scaffolded straight into your project.",
+  "keywords": [
+    "nextjs",
+    "react",
+    "dashboard",
+    "shadcn",
+    "shadcn-ui",
+    "typescript",
+    "tailwindcss",
+    "starter-template",
+    "create-next-app"
+  ],
+  "homepage": "https://github.com/MeghPatel-007/Next-starter#readme",
+  "bugs": {
+    "url": "https://github.com/MeghPatel-007/Next-starter/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MeghPatel-007/Next-starter.git"
+  },
+  "license": "MIT",
+  "author": "Megh Patel",
+  "type": "module",
+  "bin": {
+    "next-starter": "bin/index.js"
+  },
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "template/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node scripts/verify-package.js"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1"
+  }
+}

package/src/cli.js

@@ -0,0 +1,242 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import process from "node:process";
+import * as clack from "@clack/prompts";
+import { validateProjectName } from "./utils.js";
+import {
+  assertFreshDestination,
+  applyProjectName,
+  copyTemplate,
+  restoreGitignore,
+} from "./scaffold.js";
+import {
+  PACKAGE_MANAGERS,
+  isPackageManagerAvailable,
+  installDependencies,
+  devCommand,
+} from "./install.js";
+import { initGit, gitInitInstructions } from "./git.js";
+
+const PACKAGE_ROOT = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
+
+async function getVersion() {
+  const pkg = JSON.parse(await fs.readFile(path.join(PACKAGE_ROOT, "package.json"), "utf8"));
+  return pkg.version;
+}
+
+const usage = `
+Usage: npx @meghpatel-007/next-starter <project-name> [options]
+
+Options:
+  --pm <npm|pnpm|bun>         Install dependencies with this package manager
+  --install / --no-install    Install template dependencies (default: ask)
+  --git / --no-git            Initialize a Git repository (default: ask)
+  --version, -v               Print version
+  --help, -h                  Print this help
+`.trim();
+
+function parseArgs(argv) {
+  const args = { name: null, pm: null, install: null, git: null, help: false, version: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case "help":
+      case "--help":
+      case "-h":
+        args.help = true;
+        break;
+      case "version":
+      case "--version":
+      case "-v":
+        args.version = true;
+        break;
+      case "--pm": {
+        const value = argv[++i];
+        if (!value || !PACKAGE_MANAGERS.includes(value)) {
+          throw new Error(`--pm expects one of: ${PACKAGE_MANAGERS.join(", ")}`);
+        }
+        args.pm = value;
+        break;
+      }
+      case "--install":
+        args.install = true;
+        break;
+      case "--no-install":
+        args.install = false;
+        break;
+      case "--git":
+        args.git = true;
+        break;
+      case "--no-git":
+        args.git = false;
+        break;
+      default:
+        if (arg.startsWith("--")) throw new Error(`Unknown option: ${arg}\n\n${usage}`);
+        if (args.name !== null) throw new Error(`Unexpected argument: ${arg}\n\n${usage}`);
+        args.name = arg;
+    }
+  }
+  return args;
+}
+
+const PACKAGE_MANAGER_LABELS = { npm: "npm", pnpm: "pnpm", bun: "Bun" };
+
+/** Detect which package manager invoked us (npx / pnpm dlx / bunx). */
+function detectPackageManager() {
+  const userAgent = process.env.npm_config_user_agent ?? "";
+  const agent = userAgent.split(" ")[0] ?? "";
+  const match = agent.match(/^(npm|pnpm|bun)\//);
+  return match ? match[1] : null;
+}
+
+function cancelled(clack, value) {
+  if (clack.isCancel(value)) {
+    clack.cancel("Cancelled.");
+    return true;
+  }
+  return false;
+}
+
+function bail() {
+  process.exitCode = 1;
+}
+
+export async function runCli(argv = process.argv.slice(2)) {
+  let args;
+  try {
+    args = parseArgs(argv);
+  } catch (error) {
+    console.error(error.message);
+    bail();
+    return;
+  }
+
+  if (args.help) {
+    console.log(usage);
+    return;
+  }
+  if (args.version) {
+    console.log(await getVersion());
+    return;
+  }
+
+  clack.intro("next-starter");
+
+  let name = args.name;
+  if (name !== null) {
+    const invalid = validateProjectName(name);
+    if (invalid) {
+      clack.cancel(invalid);
+      bail();
+      return;
+    }
+  }
+
+  // Without a TTY we cannot ask questions; tell the user which flags to pass instead.
+  const canAsk = Boolean(process.stdout.isTTY);
+  const needsAsk = args.install === null || args.git === null || (args.install && args.pm === null);
+
+  if (name === null) {
+    if (!canAsk) {
+      clack.cancel(`No project name given.\n\n${usage}`);
+      bail();
+      return;
+    }
+    name = await clack.text({
+      message: "What should the project be called?",
+      placeholder: "my-app",
+      validate: (value) => {
+        if (!value || value.trim().length === 0) return "Project name cannot be empty.";
+        const invalid = validateProjectName(value.trim());
+        return invalid ?? undefined;
+      },
+    });
+    if (cancelled(clack, name)) return;
+    name = name.trim();
+  }
+
+  if (needsAsk && !canAsk) {
+    // Fall back to sensible defaults instead of failing: prefer the package
+    // manager whose agent launched us (npx -> npm, bunx -> bun, pnpm dlx -> pnpm).
+    if (install === true && pm === null) pm = detectPackageManager() ?? "npm";
+    if (install === null) install = true;
+    if (doGit === null) doGit = true;
+    clack.log.info("Non-interactive shell: installing with default answers.");
+  }
+
+  let install = args.install;
+  let pm = args.pm;
+  let doGit = args.git;
+
+  if (install === null) {
+    install = await clack.confirm({ message: "Install dependencies after scaffolding?", initialValue: true });
+    if (cancelled(clack, install)) return;
+  }
+  if (install && pm === null) {
+    const preferred = detectPackageManager();
+    pm = await clack.select({
+      message: "Which package manager should install dependencies?",
+      options: PACKAGE_MANAGERS.map((value) => ({
+        value,
+        label: PACKAGE_MANAGER_LABELS[value],
+        hint: value === preferred ? "detected" : undefined,
+        disabled: !isPackageManagerAvailable(value) ? "not installed" : undefined,
+      })),
+    });
+    if (cancelled(clack, pm)) return;
+  }
+  if (doGit === null) {
+    doGit = await clack.confirm({ message: "Initialize a Git repository?", initialValue: true });
+    if (cancelled(clack, doGit)) return;
+  }
+
+  let dest;
+  try {
+    dest = await assertFreshDestination(process.cwd(), name);
+  } catch (error) {
+    clack.cancel(error.message);
+    bail();
+    return;
+  }
+
+  const scaffoldSpinner = clack.spinner();
+  try {
+    scaffoldSpinner.start(`Scaffolding "${name}" from template`);
+    await copyTemplate(dest);
+    await restoreGitignore(dest);
+    await applyProjectName(dest, name);
+    scaffoldSpinner.stop("Template copied.");
+  } catch (error) {
+    scaffoldSpinner.stop("Scaffolding failed.", 1);
+    clack.cancel(error.message ?? String(error));
+    bail();
+    return;
+  }
+
+  if (doGit) {
+    if (initGit(dest)) {
+      clack.log.step("Git repository initialized.");
+    } else {
+      clack.log.warn(gitInitInstructions());
+    }
+  }
+
+  const nextSteps = [`  cd ${name}`];
+  if (install) {
+    const result = await installDependencies(dest, pm);
+    if (!result.ok) {
+      clack.log.error(result.reason);
+      nextSteps.push(`  ${pm} install`);
+      bail();
+    } else {
+      clack.log.step(`Dependencies installed with ${pm}.`);
+    }
+  } else {
+    clack.log.info("Dependencies were not installed. Run these when ready:");
+    nextSteps.push(`  ${PACKAGE_MANAGERS.map((m) => `${m} install`).join("   or   ")}`);
+  }
+  nextSteps.push(`      ${devCommand(pm ?? detectPackageManager() ?? "npm")}`, "");
+
+  clack.outro(`Project "${name}" created successfully.\n${nextSteps.join("\n")}`);
+}

package/src/git.js

@@ -0,0 +1,25 @@
+import { spawnSync } from "node:child_process";
+import process from "node:process";
+
+/**
+ * Run `git init` in the generated project. Argument arrays only - never shell
+ * string concatenation - so paths with spaces stay safe.
+ */
+export function initGit(dest) {
+  const result = spawnSync("git", ["init"], {
+    cwd: dest,
+    stdio: "inherit",
+    shell: false,
+    windowsHide: true,
+  });
+  if (result.error) {
+    return false;
+  }
+  return result.status === 0;
+}
+
+export function gitInitInstructions() {
+  return "Git was not initialized. You can do it later with:\n  cd <project>\n  git init";
+}
+
+export default { initGit };

package/src/install.js

@@ -0,0 +1,55 @@
+import { spawnSync, spawn } from "node:child_process";
+import process from "node:process";
+
+export const PACKAGE_MANAGERS = ["npm", "pnpm", "bun"];
+
+export function isPackageManagerAvailable(pm) {
+  if (!PACKAGE_MANAGERS.includes(pm)) return false;
+  // pm comes from an internal whitelist, so this string is fixed; on Windows
+  // npm/pnpm are .cmd shims which Node refuses to spawn without a shell.
+  const result = spawnSync(`${pm} --version`, {
+    stdio: "ignore",
+    encoding: "utf8",
+    shell: true,
+    windowsHide: true,
+  });
+  return !result.error && result.status === 0;
+}
+
+/** Install template dependencies. Returns { ok } or { ok:false, reason }. */
+export async function installDependencies(dest, pm) {
+  if (!PACKAGE_MANAGERS.includes(pm)) {
+    return {
+      ok: false,
+      reason: `Unknown package manager "${pm}". Supported: ${PACKAGE_MANAGERS.join(", ")}.`,
+    };
+  }
+  if (!isPackageManagerAvailable(pm)) {
+    return {
+      ok: false,
+      reason: `"${pm}" was not found on PATH. Install it, or run the install step manually.`,
+    };
+  }
+  return await new Promise((resolve) => {
+    const child = spawn(`${pm} install`, {
+      cwd: dest,
+      stdio: "inherit",
+      shell: true,
+      windowsHide: true,
+    });
+    child.on("close", (code) => {
+      if (code === 0) return resolve({ ok: true });
+      resolve({
+        ok: false,
+        reason: `"${pm} install" exited with code ${code}. The project files were kept; run "${pm} install" inside the project to retry.`,
+      });
+    });
+    child.on("error", (error) => {
+      resolve({ ok: false, reason: error.message });
+    });
+  });
+}
+
+export function devCommand(pm) {
+  return pm === "pnpm" ? "pnpm dev" : pm === "bun" ? "bun dev" : "npm run dev";
+}

package/src/scaffold.js

@@ -0,0 +1,110 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import process from "node:process";
+
+const packageRoot = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
+export const TEMPLATE_DIR = path.join(packageRoot, "template");
+
+const EXCLUDED_FILE_NAMES = new Set([
+  "bun.lock",
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+]);
+
+const EXCLUDED_DIR_NAMES = new Set([
+  "node_modules",
+  ".next",
+  ".git",
+  ".vercel",
+  "coverage",
+  ".turbo",
+  ".cache",
+]);
+
+function isExcludedFile(sourcePath) {
+  const base = path.basename(sourcePath);
+  if (base.toLowerCase().startsWith(".env")) return true;
+  // .npmignore only controls npm packaging of the shipped package
+  if (base === ".npmignore") return true;
+  if (base.endsWith(".tsbuildinfo")) return true;
+  return EXCLUDED_FILE_NAMES.has(base);
+}
+
+/**
+ * Recursively copy the template into dest, skipping build artifacts,
+ * lockfiles, dependencies, caches and local env secrets.
+ */
+export async function copyTemplate(dest) {
+  await fs.cp(TEMPLATE_DIR, dest, {
+    recursive: true,
+    filter: async (source) => {
+      if (path.relative(TEMPLATE_DIR, source) === "") return true;
+      const stat = await fs.stat(source);
+      if (stat.isDirectory()) {
+        return !EXCLUDED_DIR_NAMES.has(path.basename(source));
+      }
+      return !isExcludedFile(source);
+    },
+  });
+}
+
+/** Restore the npm-safe `_gitignore` sentinel as `.gitignore` in the generated project. */
+export async function restoreGitignore(dest) {
+  const sentinel = path.join(dest, "_gitignore");
+  const gitignore = path.join(dest, ".gitignore");
+  try {
+    const content = await fs.readFile(sentinel, "utf8");
+    await fs.writeFile(gitignore, content);
+  } catch (error) {
+    // "Running from a repo checkout": template/.gitignore is present as the real
+    // file and no _gitignore sentinel is shipped, so fs.cp already wrote .gitignore.
+    try {
+      await fs.access(gitignore);
+    } catch {
+      throw new Error("Could not restore .gitignore in the generated project.", { cause: error });
+    }
+    return;
+  }
+  await fs.rm(sentinel, { force: true });
+}
+
+/** The generated project keeps the template's deps/scripts; only its name changes. */
+export async function applyProjectName(dest, name) {
+  const pkgPath = path.join(dest, "package.json");
+  const pkg = JSON.parse(await fs.readFile(pkgPath, "utf8"));
+  pkg.name = name;
+  await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+}
+
+export async function assertFreshDestination(root, folder) {
+  const dest = path.resolve(root, folder);
+  if (path.parse(dest).root === path.normalize(dest)) {
+    throw new Error(`"${folder}" resolves to a drive root. Choose a project folder name, not a disk root.`);
+  }
+  if (dest === process.cwd()) {
+    throw new Error("Destination resolves to the current directory. Use a new folder name.");
+  }
+  let entries;
+  try {
+    entries = await fs.readdir(dest);
+  } catch (error) {
+    if (error.code === "ENOENT") return dest;
+    if (error.code === "ENOTDIR") {
+      throw new Error(`"${dest}" exists and is a file. Choose a different project name.`);
+    }
+    if (error.code === "EACCES" || error.code === "EPERM") {
+      throw new Error(
+        `Permission denied reading "${dest}". Check folder permissions or pick another location.`
+      );
+    }
+    throw error;
+  }
+  if (entries.length > 0) {
+    throw new Error(
+      `Destination "${dest}" already exists and is not empty. Refusing to overwrite existing files.`
+    );
+  }
+  return dest;
+}