@thinhnguyencth1204/nextcli 0.5.0 → 0.6.1

package/README.md

@@ -27,7 +27,7 @@ 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`, `resend`)
+- 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
 - ships `SETUP.md` and `PROJECT_STRUCTURE.md` in the generated project root
@@ -97,7 +97,7 @@ Interactive multiselect shows available module catalog:
 - `chat`
 - `supabase-realtime`
 - `seo`
-- `resend`
+- `email`
 
 Non-interactive example:
 
@@ -106,6 +106,9 @@ node ../dist/cli.js add module --module seo --module supabase-realtime --yes
 ```
 
 `supabase` is no longer an optional module; Supabase client, Storage helpers, and Supabase Postgres env placeholders are part of the base template.
+`resend` is now 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
 
@@ -166,7 +169,7 @@ node ../dist/cli.js migrate --name init_auth --skip-generate
 - i18n base with `next-intl`
 - Sonner notifications
 - date-fns utility library
-- Optional modules: chat, supabase-realtime, seo, resend
+- Optional modules: chat, supabase-realtime, seo, email
 
 ## Template structure
 
@@ -179,7 +182,7 @@ Optional module templates:
 - `templates/features/chat`
 - `templates/features/supabase-realtime`
 - `templates/features/seo`
-- `templates/features/resend`
+- `templates/features/email`
 
 ## Realtime chat schema foundation
 

package/dist/cli.js

@@ -216,7 +216,7 @@ var templatePaths = {
   chat: path2.join(rootDir, "templates/features/chat"),
   supabaseRealtime: path2.join(rootDir, "templates/features/supabase-realtime"),
   seo: path2.join(rootDir, "templates/features/seo"),
-  resend: path2.join(rootDir, "templates/features/resend")
+  email: path2.join(rootDir, "templates/features/email")
 };
 
 // src/core/modules.ts
@@ -258,23 +258,17 @@ Requires \`supabase-realtime\` (auto-added). Run \`db:migrate\` after add \u2014
     setupSection: `No extra env keys. Edit \`src/app/robots.ts\`, \`sitemap.ts\`, and JSON-LD helpers after add.`
   },
   {
-    id: "resend",
-    label: "Resend email",
-    description: "Adds Resend client, send helper, and React Email welcome template",
-    templatePath: templatePaths.resend,
-    env: {
-      RESEND_API_KEY: "",
-      RESEND_FROM_EMAIL: ""
-    },
-    dependencies: {
-      resend: "^6.9.2",
-      "@react-email/components": "^1.0.12",
-      "react-email": "^4.0.0"
-    },
-    setupSection: `| Variable | Where to get |
-| -------- | ------------ |
-| \`RESEND_API_KEY\` | resend.com \u2192 API Keys \u2192 Create |
-| \`RESEND_FROM_EMAIL\` | resend.com \u2192 Domains \u2192 verify domain \u2192 use \`Name <you@domain.com>\` |`
+    id: "email",
+    label: "Email module (SMTP or Resend)",
+    description: "Adds provider-agnostic sendEmail helper with SMTP/Resend adapters",
+    templatePath: templatePaths.email,
+    env: {},
+    setupSection: `When you add this module, NexTCLI asks which provider to configure:
+
+- **Resend**: \`EMAIL_PROVIDER=resend\`, \`RESEND_API_KEY\`, \`RESEND_FROM_EMAIL\`
+- **SMTP**: \`EMAIL_PROVIDER=smtp\`, \`SMTP_HOST\`, \`SMTP_PORT\`, \`SMTP_USER\`, \`SMTP_PASSWORD\`, \`SMTP_FROM\`
+
+Only the selected provider keys are merged into your env files.`
   }
 ];
 function getModuleById(moduleId) {
@@ -448,6 +442,42 @@ async function ensureBetterAuthGenerate(cwd, options = {}) {
   }
 }
 
+// src/core/email-module.ts
+var EMAIL_PROVIDER_OPTIONS = ["resend", "smtp"];
+function isEmailProvider(value) {
+  return EMAIL_PROVIDER_OPTIONS.includes(value);
+}
+function getEmailProviderEnv(provider) {
+  if (provider === "smtp") {
+    return {
+      EMAIL_PROVIDER: "smtp",
+      SMTP_HOST: "",
+      SMTP_PORT: "587",
+      SMTP_USER: "",
+      SMTP_PASSWORD: "",
+      SMTP_FROM: ""
+    };
+  }
+  return {
+    EMAIL_PROVIDER: "resend",
+    RESEND_API_KEY: "",
+    RESEND_FROM_EMAIL: ""
+  };
+}
+function getEmailProviderDependencies(provider) {
+  if (provider === "smtp") {
+    return {
+      nodemailer: "^6.10.1",
+      "@types/nodemailer": "^6.4.17"
+    };
+  }
+  return {
+    resend: "^6.9.2",
+    "@react-email/components": "^1.0.12",
+    "react-email": "^4.0.0"
+  };
+}
+
 // src/core/chat-schema.ts
 import path3 from "path";
 import { readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
@@ -552,7 +582,7 @@ import { readdir as readdir3, readFile as readFile4, writeFile as writeFile4 } f
 import path4 from "path";
 import { readdir as readdir2, readFile as readFile3, writeFile as writeFile3 } from "fs/promises";
 var defaultManifest = {
-  cli: "0.5.0",
+  cli: "0.6.1",
   defaultLocale: "vi",
   locales: ["vi"],
   namespaces: ["common", "auth", "example"],
@@ -617,9 +647,7 @@ async function reconcileManifest(projectDir) {
     ]
   };
   merged.defaultLocale = merged.locales.includes(merged.defaultLocale) ? merged.defaultLocale : merged.locales[0] ?? "vi";
-  merged.modules = [...new Set(merged.modules)].filter(
-    (moduleId) => moduleId !== "supabase"
-  );
+  merged.modules = [...new Set(merged.modules)].map((moduleId) => moduleId === "resend" ? "email" : moduleId).filter((moduleId) => moduleId !== "supabase");
   merged.features = [...new Set(merged.features)];
   await writeManifest(projectDir, merged);
   return merged;
@@ -1419,166 +1447,239 @@ function registerAddCommand(program2) {
       "No migration was executed. Run your migration command manually when ready."
     );
   });
