NexTCLI

NexTCLI is an npm-installable CLI to scaffold outsource-ready Next.js projects with a consistent architecture, core integrations, and fast feature generation.

Install

npm install
npm run build

For local execution:

node dist/cli.js --help

Command: create

Create a new project from the full-stack base template:

node dist/cli.js create

This command is fully interactive:

• enter project name
• select package manager in CLI UI (npm, pnpm, yarn, bun)
• multi-select optional modules (chat, supabase-realtime, seo, email)
• confirm install step
• normalizes project directory name into a safe project slug for generated package.json and env placeholders
• generates a project-specific .gitignore (standard Next.js ignores plus rules for selected optional modules; .env.example stays trackable)
• initializes a Git repository (git init) in the generated project directory
• ships START_HERE.md, SETUP.md, and PROJECT_STRUCTURE.md in the generated project root

Default output includes: Prisma + Postgres, Supabase client + Storage, Better Auth + RBAC, API client (Axios + React Query), i18n (next-intl), dashboard shell, example CRUD demo, branding, theme, UI primitives, and Lexical rich text adapters. Optional modules are added only when selected.

Rich text (base)

All generated projects include Lexical rich text building blocks:

• EditorField — swappable textarea or lexical adapter for forms
• RichTextRenderer — read-only playback of Lexical JSON from API data
• Toolbar: bold/italic/underline, emoji picker, image URL insertion
• Demo page: /blog-demo

Lexical content is stored as JSON (SerializedEditorState). Supabase-managed image URLs trigger storage cleanup via syncRemovedSupabaseRichTextImages (included in base).

Included in every project (base):

| Module | Adds | | ----------- | -------------------------------------------------------- | | database | Prisma schema, client, DATABASE_URL, db scripts | | supabase | Supabase browser client + Storage helpers | | auth | Better Auth, sign-in pages, user APIs, bootstrap admin | | api | Axios client, API envelope helpers, React Query provider | | i18n | next-intl config, messages, locale switcher | | dashboard | Protected dashboard shell, sidebar, data-table UI | | example | Starter CRUD demo + Example Prisma model |

Optional during create and add module:

| Module | Adds | | ------------------- | ------------------------------------------------------------------- | | chat | Chat routes, hooks, Prisma chat models (+ auto supabase-realtime) | | supabase-realtime | Realtime channel helpers | | seo | robots/sitemap/JSON-LD helpers | | email | Email helper + React Email templates (SMTP or Resend) |

Auth (base)

Every generated project includes:

• Better Auth + Prisma adapter with JWT + username plugins
• username/password sign-in (/sign-in) and forced password change (/change-password)
• default bootstrap user admin / admin1234 (must change password on first login)
• hierarchical RBAC (Role.level) and user CRUD under /api/v1/users
• account sample page (/account)
• auth API wrappers:
  • POST /api/v1/auth/login
  • POST /api/v1/auth/refresh
  • POST /api/v1/auth/logout
  • GET /api/v1/auth/me
  • POST /api/v1/auth/change-password

Axios setup (included in base):

• publicApi: public calls
• protectedApi: bearer token calls with 401 refresh queue + retry
• refresh uses HttpOnly cookie strategy (withCredentials: true)

API response standard

Project-owned routes under /api/v1/* use a unified envelope:

• Success:
  • { success: true, data: T, meta: { timestamp, requestId?, pagination? } }
• Error:
  • { success: false, error: { code, message, details? }, timestamp, requestId? }

This is powered by src/lib/api/response.ts (included in base). The Better Auth passthrough route /api/auth/[...all] remains unwrapped.

Command: add feature

Run inside a generated project root (database and api are included in base):

node ../dist/cli.js add feature orders

add feature creates:

• src/features/<feature>/api/use-<feature>.ts
• src/features/<feature>/components/
• src/features/<feature>/services.ts
• src/features/<feature>/validations.ts
• src/app/api/v1/<feature>/route.ts

Command: add module

Add optional modules after project initialization:

node ../dist/cli.js add module

Module copy is non-destructive: existing files are kept and reported as skipped conflicts.

Non-interactive example:

node ../dist/cli.js add module --module database --module auth --module dashboard --yes

--module supabase installs the Supabase client + Storage module. resend is handled by the email module (legacy --module resend maps to email with provider resend).

When email is selected, CLI asks for provider (resend or smtp) and only merges env keys/dependencies for that provider.

Command: add auth-provider

Enable social auth providers after the auth module is installed:

node ../dist/cli.js add auth-provider

Supported providers:

• google
• facebook

Non-interactive example:

node ../dist/cli.js add auth-provider --provider google --provider facebook --yes

This command:

• updates src/lib/auth/server.ts provider block
• merges provider env keys into .env, .env.example, and .env.development
• runs Better Auth schema generation helper (with install prompt if CLI is missing in interactive mode)

Command: migrate

Run Prisma migration script automatically from project root (requires database module):

node ../dist/cli.js migrate

Optional flags:

• --name <migration-name>: set migration name manually
• --skip-generate: pass through to prisma migrate dev --skip-generate

Generated stack (when modules selected)

• Next.js App Router + TypeScript (base)
• Better Auth + Prisma (database + auth)
• Supabase client + Storage (supabase)
• Axios + React Query (api)
• next-intl (i18n)
• Dashboard shell + TanStack Table (dashboard)
• shadcn-style shared UI folder (base)
• Zod validation (base)
• Sonner notifications (base)
• Lexical rich text editor + renderer (base)
• Optional: chat, supabase-realtime, seo, email

Template structure

Minimal base template:

• templates/next-base

Optional module templates:

• templates/features/database
• templates/features/supabase
• templates/features/auth
• templates/features/api
• templates/features/i18n
• templates/features/dashboard
• templates/features/example
• templates/features/chat
• templates/features/supabase-realtime
• templates/features/seo
• templates/features/email

Realtime chat schema foundation

Chatbox Prisma entities are appended only when you add the chat module (during create or via add module --module chat).

When chat is selected, NexTCLI auto-adds database, supabase-realtime, and supabase when missing.

The generated chat schema is provider-agnostic:

• ChatConversation
• ChatParticipant
• ChatMessage

Core relations and constraints are included:

• participant uniqueness per conversation (conversationId, userId)
• ordered message lookup index (conversationId, createdAt)
• sender and participant linkage to User