nextworks 0.2.0-alpha.0 → 0.2.0-alpha.10

package/README.md

@@ -1,37 +1,76 @@
 # nextworks
 
+## 90-second install demo (silent)
+
+Fresh `create-next-app` + `npx nextworks add blocks --templates`, plus a quick browser tour of the gallery + templates:
+
+[![Nextworks install demo](https://img.youtube.com/vi/7YKmGFmFY5c/hqdefault.jpg)](https://www.youtube.com/watch?v=7YKmGFmFY5c)
+
 Nextworks is a CLI that installs **modular Next.js building blocks** into your app:
 
 - **Blocks** – UI sections, templates, and core UI primitives.
 
 > **Status:** early‑access alpha. Expect rough edges and breaking changes between alpha releases.
 >
-> **Package manager:** npm only (for now).
+> **Support matrix:**
+>
+> **CI-tested:**
+>
+> - OS: Windows, macOS, Linux
+> - Node: 20.x and 22.x
+> - Next.js (sandbox pin): 16.0.7 and 16.1.4 (via create-next-app in CI)
+> - Router: App Router and Pages Router
+> - Package managers: npm, pnpm, yarn
+>
+> Note: CI uses pinned Next.js versions for stability and security (see CVE-2025-66478 / RSC protocol advisory).
 >
 > In this alpha, the most reliable setup is:
 >
-> 1. Create a new Next.js App Router project:
+> 1. Create a new Next.js project (App Router **or** Pages Router):
 >
 >    ```bash
 >    npx create-next-app@latest
 >    ```
 >
-> 2. From your app root, install **Blocks** first:
+> 2. From your app root, install **Blocks**:
+>
+>    ```bash
+>    npx nextworks@latest add blocks --templates
+>    ```
+>
+>    pnpm / yarn equivalents:
 >
 >    ```bash
->    npx nextworks@latest add blocks --sections --templates
+>    pnpm dlx nextworks@latest add blocks --templates
+>    yarn dlx nextworks@latest add blocks --templates
 >    ```
 >
 >    Non-interactive / CI-friendly:
 >
 >    ```bash
->    npx nextworks@latest add blocks --sections --templates --yes
+>    npx nextworks@latest add blocks --templates --yes
+>    ```
+>
+>    Force a specific package manager (overrides lockfile detection):
+>
+>    ```bash
+>    npx nextworks@latest add blocks --templates --pm pnpm
+>    npx nextworks@latest add blocks --templates --pm yarn
+>    npx nextworks@latest add blocks --templates --pm npm
 >    ```
 >
 > 3. Optionally, adjust flags to install only what you want (UI-only, sections, templates).
 
 ---
 
+## Known issues (alpha)
+
+- **Existing files may be overwritten** if they collide with kit paths. Commit first.
+- **Router entrypoint patching can conflict** with heavily customized `app/layout.tsx` or `pages/_app.tsx`.
+- **Fonts/providers wiring:** Blocks configures fonts in your router entrypoint (not inside shared packages) for Turbopack compatibility. If you manually edit fonts/providers and see errors, re-run the Blocks install to re-apply the patch.
+
+---
+
 ## Safety (read this first)
 
 `nextworks` installs kits by copying files into your Next.js project. If a destination path already exists, kit installs may **overwrite** your files.
@@ -49,10 +88,13 @@ Before running installs, strongly consider:
 Kits may also:
 
 - **merge dependencies** into `package.json`
-- **edit `app/layout.tsx`** (Blocks)
+- **edit your router entrypoint** (Blocks):
+  - App Router: `app/layout.tsx`
+  - Pages Router: `pages/_app.tsx` (and may create/update `pages/_document.tsx`)
 - create/update `.nextworks/config.json`
 
 For a transparent breakdown of what each kit writes/edits, see:
+
 - https://github.com/jblh/nextworks-cli/blob/main/docs/FILE_CHANGES.md
 
 ---
@@ -66,6 +108,8 @@ Nextworks is early‑access alpha and I’m actively looking for feedback from e
 - **Start here (installation + where to post feedback):** https://github.com/jblh/nextworks-cli/discussions/1
 - **Alpha feedback thread (what broke / what’s missing):** https://github.com/jblh/nextworks-cli/discussions/2
 
+If you’re reporting an install/runtime issue, please include OS, Node version, Next.js version, package manager, the exact command you ran, and the error output.
+
 ### Bug reports
 
 For reproducible bugs / errors (especially install/runtime issues), please open a GitHub Issue using the templates in `.github/ISSUE_TEMPLATE/`.
@@ -78,17 +122,25 @@ If you need to share something privately (e.g. security-related), email: nextjsw
 
 ## Install and run the CLI
 
-From your Next.js app root, use `npx`:
+From your Next.js app root, run the CLI with your preferred package manager:
 
 ```bash
 npx nextworks@latest --help
+pnpm dlx nextworks@latest --help
+yarn dlx nextworks@latest --help
 ```
 
 Example commands:
 
 ```bash
-npx nextworks@latest add blocks --sections --templates
-npx nextworks@latest add blocks --sections --templates --yes  # non-interactive / CI
+npx nextworks@latest add blocks  --templates
+pnpm dlx nextworks@latest add blocks --templates
+yarn dlx nextworks@latest add blocks --templates
+
+npx nextworks@latest add blocks --templates --yes  # non-interactive / CI
+
+# Force a specific package manager (overrides lockfile detection)
+npx nextworks@latest add blocks --templates --pm pnpm
 ```
 
 ---
@@ -97,7 +149,7 @@ npx nextworks@latest add blocks --sections --templates --yes  # non-interactive
 
 Prerequisites:
 
-- A Next.js App Router project (e.g. from `create-next-app`).
+- A Next.js project (App Router **or** Pages Router).
 - TypeScript required.
 - Tailwind CSS required (the Blocks kit and templates rely on Tailwind classes).
 
@@ -108,33 +160,45 @@ From your app root:
 Non-interactive / CI-friendly (auto-accept defaults where possible):
 
 ```bash
-npx nextworks@latest add blocks --sections --templates --yes
+npx nextworks@latest add blocks --templates --yes
 ```
 
 > **Turbopack / Next 16 note (fonts + AppProviders)**
 >
-> As of the current alpha, `@nextworks/blocks-core/server` intentionally **does not** import `next/font/*`.
-> Fonts are instead configured directly in your app’s `app/layout.tsx` (the CLI patches this for you).
-> This avoids Turbopack dev issues related to internal Next font modules.
+> Shared packages intentionally avoid importing `next/font/*`.
+> Fonts are configured directly in your app’s router entrypoint (the CLI patches this for you):
+>
+> - App Router: `app/layout.tsx`
+> - Pages Router: `pages/_app.tsx`
+>   This avoids Turbopack dev issues related to internal Next font modules.
 >
 > If you ever see a font-related Turbopack error after upgrades or manual edits, re-run:
 >
 > ```bash
-> npx nextworks@latest add blocks --sections --templates
+> npx nextworks@latest add blocks --templates
 > ```
 >
-> to re-apply the layout patch, and ensure `app/layout.tsx` contains a valid
+> to re-apply the patch, and ensure your router entrypoint contains a valid
 > `import { ... } from "next/font/google";` plus the corresponding `const geistSans = ...` etc.
+>
+> - App Router: `app/layout.tsx`
+> - Pages Router: `pages/_app.tsx`
 
 ```bash
-npx nextworks@latest add blocks --sections --templates
+npx nextworks@latest add blocks --templates
 ```
 
+> Note: Older docs (and the demo video) may show `--sections --templates`. It still works, but `--sections` is no longer needed.
+
 This copies:
 
 - `components/ui/*` (core UI primitives)
 - `components/sections/*` (reusable sections)
-- Page templates under `app/templates/*`
+- Templates (router-native):
+  - App Router projects: `app/templates/<template>/**`
+  - Pages Router projects:
+    - route entry file: `pages/templates/<template>/index.tsx`
+    - supporting template files: `components/templates/<template>/**`
 - Theme helpers and `app/globals.css` (if not already present)
 
 After this step you should be able to start your dev server and visit:
@@ -142,7 +206,6 @@ After this step you should be able to start your dev server and visit:
 - `/` (if wired as the home page), or
 - `/templates/productlaunch`, `/templates/saasdashboard`, `/templates/digitalagency`
 
-
 ---
 
 ## Advanced Blocks installs
@@ -150,21 +213,20 @@ After this step you should be able to start your dev server and visit:
 For a full UI kit including core primitives, sections, and templates, use:
 
 ```bash
-npx nextworks@latest add blocks --sections --templates
+npx nextworks@latest add blocks --templates
 ```
 
 Non-interactive / CI-friendly:
 
 ```bash
-npx nextworks@latest add blocks --sections --templates --yes
+npx nextworks@latest add blocks --templates --yes
 ```
 
 If you want finer control:
 
 - `npx nextworks@latest add blocks --ui-only` – install core UI primitives only (no sections/templates).
 - `npx nextworks@latest add blocks --sections` – install core + sections only.
-- `npx nextworks@latest add blocks --templates` – install core + templates only.
-- `npx nextworks@latest add blocks --sections --templates` – install core + sections + templates.
+- `npx nextworks@latest add blocks --templates` – install core + sections + templates.
 
 ---
 
@@ -177,16 +239,27 @@ You can add a short “Nextworks setup” section to your app README:
 
 1. Install and run the CLI from your Next.js app root:
 
-   npx nextworks@latest add blocks --sections --templates
+   npx nextworks@latest add blocks --templates
+
    # CI / non-interactive:
-   npx nextworks@latest add blocks --sections --templates --yes
+
+   npx nextworks@latest add blocks --templates --yes
 
 2. Start dev server:
 
    npm run dev
 
 3. Try these routes:
-   - `/` or `/templates/productlaunch` (Blocks template)
+   - `/templates/productlaunch`
+   - `/templates/saasdashboard`
+   - `/templates/digitalagency`
+   - `/templates/gallery`
+
+   Template files live at:
+   - App Router: `app/templates/<template>/**`
+   - Pages Router:
+     - route entry file: `pages/templates/<template>/index.tsx`
+     - supporting template files: `components/templates/<template>/**`
 ```
 
 ---

package/dist/cli_manifests/blocks_manifest.json

@@ -27,7 +27,10 @@
         "components/ui/theme-toggle.tsx",
         "components/ui/toaster.tsx",
         "components/enhanced-theme-provider.tsx",
+        "components/providers/BlocksAppProviders.tsx",
         "components/app-providers.tsx",
+        "components/app-providers.app.tsx",
+        "components/app-providers.pages.tsx",
         "components/theme-provider.tsx",
         "lib/themes.ts",
         "lib/utils.ts",
@@ -65,35 +68,6 @@
     "templates": {
       "description": "Full page templates (Product Launch, SaaS Dashboard, Digital Agency, Gallery)",
       "files": [
-        "components/ui/alert-dialog.tsx",
-        "components/ui/brand-node.tsx",
-        "components/ui/button.tsx",
-        "components/ui/card.tsx",
-        "components/ui/checkbox.tsx",
-        "components/ui/cta-button.tsx",
-        "components/ui/dropdown-menu.tsx",
-        "components/ui/feature-card.tsx",
-        "components/ui/input.tsx",
-        "components/ui/label.tsx",
-        "components/ui/pricing-card.tsx",
-        "components/ui/select.tsx",
-        "components/ui/skeleton.tsx",
-        "components/ui/switch.tsx",
-        "components/ui/table.tsx",
-        "components/ui/testimonial-card.tsx",
-        "components/ui/textarea.tsx",
-        "components/ui/theme-selector.tsx",
-        "components/ui/theme-toggle.tsx",
-        "components/ui/toaster.tsx",
-        "components/enhanced-theme-provider.tsx",
-        "components/app-providers.tsx",
-        "components/theme-provider.tsx",
-        "lib/themes.ts",
-        "lib/utils.ts",
-        "app/globals.css",
-        "app/tw-animate.css",
-        "next.config.ts",
-
         "app/templates/productlaunch/page.tsx",
         "app/templates/productlaunch/PresetThemeVars.tsx",
         "app/templates/productlaunch/README.md",
@@ -162,8 +136,21 @@
         "public/placeholders/saas_dashboard/projectBoard.png",
         ".nextworks/docs/THEME_GUIDE.md"
       ]
+    },
+    "gallery": {
+      "description": "Gallery of marketing sections (Hero, CTA, Pricing, etc.)",
+      "files": [
+        "app/templates/gallery/page.tsx",
+        "app/templates/gallery/PresetThemeVars.tsx",
+        "public/placeholders/gallery/hero-pexels-broken-9945014.avif",
+        "public/placeholders/gallery/pexels-googledeepmind-25626431.jpg",
+        "public/placeholders/gallery/pexels-googledeepmind-25626432.jpg",
+        "public/placeholders/gallery/pexels-googledeepmind-25626434.jpg",
+        "public/placeholders/gallery/pexels-googledeepmind-25626436.jpg"
+      ]
     }
   },
+
   "files": [
     "public/placeholders/gallery/hero-pexels-broken-9945014.avif",
     "public/placeholders/gallery/pexels-googledeepmind-25626431.jpg",

package/dist/commands/blocks.d.ts

@@ -5,6 +5,9 @@ export interface AddBlocksOptions {
     uiOnly?: boolean;
     /** Skip interactive prompts and accept defaults. */
     yes?: boolean;
+    /** Force package manager (overrides lockfile detection). */
+    pm?: import("../utils/package-manager").PackageManager;
+    dryRun?: boolean;
 }
 export declare function addBlocks(options?: AddBlocksOptions): Promise<void>;
 //# sourceMappingURL=blocks.d.ts.map

package/dist/commands/blocks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../../src/commands/blocks.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,oDAAoD;IACpD,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,wBAAsB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoR7E"}
+{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../../src/commands/blocks.ts"],"names":[],"mappings":"AAgCA,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,oDAAoD;IACpD,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,4DAA4D;IAC5D,EAAE,CAAC,EAAE,OAAO,0BAA0B,EAAE,cAAc,CAAC;IACvD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAokB7E"}