@thinhnguyencth1204/nextcli 0.3.0 → 0.4.0

package/templates/next-base/PROJECT_STRUCTURE.md

@@ -0,0 +1,88 @@
+# Project structure
+
+Generated by NexTCLI. Folders marked **(module)** or **(feature)** appear only when that add-on is enabled.
+
+## Root
+
+| Path                   | Purpose                                                       |
+| ---------------------- | ------------------------------------------------------------- |
+| `nextcli.json`         | Manifest: CLI version, locales, namespaces, modules, features |
+| `SETUP.md`             | Env + branding setup (this repo)                              |
+| `PROJECT_STRUCTURE.md` | Folder map (this file)                                        |
+| `prisma/`              | Schema + migrations                                           |
+| `messages/`            | i18n JSON per locale/namespace                                |
+| `public/`              | Static assets (`logo.svg`, etc.)                              |
+
+## `src/app/` — App Router
+
+| Path                 | Purpose                                    |
+| -------------------- | ------------------------------------------ |
+| `layout.tsx`         | Root layout, metadata from `branding`      |
+| `globals.css`        | Design tokens (`nextcli:theme` markers)    |
+| `(auth)/`            | Sign-in, forced password change            |
+| `(dashboard)/`       | Protected shell (session + password guard) |
+| `api/auth/[...all]/` | Better Auth passthrough (not wrapped)      |
+| `api/v1/`            | Project API envelope (`ok` / `fail`)       |
+| `api/v1/users/`      | User CRUD + RBAC **(base)**                |
+| `api/v1/example/`    | Demo CRUD sample                           |
+
+## `src/config/`
+
+| Path          | Purpose                              |
+| ------------- | ------------------------------------ |
+| `branding.ts` | Project name, logo path, description |
+
+## `src/lib/` — Shared runtime
+
+| Path                         | Purpose                                           |
+| ---------------------------- | ------------------------------------------------- |
+| `auth.ts` / `auth-client.ts` | Better Auth (username + JWT)                      |
+| `bootstrap.ts`               | Seeds `admin` role/user on startup                |
+| `rbac.ts`                    | Role hierarchy guards                             |
+| `prisma.ts`                  | DB client                                         |
+| `api-response.ts`            | `/api/v1/*` envelope helpers                      |
+| `supabase/`                  | **(module: `supabase`)** client + storage helpers |
+| `resend/`                    | **(module: `resend`)** email client + send helper |
+
+## `src/features/` vs `src/example/`
+
+| Path               | Purpose                                                   |
+| ------------------ | --------------------------------------------------------- |
+| `features/auth/`   | Sign-in + change-password UI                              |
+| `features/users/`  | User validations/services for API                         |
+| `example/`         | Starter demo feature (rename for production)              |
+| `features/<name>/` | **(feature: `nextcli add feature <name>`)** CRUD scaffold |
+
+## `src/components/`
+
+| Path                | Purpose                           |
+| ------------------- | --------------------------------- |
+| `branding/logo.tsx` | Logo + project name               |
+| `layout/private/`   | Dashboard shell (sidebar, header) |
+| `ui/`               | shadcn-style primitives           |
+
+## `src/i18n/`
+
+Locale config with `nextcli:locales` / `nextcli:namespaces` markers (patched by `nextcli add language` / `add feature`).
+
+## `src/emails/`
+
+**(module: `resend`)** React Email templates.
+
+## Optional modules (via `nextcli add module`)
+
+| Module              | Adds                                                                |
+| ------------------- | ------------------------------------------------------------------- |
+| `chat`              | Chat routes, hooks, Prisma chat models (+ auto `supabase-realtime`) |
+| `supabase`          | `src/lib/supabase/*`, Storage upload helpers                        |
+| `supabase-realtime` | Realtime channel helpers                                            |
+| `seo`               | robots/sitemap/JSON-LD helpers                                      |
+| `resend`            | `src/lib/resend/*`, `src/emails/*`                                  |
+
+Module **env variables** and where to find them: see `SETUP.md` → **Optional module environment** (full catalog; `Enabled modules` line updates when you create/add modules).
+
+## Notes
+
+- Do not wrap `api/auth/[...all]` responses — Better Auth expects raw format.
+- Review `prisma/schema.prisma` before production migrations (demo `Example` model).
+- Super-admin account `admin` cannot be modified/deleted via user APIs.

package/templates/next-base/SETUP.md