-  add.command("module").description("Add optional modules using interactive multi-select").option("--module <module...>", "Preselect module ids").option("--yes", "Skip prompts").action(async (options) => {
-    const cwd = process.cwd();
-    const hasSrc = await pathExists(path7.join(cwd, "src"));
-    const hasPackageJson = await pathExists(path7.join(cwd, "package.json"));
-    if (!hasSrc || !hasPackageJson) {
-      log.error("Run this command from your generated Next.js project root.");
-      process.exitCode = 1;
-      return;
-    }
-    const validIds = new Set(
-      optionalModules.map((module) => module.id)
-    );
-    const requestedValues = options.module ? options.module.flatMap((value) => value.split(",")).map((value) => value.trim()).filter(Boolean) : [];
-    const requestedIds = [];
-    for (const moduleId of requestedValues) {
-      if (validIds.has(moduleId)) {
-        requestedIds.push(moduleId);
-        continue;
-      }
-      if (moduleId === "supabase") {
-        log.info(
-          "Supabase is now part of the base template; only supabase-realtime is optional."
+  add.command("module").description("Add optional modules using interactive multi-select").option("--module <module...>", "Preselect module ids").option(
+    "--email-provider <provider>",
+    "Email provider for email module: resend or smtp"
+  ).option("--yes", "Skip prompts").action(
+    async (options) => {
+      const cwd = process.cwd();
+      const hasSrc = await pathExists(path7.join(cwd, "src"));
+      const hasPackageJson = await pathExists(path7.join(cwd, "package.json"));
+      if (!hasSrc || !hasPackageJson) {
+        log.error(
+          "Run this command from your generated Next.js project root."
         );
-        continue;
+        process.exitCode = 1;
+        return;
       }
-      if (!validIds.has(moduleId)) {
-        log.error(`Unknown module: ${moduleId}`);
+      const validIds = new Set(
+        optionalModules.map((module) => module.id)
+      );
+      const requestedValues = options.module ? options.module.flatMap((value) => value.split(",")).map((value) => value.trim()).filter(Boolean) : [];
+      const requestedIds = [];
+      let emailProviderFromModuleAlias;
+      const optionEmailProvider = options.emailProvider ? options.emailProvider.trim().toLowerCase() : void 0;
+      if (optionEmailProvider && !isEmailProvider(optionEmailProvider)) {
+        log.error(`Unknown email provider: ${options.emailProvider}`);
         process.exitCode = 1;
         return;
       }
-    }
-    startPrompt("NexTCLI optional modules");
-    const rawModules = requestedIds.length > 0 ? [...new Set(requestedIds)] : options.yes ? [] : await askMultiSelect(
-      "Select modules to add:",
-      optionalModules.map((module) => ({
-        value: module.id,
-        label: module.label,
-        hint: module.description
-      })),
-      []
-    );
-    const { selectedModules, autoAddedModules } = normalizeModuleSelection(rawModules);
-    if (selectedModules.length === 0) {
-      finishPrompt("No modules selected.");
-      return;
-    }
-    const skippedConflictsByModule = [];
-    let copiedFileCount = 0;
-    for (const moduleId of selectedModules) {
-      const module = getModuleById(moduleId);
-      const copyReport = await copyDirectorySafely(module.templatePath, cwd);
-      copiedFileCount += copyReport.copiedCount;
-      if (copyReport.skippedConflicts.length > 0) {
-        skippedConflictsByModule.push({
-          moduleId,
-          paths: copyReport.skippedConflicts
-        });
+      for (const moduleId of requestedValues) {
+        if (validIds.has(moduleId)) {
+          requestedIds.push(moduleId);
+          continue;
+        }
+        if (moduleId === "supabase") {
+          log.info(
+            "Supabase is now part of the base template; only supabase-realtime is optional."
+          );
+          continue;
+        }
+        if (moduleId === "resend") {
+          log.info(
+            "Module 'resend' is now 'email'; selecting email with provider resend."
+          );
+          requestedIds.push("email");
+          emailProviderFromModuleAlias = "resend";
+          continue;
+        }
+        if (!validIds.has(moduleId)) {
+          log.error(`Unknown module: ${moduleId}`);
+          process.exitCode = 1;
+          return;
+        }
       }
-    }
-    let chatSchemaStatus;
-    if (selectedModules.includes("chat")) {
-      chatSchemaStatus = await ensureChatSchemaInProject(cwd);
-    }
-    const envTargets = [".env", ".env.example", ".env.development"];
-    for (const moduleId of selectedModules) {
-      const module = getModuleById(moduleId);
-      if (Object.keys(module.env).length === 0) {
-        continue;
+      startPrompt("NexTCLI optional modules");
+      const rawModules = requestedIds.length > 0 ? [...new Set(requestedIds)] : options.yes ? [] : await askMultiSelect(
+        "Select modules to add:",
+        optionalModules.map((module) => ({
+          value: module.id,
+          label: module.label,
+          hint: module.description
+        })),
+        []
+      );
+      const { selectedModules, autoAddedModules } = normalizeModuleSelection(rawModules);
+      if (optionEmailProvider && !selectedModules.includes("email")) {
+        log.warn(
+          "Ignoring --email-provider because email module is not selected."
+        );
       }
-      for (const envFile of envTargets) {
-        const envPath = path7.join(cwd, envFile);
-        if (await pathExists(envPath)) {
-          await mergeEnvFile(envPath, module.env, {
-            header: `# --- module: ${module.id} ---`
+      let emailProvider;
+      if (selectedModules.includes("email")) {
+        if (emailProviderFromModuleAlias) {
+          emailProvider = emailProviderFromModuleAlias;
+        } else if (optionEmailProvider && isEmailProvider(optionEmailProvider)) {
+          emailProvider = optionEmailProvider;
+        } else if (options.yes) {
+          emailProvider = "resend";
+          log.info(
+            "No --email-provider supplied in --yes mode; defaulting email provider to resend."
+          );
+        } else {
+          emailProvider = await askSelect(
+            "Select email provider:",
+            [
+              {
+                value: "resend",
+                label: "Resend",
+                hint: "Transactional email API with React Email support"
+              },
+              {
+                value: "smtp",
+                label: "SMTP",
+                hint: "Use your SMTP relay credentials"
+              }
+            ],
+            "resend"
+          );
+        }
+      }
+      if (selectedModules.length === 0) {
+        finishPrompt("No modules selected.");
+        return;
+      }
+      const skippedConflictsByModule = [];
+      let copiedFileCount = 0;
+      for (const moduleId of selectedModules) {
+        const module = getModuleById(moduleId);
+        const copyReport = await copyDirectorySafely(
+          module.templatePath,
+          cwd
+        );
+        copiedFileCount += copyReport.copiedCount;
+        if (copyReport.skippedConflicts.length > 0) {
+          skippedConflictsByModule.push({
+            moduleId,
+            paths: copyReport.skippedConflicts
           });
         }
       }
-    }
-    const dependencyEntries = selectedModules.reduce(
-      (acc, moduleId) => {
+      let chatSchemaStatus;
+      if (selectedModules.includes("chat")) {
+        chatSchemaStatus = await ensureChatSchemaInProject(cwd);
+      }
+      const envTargets = [".env", ".env.example", ".env.development"];
+      for (const moduleId of selectedModules) {
         const module = getModuleById(moduleId);
+        const moduleEnv = moduleId === "email" && emailProvider ? getEmailProviderEnv(emailProvider) : module.env;
+        if (Object.keys(moduleEnv).length === 0) {
+          continue;
+        }
+        for (const envFile of envTargets) {
+          const envPath = path7.join(cwd, envFile);
+          if (await pathExists(envPath)) {
+            await mergeEnvFile(envPath, moduleEnv, {
+              header: `# --- module: ${module.id} ---`
+            });
+          }
+        }
+      }
+      const dependencyEntries = selectedModules.reduce((acc, moduleId) => {
+        const module = getModuleById(moduleId);
+        const emailDependencies = moduleId === "email" && emailProvider ? getEmailProviderDependencies(emailProvider) : {};
         return {
           ...acc,
+          ...emailDependencies,
           ...module.dependencies ?? {}
         };
-      },
-      {}
-    );
-    if (Object.keys(dependencyEntries).length > 0) {
-      await addDependencies(
-        path7.join(cwd, "package.json"),
-        dependencyEntries
-      );
-    }
-    const state = await detectProjectState(cwd);
-    const namespaceSet = new Set(state.namespaces);
-    for (const moduleId of selectedModules) {
-      const moduleTemplateMessages = path7.join(
-        getModuleById(moduleId).templatePath,
-        "messages/vi"
-      );
-      if (!await pathExists(moduleTemplateMessages)) {
-        continue;
+      }, {});
+      if (Object.keys(dependencyEntries).length > 0) {
+        await addDependencies(
+          path7.join(cwd, "package.json"),
+          dependencyEntries
+        );
       }
-      const files = await readdir4(moduleTemplateMessages, {
-        withFileTypes: true
-      });
-      for (const file of files) {
-        if (!file.isFile() || !file.name.endsWith(".json")) {
+      const state = await detectProjectState(cwd);
+      const namespaceSet = new Set(state.namespaces);
+      for (const moduleId of selectedModules) {
+        const moduleTemplateMessages = path7.join(
+          getModuleById(moduleId).templatePath,
+          "messages/vi"
+        );
+        if (!await pathExists(moduleTemplateMessages)) {
           continue;
         }
-        const namespace = file.name.replace(/\.json$/, "");
-        namespaceSet.add(namespace);
-        const templateData = JSON.parse(
-          await readFile6(
-            path7.join(moduleTemplateMessages, file.name),
-            "utf8"
+        const files = await readdir4(moduleTemplateMessages, {
+          withFileTypes: true
+        });
+        for (const file of files) {
+          if (!file.isFile() || !file.name.endsWith(".json")) {
+            continue;
+          }
+          const namespace = file.name.replace(/\.json$/, "");
+          namespaceSet.add(namespace);
+          const templateData = JSON.parse(
+            await readFile6(
+              path7.join(moduleTemplateMessages, file.name),
+              "utf8"
+            )
+          );
+          await writeNamespaceMessages(cwd, namespace, templateData);
+          await appendNamespace(cwd, namespace);
+        }
+      }
+      await writeManifest(cwd, {
+        ...state,
+        namespaces: [...namespaceSet],
+        modules: [
+          ...new Set(
+            [...state.modules, ...selectedModules].map(
+              (moduleId) => moduleId === "resend" ? "email" : moduleId
+            )
+          )
+        ]
+      });
+      const mergedModules = [
+        ...new Set(
+          [...state.modules, ...selectedModules].map(
+            (moduleId) => moduleId === "resend" ? "email" : moduleId
           )
+        )
+      ];
+      await mergeModuleSetupSections(cwd, selectedModules, mergedModules);
+      finishPrompt(`Added modules: ${selectedModules.join(", ")}`);
+      log.detail("Copied files", String(copiedFileCount));
+      if (autoAddedModules.length > 0) {
+        log.detail("Auto-added", autoAddedModules.join(", "));
+      }
+      if (emailProvider) {
+        log.detail("Email provider", emailProvider);
+      }
+      if (skippedConflictsByModule.length > 0) {
+        const totalSkipped = skippedConflictsByModule.reduce(
+          (total, item) => total + item.paths.length,
+          0
+        );
+        log.warn(
+          `Skipped ${totalSkipped} existing file(s). Existing project files were kept unchanged.`
         );
-        await writeNamespaceMessages(cwd, namespace, templateData);
-        await appendNamespace(cwd, namespace);
+        for (const conflict of skippedConflictsByModule) {
+          const preview = conflict.paths.slice(0, 3).join(", ");
+          const suffix = conflict.paths.length > 3 ? ", ..." : "";
+          log.detail(`Skipped (${conflict.moduleId})`, `${preview}${suffix}`);
+        }
       }
-    }
-    await writeManifest(cwd, {
-      ...state,
-      namespaces: [...namespaceSet],
-      modules: [.../* @__PURE__ */ new Set([...state.modules, ...selectedModules])]
-    });
-    const mergedModules = [
-      .../* @__PURE__ */ new Set([...state.modules, ...selectedModules])
-    ];
-    await mergeModuleSetupSections(cwd, selectedModules, mergedModules);
-    finishPrompt(`Added modules: ${selectedModules.join(", ")}`);
-    log.detail("Copied files", String(copiedFileCount));
-    if (autoAddedModules.length > 0) {
-      log.detail("Auto-added", autoAddedModules.join(", "));
-    }
-    if (skippedConflictsByModule.length > 0) {
-      const totalSkipped = skippedConflictsByModule.reduce(
-        (total, item) => total + item.paths.length,
-        0
-      );
-      log.warn(
-        `Skipped ${totalSkipped} existing file(s). Existing project files were kept unchanged.`
-      );
-      for (const conflict of skippedConflictsByModule) {
-        const preview = conflict.paths.slice(0, 3).join(", ");
-        const suffix = conflict.paths.length > 3 ? ", ..." : "";
-        log.detail(`Skipped (${conflict.moduleId})`, `${preview}${suffix}`);
+      if (chatSchemaStatus === "added") {
+        log.info(
+          "Optional chat schema block was appended to prisma/schema.prisma."
+        );
       }
-    }
-    if (chatSchemaStatus === "added") {
-      log.info(
-        "Optional chat schema block was appended to prisma/schema.prisma."
+      log.step(
+        "Next: run your package manager install to apply new dependencies."
       );
     }
-    log.step(
-      "Next: run your package manager install to apply new dependencies."
-    );
-  });
+  );
   add.command("language").description("Add locales and clone message files from Vietnamese").option("--locale <locale...>", "Preselect locales: en,ja,ko").option("--yes", "Skip prompts").action(async (options) => {
     const cwd = process.cwd();
     const hasMessages = await pathExists(path7.join(cwd, "messages"));
@@ -1821,6 +1922,25 @@ function registerCreateCommand(program2) {
       []
     );
     const { selectedModules, autoAddedModules } = normalizeModuleSelection2(rawModules);
+    let emailProvider;
+    if (selectedModules.includes("email")) {
+      emailProvider = await askSelect(
+        "Select email provider:",
+        [
+          {
+            value: "resend",
+            label: "Resend",
+            hint: "Transactional email API with React Email support"
+          },
+          {
+            value: "smtp",
+            label: "SMTP",
+            hint: "Use your SMTP relay credentials"
+          }
+        ],
+        "resend"
+      );
+    }
     const shouldInstall = await askConfirm("Install dependencies now?", true);
     await copyDirectory(templatePaths.base, targetPath);
     for (const moduleId of selectedModules) {
@@ -1834,13 +1954,14 @@ function registerCreateCommand(program2) {
     const envTargets = [".env", ".env.example", ".env.development"];
     for (const moduleId of selectedModules) {
       const module = getModuleById(moduleId);
-      if (Object.keys(module.env).length === 0) {
+      const moduleEnv = moduleId === "email" && emailProvider ? getEmailProviderEnv(emailProvider) : module.env;
+      if (Object.keys(moduleEnv).length === 0) {
         continue;
       }
       for (const envFile of envTargets) {
         const envPath = path8.join(targetPath, envFile);
         if (await pathExists(envPath)) {
-          await mergeEnvFile(envPath, module.env, {
+          await mergeEnvFile(envPath, moduleEnv, {
             header: `# --- module: ${module.id} ---`
           });
         }
@@ -1849,8 +1970,10 @@ function registerCreateCommand(program2) {
     const dependencyEntries = selectedModules.reduce(
       (acc, moduleId) => {
         const module = getModuleById(moduleId);
+        const emailDependencies = moduleId === "email" && emailProvider ? getEmailProviderDependencies(emailProvider) : {};
         return {
           ...acc,
+          ...emailDependencies,
           ...module.dependencies ?? {}
         };
       },
@@ -1866,7 +1989,7 @@ function registerCreateCommand(program2) {
     await replaceTokensInDirectory(targetPath, {
       __PROJECT_NAME__: projectSlug,
       __BETTER_AUTH_SECRET__: betterAuthSecret,
-      __NEXTCLI_VERSION__: "0.5.0"
+      __NEXTCLI_VERSION__: "0.6.1"
     });
     await mergeModuleSetupSections(
       targetPath,
@@ -1877,7 +2000,7 @@ function registerCreateCommand(program2) {
     if (manifest) {
       await writeManifest(targetPath, {
         ...manifest,
-        cli: "0.5.0",
+        cli: "0.6.1",
         modules: selectedModules
       });
     }
@@ -1897,6 +2020,9 @@ function registerCreateCommand(program2) {
     if (autoAddedModules.length > 0) {
       log.detail("Auto-added", autoAddedModules.join(", "));
     }
+    if (emailProvider) {
+      log.detail("Email provider", emailProvider);
+    }
     if (chatSchemaStatus === "added") {
       log.info(
         "Optional chat schema block was appended to prisma/schema.prisma."
@@ -2119,7 +2245,7 @@ var NexTCLICommand = class _NexTCLICommand extends Command {
 
 // src/cli.ts
 var program = new NexTCLICommand();
-program.name("nextcli").description("Scaffold outsource-ready Next.js projects").version("0.5.0");
+program.name("nextcli").description("Scaffold outsource-ready Next.js projects").version("0.6.1");
 registerCreateCommand(program);
 registerAddCommand(program);
 registerMigrateCommand(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinhnguyencth1204/nextcli",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "CLI scaffolder for outsourced Next.js projects",
   "type": "module",
   "bin": {

package/templates/features/{resend/src/lib/resend/send-email.ts → email/src/lib/email/providers/resend.ts}

@@ -1,39 +1,19 @@
-import type { ReactNode } from "react";
 import type { CreateEmailOptions } from "resend";
+import { Resend } from "resend";
 
-import { resend } from "@/lib/resend/client";
-import { getResendFromAddress } from "@/lib/resend/config";
+import type { SendEmailInput, SendEmailResult } from "@/lib/email/types";
 
-export type ResendError = {
-  message: string;
-  name: string;
-};
+const apiKey = process.env.RESEND_API_KEY?.trim();
+const resend = apiKey ? new Resend(apiKey) : null;
 
-export type SendEmailResult = {
-  data: { id: string } | null;
-  error: ResendError | null;
-};
+function getResendFromAddress(): string | null {
+  const from = process.env.RESEND_FROM_EMAIL?.trim();
+  return from || null;
+}
 
-export type SendEmailInput = {
-  to: string | string[];
-  subject: string;
-  html?: string;
-  text?: string;
-  /** Pass as a function call: WelcomeEmail({ name }), not JSX. */
-  react?: ReactNode;
-  cc?: string | string[];
-  bcc?: string | string[];
-  replyTo?: string | string[];
-  scheduledAt?: string;
-  headers?: Record<string, string>;
-  tags?: Array<{ name: string; value: string }>;
-  attachments?: CreateEmailOptions["attachments"];
-  template?: {
-    id: string;
-    variables?: Record<string, string | number>;
-  };
-  idempotencyKey?: string;
-};
+export function isResendConfigured(): boolean {
+  return Boolean(process.env.RESEND_API_KEY?.trim() && getResendFromAddress());
+}
 
 function notConfigured(message: string): SendEmailResult {
   return {
@@ -58,7 +38,7 @@ function countContentFields(input: SendEmailInput): number {
   return count;
 }
 
-export async function sendEmail(
+export async function sendWithResend(
   input: SendEmailInput,
 ): Promise<SendEmailResult> {
   if (!resend) {
@@ -101,7 +81,7 @@ export async function sendEmail(
         scheduledAt: rest.scheduledAt,
         headers: rest.headers,
         tags: rest.tags,
-        attachments: rest.attachments,
+        attachments: rest.attachments as CreateEmailOptions["attachments"],
       }
     : {
         from,
@@ -116,7 +96,7 @@ export async function sendEmail(
         scheduledAt: rest.scheduledAt,
         headers: rest.headers,
         tags: rest.tags,
-        attachments: rest.attachments,
+        attachments: rest.attachments as CreateEmailOptions["attachments"],
       };
 
   const result = await resend.emails.send(
@@ -129,18 +109,3 @@ export async function sendEmail(
     error: result.error,
   };
 }
-
-export async function sendWelcomeEmail(input: {
-  to: string;
-  name: string;
-  idempotencyKey?: string;
-}): Promise<SendEmailResult> {
-  const { WelcomeEmail } = await import("@/emails/welcome-email");
-
-  return sendEmail({
-    to: input.to,
-    subject: "Welcome",
-    react: WelcomeEmail({ name: input.name }),
-    idempotencyKey: input.idempotencyKey ?? `welcome-user/${input.to}`,
-  });
-}

package/templates/features/email/src/lib/email/providers/smtp.ts

@@ -0,0 +1,116 @@
+import nodemailer from "nodemailer";
+
+import type { SendEmailInput, SendEmailResult } from "@/lib/email/types";
+
+type SmtpConfig = {
+  host: string;
+  port: number;
+  user: string;
+  password: string;
+  from: string;
+};
+
+function readSmtpConfig(): SmtpConfig | null {
+  const host = process.env.SMTP_HOST?.trim();
+  const portRaw = process.env.SMTP_PORT?.trim() || "587";
+  const user = process.env.SMTP_USER?.trim();
+  const password = process.env.SMTP_PASSWORD?.trim();
+  const from = process.env.SMTP_FROM?.trim();
+  const port = Number.parseInt(portRaw, 10);
+
+  if (!host || !user || !password || !from || Number.isNaN(port)) {
+    return null;
+  }
+
+  return { host, port, user, password, from };
+}
+
+export function isSmtpConfigured(): boolean {
+  return readSmtpConfig() !== null;
+}
+
+function notConfigured(message: string): SendEmailResult {
+  return {
+    data: null,
+    error: { message, name: "NOT_CONFIGURED" },
+  };
+}
+
+function validationError(message: string): SendEmailResult {
+  return {
+    data: null,
+    error: { message, name: "VALIDATION_ERROR" },
+  };
+}
+
+function countContentFields(input: SendEmailInput): number {
+  let count = 0;
+  if (input.html) count += 1;
+  if (input.text) count += 1;
+  if (input.react) count += 1;
+  if (input.template) count += 1;
+  return count;
+}
+
+export async function sendWithSmtp(
+  input: SendEmailInput,
+): Promise<SendEmailResult> {
+  const config = readSmtpConfig();
+  if (!config) {
+    return notConfigured(
+      "SMTP is not configured. Set SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, and SMTP_FROM.",
+    );
+  }
+
+  const contentCount = countContentFields(input);
+  if (contentCount === 0) {
+    return validationError("Provide one of html or text for SMTP email body.");
+  }
+  if (contentCount > 1) {
+    return validationError(
+      "Provide only one body source: html or text for SMTP transport.",
+    );
+  }
+  if (input.react || input.template) {
+    return validationError(
+      "SMTP adapter supports html/text only. Convert React/template content before sending.",
+    );
+  }
+
+  const transporter = nodemailer.createTransport({
+    host: config.host,
+    port: config.port,
+    secure: config.port === 465,
+    auth: {
+      user: config.user,
+      pass: config.password,
+    },
+  });
+
+  try {
+    const info = await transporter.sendMail({
+      from: config.from,
+      to: input.to,
+      subject: input.subject,
+      html: input.html,
+      text: input.text,
+      cc: input.cc,
+      bcc: input.bcc,
+      replyTo: input.replyTo,
+      headers: input.headers,
+      attachments: input.attachments as never,
+    });
+    return {
+      data: { id: info.messageId || `smtp-${Date.now()}` },
+      error: null,
+    };
+  } catch (error) {
+    return {
+      data: null,
+      error: {
+        name: "SMTP_ERROR",
+        message: error instanceof Error ? error.message : "SMTP send failed.",
+      },
+    };
+  }
+}

package/templates/features/email/src/lib/email/send-email.ts

@@ -0,0 +1,68 @@
+import type {
+  EmailProvider,
+  SendEmailInput,
+  SendEmailResult,
+} from "@/lib/email/types";
+import { sendWithResend } from "@/lib/email/providers/resend";
+import { sendWithSmtp } from "@/lib/email/providers/smtp";
+
+function notConfigured(message: string): SendEmailResult {
+  return {
+    data: null,
+    error: { message, name: "NOT_CONFIGURED" },
+  };
+}
+
+function resolveEmailProvider(): EmailProvider | null {
+  const provider = process.env.EMAIL_PROVIDER?.trim().toLowerCase();
+  if (provider === "resend" || provider === "smtp") {
+    return provider;
+  }
+  return null;
+}
+
+export async function sendEmail(
+  input: SendEmailInput,
+): Promise<SendEmailResult> {
+  const provider = resolveEmailProvider();
+  if (!provider) {
+    return notConfigured(
+      "Email provider not configured. Set EMAIL_PROVIDER to 'resend' or 'smtp'.",
+    );
+  }
+
+  if (provider === "smtp") {
+    return sendWithSmtp(input);
+  }
+
+  return sendWithResend(input);
+}
+
+export async function sendWelcomeEmail(input: {
+  to: string;
+  name: string;
+  idempotencyKey?: string;
+}): Promise<SendEmailResult> {
+  const provider = resolveEmailProvider();
+  if (!provider) {
+    return notConfigured(
+      "Email provider not configured. Set EMAIL_PROVIDER to 'resend' or 'smtp'.",
+    );
+  }
+
+  if (provider === "smtp") {
+    return sendWithSmtp({
+      to: input.to,
+      subject: "Welcome",
+      text: `Welcome, ${input.name}. Thanks for joining.`,
+    });
+  }
+
+  const { WelcomeEmail } = await import("@/emails/welcome-email");
+  return sendWithResend({
+    to: input.to,
+    subject: "Welcome",
+    react: WelcomeEmail({ name: input.name }),
+    idempotencyKey: input.idempotencyKey ?? `welcome-user/${input.to}`,
+  });
+}

package/templates/features/email/src/lib/email/types.ts

@@ -0,0 +1,34 @@
+import type { ReactNode } from "react";
+
+export type EmailProvider = "resend" | "smtp";
+
+export type EmailError = {
+  message: string;
+  name: string;
+};
+
+export type SendEmailResult = {
+  data: { id: string } | null;
+  error: EmailError | null;
+};
+
+export type SendEmailInput = {
+  to: string | string[];
+  subject: string;
+  html?: string;
+  text?: string;
+  /** Pass as a function call: WelcomeEmail({ name }), not JSX. */
+  react?: ReactNode;
+  cc?: string | string[];
+  bcc?: string | string[];
+  replyTo?: string | string[];
+  scheduledAt?: string;
+  headers?: Record<string, string>;
+  tags?: Array<{ name: string; value: string }>;
+  attachments?: unknown;
+  template?: {
+    id: string;
+    variables?: Record<string, string | number>;
+  };
+  idempotencyKey?: string;
+};

package/templates/next-base/.env

@@ -1,7 +1,10 @@
 # --- Database (Supabase) ---
-DATABASE_URL="postgresql://postgres:your-supabase-db-password@db.your-project-ref.supabase.co:5432/postgres"
+DATABASE_URL="postgresql://postgres.your-project-ref:your-supabase-db-password@aws-0-us-east-1.pooler.supabase.com:6543/postgres?pgbouncer=true"
+DIRECT_URL="postgresql://postgres.your-project-ref:your-supabase-db-password@aws-0-us-east-1.pooler.supabase.com:5432/postgres"
 NEXT_PUBLIC_SUPABASE_URL=""
+# Public/browser-safe anon key from Supabase Project Settings -> API -> anon public
 NEXT_PUBLIC_SUPABASE_ANON_KEY=""
+# Storage bucket name used by the app (default scaffold bucket name: public)
 NEXT_PUBLIC_SUPABASE_STORAGE_BUCKET="public"
 
 # --- Auth ---
@@ -10,4 +13,4 @@ BETTER_AUTH_URL="http://localhost:3000"
 
 # --- App ---
 NEXT_PUBLIC_APP_URL="http://localhost:3000"
-NEXT_PUBLIC_DEFAULT_LOCALE="en"
+NEXT_PUBLIC_DEFAULT_LOCALE="vi"

package/templates/next-base/.env.development

@@ -1,7 +1,10 @@
 # --- Database (Supabase) ---
-DATABASE_URL="postgresql://postgres:your-supabase-db-password@db.your-project-ref.supabase.co:5432/postgres"
+DATABASE_URL="postgresql://postgres.your-project-ref:your-supabase-db-password@aws-0-us-east-1.pooler.supabase.com:6543/postgres?pgbouncer=true"
+DIRECT_URL="postgresql://postgres.your-project-ref:your-supabase-db-password@aws-0-us-east-1.pooler.supabase.com:5432/postgres"
 NEXT_PUBLIC_SUPABASE_URL=""
+# Public/browser-safe anon key from Supabase Project Settings -> API -> anon public
 NEXT_PUBLIC_SUPABASE_ANON_KEY=""
+# Storage bucket name used by the app (default scaffold bucket name: public)
 NEXT_PUBLIC_SUPABASE_STORAGE_BUCKET="public"
 
 # --- Auth ---
@@ -10,4 +13,4 @@ BETTER_AUTH_URL="http://localhost:3000"
 
 # --- App ---
 NEXT_PUBLIC_APP_URL="http://localhost:3000"
-NEXT_PUBLIC_DEFAULT_LOCALE="en"
+NEXT_PUBLIC_DEFAULT_LOCALE="vi"

package/templates/next-base/.env.example

@@ -1,7 +1,10 @@
 # --- Database (Supabase) ---
-DATABASE_URL="postgresql://postgres:your-supabase-db-password@db.your-project-ref.supabase.co:5432/postgres"
+DATABASE_URL="postgresql://postgres.your-project-ref:your-supabase-db-password@aws-0-us-east-1.pooler.supabase.com:6543/postgres?pgbouncer=true"
+DIRECT_URL="postgresql://postgres.your-project-ref:your-supabase-db-password@aws-0-us-east-1.pooler.supabase.com:5432/postgres"
 NEXT_PUBLIC_SUPABASE_URL=""
+# Public/browser-safe anon key from Supabase Project Settings -> API -> anon public
 NEXT_PUBLIC_SUPABASE_ANON_KEY=""
+# Storage bucket name used by the app (default scaffold bucket name: public)
 NEXT_PUBLIC_SUPABASE_STORAGE_BUCKET="public"
 
 # --- Auth ---
@@ -10,4 +13,4 @@ BETTER_AUTH_URL="http://localhost:3000"
 
 # --- App ---
 NEXT_PUBLIC_APP_URL="http://localhost:3000"
-NEXT_PUBLIC_DEFAULT_LOCALE="en"
+NEXT_PUBLIC_DEFAULT_LOCALE="vi"

package/templates/next-base/PROJECT_STRUCTURE.md

@@ -34,15 +34,15 @@ Generated by NexTCLI. Folders marked **(module)** or **(feature)** appear only w
 
 ## `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/`                  | Supabase client + Storage helpers                 |
-| `resend/`                    | **(module: `resend`)** email client + send helper |
+| 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/`                  | Supabase client + Storage helpers                               |
+| `email/`                     | **(module: `email`)** provider-agnostic email helper + adapters |
 
 ## `src/features/` vs `src/example/`
 
@@ -67,7 +67,7 @@ Locale config with `nextcli:locales` / `nextcli:namespaces` markers (patched by
 
 ## `src/emails/`
 
-**(module: `resend`)** React Email templates.
+**(module: `email`)** React Email templates.
 
 ## Optional modules (via `nextcli add module`)
 
@@ -76,7 +76,7 @@ Locale config with `nextcli:locales` / `nextcli:namespaces` markers (patched by
 | `chat`              | Chat routes, hooks, Prisma chat models (+ auto `supabase-realtime`) |
 | `supabase-realtime` | Realtime channel helpers                                            |
 | `seo`               | robots/sitemap/JSON-LD helpers                                      |
-| `resend`            | `src/lib/resend/*`, `src/emails/*`                                  |
+| `email`             | `src/lib/email/*`, `src/emails/*` (provider: SMTP or Resend)        |
 
 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).
 

package/templates/next-base/SETUP.md

@@ -4,7 +4,7 @@ Quick reference for env vars and branding after `nextcli create`.
 
 ## First run (required)
 
-1. Create a Supabase project and set `DATABASE_URL` in `.env`.
+1. Create a Supabase project and set `DATABASE_URL` and `DIRECT_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.
 
@@ -23,15 +23,16 @@ Quick reference for env vars and branding after `nextcli create`.
 
 Set in `.env` / `.env.development` (secrets are generated at create time).
 
-| Variable                              | Purpose                    | Where to get                                                           |
-| ------------------------------------- | -------------------------- | ---------------------------------------------------------------------- |
-| `DATABASE_URL`                        | Supabase Postgres database | Supabase Dashboard → Project Settings → Database → Connection string   |
-| `NEXT_PUBLIC_SUPABASE_URL`            | Supabase client URL        | Supabase Dashboard → Project Settings → API → Project URL              |
-| `NEXT_PUBLIC_SUPABASE_ANON_KEY`       | Supabase browser anon key  | Same page → Project API keys → `anon` `public`                         |
-| `NEXT_PUBLIC_SUPABASE_STORAGE_BUCKET` | Supabase Storage bucket    | Storage → create bucket → use bucket name (default scaffold: `public`) |
-| `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                                                |
+| Variable                              | Purpose                                                                               | Where to get                                                                           |
+| ------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `DATABASE_URL`                        | Postgres URL for app runtime and Prisma CLI (`prisma.config.ts` → `datasource.url`)   | Supabase Dashboard → Connect → ORMs → Prisma → pooled URL (`:6543`, `?pgbouncer=true`) |
+| `DIRECT_URL`                          | Direct/session Postgres URL from Supabase Connect (keep in env for reference/tooling) | Supabase Dashboard → Connect → ORMs → Prisma → direct/session URL (`:5432`)            |
+| `NEXT_PUBLIC_SUPABASE_URL`            | Supabase client URL                                                                   | Supabase Dashboard → Project Settings → API → Project URL                              |
+| `NEXT_PUBLIC_SUPABASE_ANON_KEY`       | Browser-safe anon API key (public key used by client SDK)                             | Same page → Project API keys → `anon` `public`                                         |
+| `NEXT_PUBLIC_SUPABASE_STORAGE_BUCKET` | Storage bucket name used by app uploads/reads (`public` is the default bucket name)   | Storage → create/select bucket → use that bucket name                                  |
+| `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
 
@@ -65,13 +66,29 @@ Uses the base Supabase URL/anon key. Enable Realtime on tables in Supabase Dashb
 
 No extra env keys. Edit `src/app/robots.ts`, `sitemap.ts`, and JSON-LD helpers after add.
 
-### Module: Resend email (`resend`)
+### Module: Email module (`email`)
+
+| Variable         | Where to get       |
+| ---------------- | ------------------ |
+| `EMAIL_PROVIDER` | `resend` or `smtp` |
+
+When `EMAIL_PROVIDER=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>` |
 
+When `EMAIL_PROVIDER=smtp`:
+
+| Variable        | Where to get                                 |
+| --------------- | -------------------------------------------- |
+| `SMTP_HOST`     | SMTP provider host (Mailgun, SES, etc.)      |
+| `SMTP_PORT`     | SMTP provider port (commonly `587` or `465`) |
+| `SMTP_USER`     | SMTP username                                |
+| `SMTP_PASSWORD` | SMTP password or app-specific token          |
+| `SMTP_FROM`     | Sender email (or `Name <mail@domain.com>`)   |
+
 <!-- nextcli:module-env:end -->
 
 ## After adding modules

package/templates/features/resend/src/lib/resend/client.ts

@@ -1,5 +0,0 @@
-import { Resend } from "resend";
-
-const apiKey = process.env.RESEND_API_KEY?.trim();
-
-export const resend = apiKey ? new Resend(apiKey) : null;

package/templates/features/resend/src/lib/resend/config.ts

@@ -1,8 +0,0 @@
-export function getResendFromAddress(): string | null {
-  const from = process.env.RESEND_FROM_EMAIL?.trim();
-  return from || null;
-}
-
-export function isResendConfigured(): boolean {
-  return Boolean(process.env.RESEND_API_KEY?.trim() && getResendFromAddress());
-}