nextworks 0.1.0-alpha.9 → 0.2.0-alpha.10

package/README.md

@@ -1,156 +1,210 @@
 # 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.
-- **Auth Core** – Email/password auth (NextAuth + Prisma), basic dashboard, and helpers.
-- **Forms** – Opinionated form primitives built on React Hook Form + Zod.
-- **Data** – Example CRUD for Users + Posts with admin UI, wired to Auth + Prisma.
 
 > **Status:** early‑access alpha. Expect rough edges and breaking changes between alpha releases.
 >
-> In this alpha, the most reliable setup is to install **Blocks** first using:
+> **Support matrix:**
 >
-> ```bash
-> npx nextworks add blocks --sections --templates
-> ```
+> **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 project (App Router **or** Pages Router):
+>
+>    ```bash
+>    npx create-next-app@latest
+>    ```
+>
+> 2. From your app root, install **Blocks**:
+>
+>    ```bash
+>    npx nextworks@latest add blocks --templates
+>    ```
 >
-> and then add **Auth Core**, **Forms**, and **Data** on top. Partial setups (e.g. Auth/Data without Blocks) may require manual tweaks and are not yet fully supported.
+>    pnpm / yarn equivalents:
+>
+>    ```bash
+>    pnpm dlx nextworks@latest add blocks --templates
+>    yarn dlx nextworks@latest add blocks --templates
+>    ```
+>
+>    Non-interactive / CI-friendly:
+>
+>    ```bash
+>    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).
 
 ---
 
-## Feedback / Contact
+## Known issues (alpha)
 
-Nextworks is early‑access alpha and I’m actively looking for feedback from early testers. If you run into issues, have questions, or want to suggest improvements or pro‑level features, I’m happy to help and would really appreciate hearing from you:
-
-- Email: nextjsworks@gmail.com
+- **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.
 
 ---
 
-## Install and run the CLI
+## Safety (read this first)
 
-From your Next.js app root, use `npx`:
+`nextworks` installs kits by copying files into your Next.js project. If a destination path already exists, kit installs may **overwrite** your files.
 
-```bash
-npx nextworks --help
-```
+Before running installs, strongly consider:
 
-Example commands:
+- **Commit first**, then install:
+  - `git add -A && git commit -m "baseline"`
+- Review changes after install:
+  - `git diff --name-status`
+- To undo everything quickly:
+  - `git reset --hard`
+  - (optional) remove untracked files created by installs: `git clean -fd`
 
-```bash
-npx nextworks add blocks --sections --templates
-npx nextworks add auth-core
-npx nextworks add forms
-npx nextworks add data
-```
+Kits may also:
 
----
+- **merge dependencies** into `package.json`
+- **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`
 
-## Getting started in an existing Next.js app
+For a transparent breakdown of what each kit writes/edits, see:
 
-Prerequisites:
+- https://github.com/jblh/nextworks-cli/blob/main/docs/FILE_CHANGES.md
 