@@ -0,0 +1,86 @@
+# Project setup guide
+
+Quick reference for env vars and branding after `nextcli create`.
+
+## First run (required)
+
+1. Start PostgreSQL and set `DATABASE_URL` in `.env`.
+2. `bun run db:migrate` — applies `prisma/migrations` (includes `Role`, `User.username`, `requirePasswordChange`).
+3. `bun run dev` — bootstrap seeds `admin` / `admin` on first start.
+
+`postinstall` runs `prisma generate` so TypeScript knows models like `Role` and `requirePasswordChange`. If types look stale, run `bun run db:generate` manually.
+
+## Branding (edit in repo, not env)
+
+| What                                       | Where                                                                     |
+| ------------------------------------------ | ------------------------------------------------------------------------- |
+| Display name, slug, description, logo path | `src/config/branding.ts`                                                  |
+| Logo file                                  | `public/logo.svg` (or update `logoPath`)                                  |
+| Theme colors (primary, sidebar, …)         | `src/app/globals.css` between `nextcli:theme:start` / `nextcli:theme:end` |
+| Sidebar/header labels (i18n)               | `messages/<locale>/common.json` → `appName`                               |
+
+## Core environment variables
+
+Set in `.env` / `.env.development` (secrets are generated at create time).
+
+| Variable              | Purpose                | Where to get                                                   |
+| --------------------- | ---------------------- | -------------------------------------------------------------- |
+| `DATABASE_URL`        | PostgreSQL connection  | Local Postgres or cloud provider dashboard → connection string |
+| `BETTER_AUTH_SECRET`  | Auth signing secret    | Auto-generated on create; rotate in production                 |
+| `BETTER_AUTH_URL`     | Server auth base URL   | Your app URL (e.g. `http://localhost:3000`)                    |
+| `NEXT_PUBLIC_APP_URL` | Client-visible app URL | Same as public site URL                                        |
+
+### Default admin account
+
+On first `dev` / `start`, bootstrap creates role `admin` and user `admin` / `admin` (must change password on first login).
+
+## Optional module environment
+
+Reference for all optional modules. Matching keys are merged into `.env` when selected at `nextcli create` or via `nextcli add module`.
+
+<!-- nextcli:enabled-modules:start -->
+
+**Enabled modules:** none
+
+<!-- nextcli:enabled-modules:end -->
+
+<!-- nextcli:module-env:start -->
+
+### Module: Chat module (`chat`)
+
+| Variable                  | Where to get                                         |
+| ------------------------- | ---------------------------------------------------- |
+| `NEXT_PUBLIC_ENABLE_CHAT` | Set `true` when chat module is enabled (auto on add) |
+
+Requires `supabase-realtime` (auto-added). Run `db:migrate` after add — chat Prisma models are appended.
+
+### Module: Supabase (`supabase`)
+
+| Variable                              | Where to get                                                           |
+| ------------------------------------- | ---------------------------------------------------------------------- |
+| `NEXT_PUBLIC_SUPABASE_URL`            | Supabase Dashboard → Project Settings → API → Project URL              |
+| `NEXT_PUBLIC_SUPABASE_ANON_KEY`       | Same page → Project API keys → `anon` `public`                         |
+| `NEXT_PUBLIC_SUPABASE_STORAGE_BUCKET` | Storage → create bucket → use bucket name (default scaffold: `public`) |
+
+### Module: Supabase Realtime (`supabase-realtime`)
+
+Uses same Supabase URL/anon key as `supabase` module. Enable Realtime on tables in Supabase Dashboard → Database → Replication.
+
+### Module: SEO pack (`seo`)
+
+No extra env keys. Edit `src/app/robots.ts`, `sitemap.ts`, and JSON-LD helpers after add.
+
+### Module: Resend email (`resend`)
+
+| Variable            | Where to get                                                       |
+| ------------------- | ------------------------------------------------------------------ |
+| `RESEND_API_KEY`    | resend.com → API Keys → Create                                     |
+| `RESEND_FROM_EMAIL` | resend.com → Domains → verify domain → use `Name <you@domain.com>` |
+
+<!-- nextcli:module-env:end -->
+
+## After adding modules
+
+1. Fill new env keys in `.env` and `.env.example`.
+2. Run `bun run db:migrate` when a module adds Prisma models.
+3. See `PROJECT_STRUCTURE.md` for folders introduced by each module.