create-next-style-guide 0.1.4 → 0.1.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alidanial7
+
+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,189 @@
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/nextjs/nextjs-original.svg" width="72" alt="Next.js" />
+</p>
+
+<h1 align="center">Next Style Guide</h1>
+
+<p align="center">
+  <strong>Ship an opinionated Next.js app in minutes</strong><br/>
+  App Router · route-colocated _components/ · Zod/Yup · Cursor rules · docs that match the code
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/create-next-style-guide"><img src="https://img.shields.io/npm/v/create-next-style-guide?style=for-the-badge&label=npm&color=CB3837" alt="npm" /></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node-%3E%3D20-339933?style=for-the-badge&logo=nodedotjs&logoColor=white" alt="Node" /></a>
+  <a href="https://nextjs.org/"><img src="https://img.shields.io/badge/Next.js-16-black?style=for-the-badge&logo=nextdotjs&logoColor=white" alt="Next.js" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-2ea44f?style=for-the-badge" alt="License" /></a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/pnpm-workspace-F69220?style=flat-square&logo=pnpm&logoColor=white" alt="pnpm" />
+  <a href="https://www.npmjs.com/package/create-next-style-guide"><img src="https://img.shields.io/badge/CLI-create--next--style--guide-111827?style=flat-square" alt="CLI" /></a>
+</p>
+
+---
+
+Opinionated **Next.js** scaffold CLI: lean App Router layout, feature installers, agent rules, and docs that match what you enabled.
+
+> Toggle options at create time — unused files and rules are not left behind.
+
+---
+
+## ✨ Why this template
+
+| | | |
+|:---:|:---|:---|
+| 🏗️ | **App-colocated layout** | Thin routes · `_components/` per route · shared `components/` + `lib/` |
+| 🎛️ | **Feature installers** | Flip options; prune what you did not pick |
+| 🤖 | **Agent-ready** | Slim `AGENTS.md` + glob-scoped `.cursor/rules/` |
+| 📚 | **Docs that match the code** | Generated `docs/style-guide/` |
+
+---
+
+## 🚀 Quick start
+
+```bash
+pnpm create next-style-guide
+# or
+npx create-next-style-guide@latest
+```
+
+Interactive prompts, or skip with a preset:
+
+```bash
+npx create-next-style-guide@latest my-app --yes --preset api-app
+npx create-next-style-guide@latest shop --yes --preset marketing
+npx create-next-style-guide@latest admin --yes --preset dashboard
+```
+
+### Presets
+
+| Preset | Focus |
+|:---|:---|
+| `minimal` | Base App Router only |
+| `api-app` | Tailwind · shadcn:starter · dark · JWT · Query · Zustand · endpoints · Vitest · CI |
+| `marketing` | Tailwind · shadcn:minimal · dark · SEO · i18n · Vercel · Vitest · CI |
+| `dashboard` | Tailwind · shadcn:starter · dark · Query · Zustand (no endpoints) · Vitest · CI |
+| `custom` | Answer every prompt (default in interactive mode) |
+
+---
+
+## 📦 What you get
+
+```text
+my-app/
+├── src/
+│   ├── app/                 # App Router + _components/
+│   ├── components/          # shared UI (≥2 routes)
+│   ├── lib/                 # env + helpers
+│   ├── utils/ · providers/ · hooks/ · types/ · constants/
+├── docs/style-guide/
+├── AGENTS.md
+├── .cursor/rules/
+└── …
+```
+
+### Options
+
+| | Choice |
+|:---:|:---|
+| 🎛️ | Preset: `minimal` / `api-app` / `marketing` / `dashboard` / `custom` |
+| 📦 | Package manager: `pnpm` / `npm` / `yarn` |
+| 🎨 | Styling: `none` / `tailwind` / `mui` |
+| 🧩 | shadcn (Tailwind only): `minimal` (button) / `starter` (button · input · card · dialog) |
+| ✅ | Validation: `zod` / `yup` |
+| 🔑 | Auth: `none` / `jwt` / `authjs` |
+| 🗃️ | Client store: `none` / `zustand` / `redux` |
+| 🌙 | Dark mode (Tailwind + next-themes) |
+| ✨ | Icons: `none` / `lucide` / `tabler` |
+| 📡 | TanStack Query |
+| 🔌 | OpenAPI endpoints codegen |
+| 📨 | API envelope unwrap |
+| 🔎 | SEO (public-routes, sitemap, robots) |
+| 🌐 | i18n (next-intl) |
+| 🧪 | Vitest (+ optional Playwright) |
+| 🧹 | ESLint / Prettier / Husky |
+| 🚀 | Deploy: `none` / `vercel` / `docker` |
+| 🤖 | GitHub Actions CI |
+
+Flags: `--preset`, `--pm`, `--store`, `--styling`, `--shadcn`, `--shadcn-set`, `--deploy`, `--dark-mode`, `--validation`, `--auth`, `--seo`, `--i18n`, `--testing`, `--playwright`, `--api-envelope`, `--icons`, … (+ `--no-*`).
+
+Default scaffold is a **neutral base** (no endpoints/envelope/store). Use presets for common stacks.
+
+Upgrade an existing app’s agent surface:
+
+```bash
+npx create-next-style-guide upgrade --diff .
+npx create-next-style-guide upgrade --apply .
+```
+
+Walkthrough: [`docs/examples/api-app-crud.md`](docs/examples/api-app-crud.md).
+
+---
+
+## 🗂️ Repo layout
+
+```text
+next-style-guide/
+├── cli/                     # create-next-style-guide
+│   ├── src/                 # prompts, scaffold, installers
+│   ├── template/            # base app
+│   └── addons/              # optional feature packs
+├── scripts/smoke.sh
+├── AGENTS.md
+└── VERSION
+```
+
+---
+
+## 🛠️ Contributors
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm smoke          # uses rg if available, else grep
+```
+
+Local CLI without publishing:
+
+```bash
+pnpm --filter create-next-style-guide build
+node cli/dist/index.js my-app --yes --no-install
+# or
+pnpm --filter create-next-style-guide dev
+```
+
+See [`AGENTS.md`](AGENTS.md).
+
+---
+
+## 🚢 Release (npm via GitHub Actions)
+
+Latest on npm: [`create-next-style-guide`](https://www.npmjs.com/package/create-next-style-guide) — version tracked in [`VERSION`](VERSION).
+
+Pushing a version tag publishes the package.
+
+1. **Secret once:** GitHub repo → Settings → Secrets and variables → Actions → `NPM_TOKEN`  
+   Create a [granular npm token](https://www.npmjs.com/settings/~/tokens) with **Read and write** + **Bypass 2FA** for publish.
+2. Commit your changes on `main`.
+3. Tag and push (semver after current `VERSION`):
+
+```bash
+# example: VERSION is 0.1.4 → next tag
+git tag v0.1.5
+git push origin v0.1.5
+```
+
+Workflow [`.github/workflows/publish.yml`](.github/workflows/publish.yml) runs typecheck + smoke, publishes, then commits `VERSION` + root/`cli` `package.json` back to `main`. On pack/publish, root `README.md` + `LICENSE` are copied into `cli/` so the [npm package page](https://www.npmjs.com/package/create-next-style-guide) shows the same docs.
+
+Tag format: `v` + semver (`v0.1.5`, `v1.0.0-beta.1`, …).
+
+---
+
+## 🤝 Contributing
+
+Issues and PRs → [github.com/alidanial7/next-style-guide](https://github.com/alidanial7/next-style-guide)
+
+## 📄 License
+
+MIT

package/dist/index.js

@@ -530,9 +530,10 @@ async function runPrompts(initialName) {
       placeholder: "my-app",
       initialValue: initialName ?? "my-app",
       validate(value) {
-        if (!value.trim()) return "Name is required.";
+        const next = value ?? "";
+        if (!next.trim()) return "Name is required.";
         try {
-          slugify(value);
+          slugify(next);
         } catch (error) {
           return error instanceof Error ? error.message : "Invalid name.";
         }
@@ -626,10 +627,34 @@ async function runPrompts(initialName) {
 // src/scaffold.ts
 import fs28 from "fs-extra";
 import path29 from "path";
+import { execFileSync } from "child_process";
 import * as p2 from "@clack/prompts";
-import { execSync } from "child_process";
 import color2 from "picocolors";
 
+// src/helpers/run-package-install.ts
+import { spawn } from "child_process";
+function runPackageInstall(projectDir, pm) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(pm.id, pm.installArgs, {
+      cwd: projectDir,
+      stdio: "inherit",
+      env: process.env,
+      shell: process.platform === "win32"
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(new Error(`${pm.id} ${pm.installArgs.join(" ")} exited with ${code}`));
+    });
+  });
+}
+function yieldUi() {
+  return new Promise((resolve) => setImmediate(resolve));
+}
+
 // src/helpers/replace-tokens.ts
 import fs from "fs-extra";
 import path2 from "path";
@@ -1964,7 +1989,7 @@ var huskyInstaller = {
       },
       "devDependencies"
     );
-    await addScripts(projectDir, { prepare: "husky" });
+    await addScripts(projectDir, { prepare: "husky || true" });
     const tsHooks = [];
     if (options.prettier) tsHooks.push("prettier --write");
     if (options.eslint) tsHooks.push("eslint --fix");
@@ -3669,10 +3694,18 @@ var installers = [
   appProvidersInstaller,
   surfaceInstaller
 ];
-async function runInstallers(ctx) {
+async function runInstallers(ctx, onProgress) {
+  const active = installers.filter(
+    (installer) => installer.active(ctx.options)
+  );
   const ran = [];
-  for (const installer of installers) {
-    if (!installer.active(ctx.options)) continue;
+  for (let i = 0; i < active.length; i += 1) {
+    const installer = active[i];
+    await onProgress?.({
+      id: installer.id,
+      index: i + 1,
+      total: active.length
+    });
     await installer.run(ctx);
     ran.push(installer.id);
   }
@@ -3693,6 +3726,7 @@ async function scaffold(options) {
   }
   const spin = p2.spinner();
   spin.start("Copying template");
+  await yieldUi();
   if (!await fs28.pathExists(TEMPLATE_DIR)) {
     spin.stop("Template missing");
     throw new Error(`Template directory not found at ${TEMPLATE_DIR}`);
@@ -3709,30 +3743,51 @@ async function scaffold(options) {
     await fs28.move(gitignoreSrc, gitignoreDest, { overwrite: true });
   }
   spin.message("Applying project tokens");
+  await yieldUi();
   await replaceTokensInTree(projectDir, {
     __PROJECT_NAME__: options.name,
     __PROJECT_SLUG__: options.slug,
     __PACKAGE_MANAGER__: pm.id
   });
-  spin.message("Running installers");
-  const ran = await runInstallers({ projectDir, options });
+  const ran = await runInstallers({ projectDir, options }, async (step) => {
+    spin.message(`Installer (${step.index}/${step.total}): ${step.id}`);
+    await yieldUi();
+  });
+  spin.stop(
+    ran.length ? `Scaffold ready \xB7 ${ran.length} installer${ran.length === 1 ? "" : "s"}` : "Scaffold ready \xB7 base template"
+  );
   if (!options.noInstall) {
-    spin.message(`Installing dependencies (${pm.id})`);
+    if (options.husky) {
+      try {
+        execFileSync("git", ["init"], {
+          cwd: projectDir,
+          stdio: "ignore"
+        });
+      } catch {
+      }
+    }
+    p2.log.step(
+      `Installing dependencies with ${color2.cyan(pm.id)} \u2014 live output below\u2026`
+    );
     try {
-      execSync(`${pm.id} ${pm.installArgs.join(" ")}`, {
-        cwd: projectDir,
-        stdio: "ignore"
-      });
-    } catch {
+      await runPackageInstall(projectDir, pm);
+      p2.log.success("Dependencies installed");
+    } catch (error) {
       if (pm.id !== "npm") {
-        spin.message(`${pm.id} failed \u2014 trying npm`);
-        execSync("npm install", { cwd: projectDir, stdio: "ignore" });
+        p2.log.warn(`${pm.id} failed \u2014 retrying with npm\u2026`);
+        const npm = getPackageManager("npm");
+        await runPackageInstall(projectDir, npm);
+        p2.log.success("Dependencies installed (npm)");
       } else {
-        throw new Error("npm install failed");
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Dependency install failed: ${message}`);
       }
     }
+  } else {
+    p2.log.info(
+      color2.dim(`Skipped install \xB7 run ${pm.id} install in the project folder`)
+    );
   }
-  spin.stop("Project ready");
   if (ran.length) {
     p2.log.info(`Installers: ${ran.join(", ")}`);
   } else {