-- A Next.js App Router project (e.g. from `create-next-app`).
-- TypeScript + Tailwind recommended.
-- A **PostgreSQL database** if you plan to use **Auth Core** and **Data**.
-  - The kits are designed and tested with Postgres using a database hosted on [Neon](https://neon.tech/).
+---
 
-From your app root:
+## Feedback
 
-### 1) Install Blocks (UI kit)
+Nextworks is early‑access alpha and I’m actively looking for feedback from early testers.
 
-```bash
-npx nextworks add blocks --sections --templates
-```
+### Where to post feedback
 
-This copies:
+- **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
 
-- `components/ui/*` (core UI primitives)
-- `components/sections/*` (reusable sections)
-- Page templates under `app/templates/*`
-- Theme helpers and `app/globals.css` (if not already present)
+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.
 
-After this step you should be able to start your dev server and visit:
+### Bug reports
 
-- `/` (if wired as the home page), or
-- `/templates/productlaunch`, `/templates/saasdashboard`, `/templates/digitalagency`
+For reproducible bugs / errors (especially install/runtime issues), please open a GitHub Issue using the templates in `.github/ISSUE_TEMPLATE/`.
 
-### 2) Add Auth Core
+### Private contact (optional)
 
-```bash
-npx nextworks add auth-core
-```
+If you need to share something privately (e.g. security-related), email: nextjsworks@gmail.com
 
-Then:
-
-1. Copy and edit your environment variables:
-
-   ```bash
-   cp .env.example .env
-   ```
-
-   Set at minimum:
+---
 
-   ```bash
-   DATABASE_URL=postgres://...
-   NEXTAUTH_URL=http://localhost:3000
-   NEXTAUTH_SECRET=your-strong-secret
-   ```
+## Install and run the CLI
 
-2. Install Prisma (if you haven’t already):
+From your Next.js app root, run the CLI with your preferred package manager:
 
-   ```bash
-   npm install @prisma/client prisma
-   ```
+```bash
+npx nextworks@latest --help
+pnpm dlx nextworks@latest --help
+yarn dlx nextworks@latest --help
+```
 
-3. Run Prisma:
+Example commands:
 
-   ```bash
-   npx prisma generate
-   npx prisma migrate dev -n init
-   ```
+```bash
+npx nextworks@latest add blocks  --templates
+pnpm dlx nextworks@latest add blocks --templates
+yarn dlx nextworks@latest add blocks --templates
 
-Start your dev server:
+npx nextworks@latest add blocks --templates --yes  # non-interactive / CI
 
-```bash
-npm run dev
+# Force a specific package manager (overrides lockfile detection)
+npx nextworks@latest add blocks --templates --pm pnpm
 ```
 
-Visit:
+---
 
-- `/auth/signup`
-- `/auth/login`
-- `/dashboard` (protected)
+## Getting started in an existing Next.js app
 
-### 3) Add Forms (optional)
+Prerequisites:
 
-```bash
-npx nextworks add forms
-```
+- A Next.js project (App Router **or** Pages Router).
+- TypeScript required.
+- Tailwind CSS required (the Blocks kit and templates rely on Tailwind classes).
 
-This adds form primitives and example pages:
+From your app root:
 
-- `/examples/forms/basic`
-- `/examples/forms/server-action`
-- `/examples/forms/wizard`
+### 1) Install Blocks (UI kit)
 
-### 4) Add Data (optional, requires Auth Core)
+Non-interactive / CI-friendly (auto-accept defaults where possible):
 
 ```bash
-npx nextworks add data
+npx nextworks@latest add blocks --templates --yes
 ```
 
-Make sure your Prisma migrations are up to date:
+> **Turbopack / Next 16 note (fonts + AppProviders)**
+>
+> 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 --templates
+> ```
+>
+> 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 prisma generate
-npx prisma migrate dev
+npx nextworks@latest add blocks --templates
 ```
 
-Then visit:
+> Note: Older docs (and the demo video) may show `--sections --templates`. It still works, but `--sections` is no longer needed.
 
-- `/admin/posts`
-- `/admin/users`
+This copies:
+
+- `components/ui/*` (core UI primitives)
+- `components/sections/*` (reusable sections)
+- 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:
+
+- `/` (if wired as the home page), or
+- `/templates/productlaunch`, `/templates/saasdashboard`, `/templates/digitalagency`
 
 ---
 
@@ -159,15 +213,20 @@ Then visit:
 For a full UI kit including core primitives, sections, and templates, use:
 
 ```bash
-npx nextworks add blocks --sections --templates
+npx nextworks@latest add blocks --templates
+```
+
+Non-interactive / CI-friendly:
+
+```bash
+npx nextworks@latest add blocks --templates --yes
 ```
 
 If you want finer control:
 
-- `npx nextworks add blocks --ui-only` – install core UI primitives only (no sections/templates).
-- `npx nextworks add blocks --sections` – install core + sections only.
-- `npx nextworks add blocks --templates` – install core + templates only.
-- `npx nextworks add blocks --sections --templates` – install core + sections + templates.
+- `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 + sections + templates.
 
 ---
 
@@ -176,41 +235,31 @@ If you want finer control:
 You can add a short “Nextworks setup” section to your app README:
 
 ```md
-### Nextworks setup (Blocks + Auth + optional Forms/Data)
+### Nextworks setup (Blocks)
 
 1. Install and run the CLI from your Next.js app root:
 
-   npx nextworks add blocks --sections --templates
-   npx nextworks add auth-core
-
-2. Copy environment variables:
-
-   cp .env.example .env
+   npx nextworks@latest add blocks --templates
 
-   Set DATABASE_URL, NEXTAUTH_URL, NEXTAUTH_SECRET (and any OAuth or email provider vars you need).
+   # CI / non-interactive:
 
-3. Install Prisma (if not present) and run migrations:
+   npx nextworks@latest add blocks --templates --yes
 
-   npm install @prisma/client prisma
-   npx prisma generate
-   npx prisma migrate dev -n init
-
-4. (Optional) Add Forms and Data kits:
-
-   npx nextworks add forms
-   npx nextworks add data
-   npx prisma generate
-   npx prisma migrate dev -n init_data
-
-5. Start dev server:
+2. Start dev server:
 
    npm run dev
 
-6. Try these routes:
-   - `/` or `/templates/productlaunch` (Blocks template)
-   - `/auth/signup`, `/auth/login`, `/dashboard` (Auth)
-   - `/examples/forms/basic` (if you ran `npx nextworks add forms`)
-   - `/admin/posts`, `/admin/users` (if you ran `npx nextworks add data`)
+3. Try these routes:
+   - `/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>/**`
 ```
 
 ---
@@ -228,27 +277,6 @@ the MIT License.
 
 ## Troubleshooting
 
-- **Prisma errors or missing migrations**
-
-  Ensure you’ve run:
-
-  ```bash
-  npx prisma generate
-  npx prisma migrate dev
-  ```
-
-  and that `DATABASE_URL` in `.env` points to a reachable PostgreSQL instance.
-
-- **Auth routes 404**
-
-  Make sure you ran:
-
-  ```bash
-  npx nextworks add auth-core
-  ```
-
-  from your app root, and restart your dev server.
-
 - **Type errors from imported components**
 
   Confirm your project is using TypeScript and that your TypeScript config picks up the new `components/` and `lib/` paths.

package/dist/cli_manifests/blocks_manifest.json

@@ -27,11 +27,15 @@
         "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",
         "app/globals.css",
+        "app/tw-animate.css",
         "next.config.ts",
         ".nextworks/docs/THEME_GUIDE.md",
         ".nextworks/docs/BLOCKS_README.md",
@@ -64,34 +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",
-        "next.config.ts",
-
         "app/templates/productlaunch/page.tsx",
         "app/templates/productlaunch/PresetThemeVars.tsx",
         "app/templates/productlaunch/README.md",
@@ -160,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

@@ -3,6 +3,11 @@ export interface AddBlocksOptions {
     templates?: boolean;
     gallery?: boolean;
     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":"AAyBA,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;CAClB;AAED,wBAAsB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2Q7E"}
+{"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"}