create-nextdevtpl 2.6.0

package/template/biome.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.3.11/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": true,
+    "includes": [
+      "**/*.ts",
+      "**/*.tsx",
+      "**/*.js",
+      "**/*.jsx",
+      "**/*.json",
+      "cloudflare/**/*.mjs",
+      "!.next",
+      "!.open-next",
+      "!packages/*/dist",
+      "!packages/*/template",
+      "!worker-configuration.d.ts"
+    ]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 80
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "correctness": {
+        "noUnusedImports": "error",
+        "noUnusedVariables": "error",
+        "useExhaustiveDependencies": "warn"
+      },
+      "style": {
+        "noNonNullAssertion": "off",
+        "useConst": "error",
+        "useImportType": "error"
+      },
+      "suspicious": {
+        "noExplicitAny": "error"
+      },
+      "a11y": {
+        "recommended": true
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "semicolons": "always",
+      "trailingCommas": "es5"
+    }
+  },
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": {
+          "level": "on"
+        }
+      }
+    }
+  }
+}

package/template/cloudflare/templates/logger.ts

@@ -0,0 +1,162 @@
+type LogData = Record<string, unknown>;
+type LogLevel = "debug" | "error" | "fatal" | "info" | "warn";
+type ConsoleMethod = "debug" | "error" | "log" | "warn";
+
+export interface Logger {
+  child(context: LogData): Logger;
+  debug(dataOrMessage: LogData | string, message?: string): void;
+  error(dataOrMessage: LogData | string, message?: string): void;
+  fatal(dataOrMessage: LogData | string, message?: string): void;
+  info(dataOrMessage: LogData | string, message?: string): void;
+  warn(dataOrMessage: LogData | string, message?: string): void;
+}
+
+const CONSOLE_METHODS: Readonly<Record<LogLevel, ConsoleMethod>> = {
+  debug: "debug",
+  error: "error",
+  fatal: "error",
+  info: "log",
+  warn: "warn",
+};
+
+function writeLog(
+  level: LogLevel,
+  context: LogData,
+  dataOrMessage: LogData | string,
+  message?: string
+): void {
+  const data =
+    typeof dataOrMessage === "string"
+      ? context
+      : { ...context, ...dataOrMessage };
+  const text = typeof dataOrMessage === "string" ? dataOrMessage : message;
+  const details = Object.keys(data).length > 0 ? data : undefined;
+  const output = console[CONSOLE_METHODS[level]];
+
+  if (text && details) {
+    output(text, details);
+    return;
+  }
+  if (text) {
+    output(text);
+    return;
+  }
+  if (details) output(details);
+}
+
+function createLogger(context: LogData = {}): Logger {
+  return {
+    child(childContext) {
+      return createLogger({ ...context, ...childContext });
+    },
+    debug(dataOrMessage, message) {
+      writeLog("debug", context, dataOrMessage, message);
+    },
+    error(dataOrMessage, message) {
+      writeLog("error", context, dataOrMessage, message);
+    },
+    fatal(dataOrMessage, message) {
+      writeLog("fatal", context, dataOrMessage, message);
+    },
+    info(dataOrMessage, message) {
+      writeLog("info", context, dataOrMessage, message);
+    },
+    warn(dataOrMessage, message) {
+      writeLog("warn", context, dataOrMessage, message);
+    },
+  };
+}
+
+export const logger = createLogger({
+  env: process.env.NODE_ENV,
+  service: "nextdevtpl",
+});
+
+export function createContextLogger(context: LogData): Logger {
+  return logger.child(context);
+}
+
+export function createRequestLogger(request: Request): Logger {
+  const url = new URL(request.url);
+  return logger.child({
+    requestId: crypto.randomUUID(),
+    method: request.method,
+    path: url.pathname,
+    userAgent: request.headers.get("user-agent")?.slice(0, 100),
+  });
+}
+
+export type BusinessEvent =
+  | "user.signup"
+  | "user.login"
+  | "user.logout"
+  | "payment.checkout.started"
+  | "payment.checkout.completed"
+  | "payment.credits.already_granted"
+  | "payment.credits.grant_success"
+  | "payment.subscription.created"
+  | "payment.subscription.canceled"
+  | "payment.subscription.past_due"
+  | "payment.subscription.paused"
+  | "payment.subscription.upserted"
+  | "credits.purchased"
+  | "credits.consumed"
+  | "credits.expired"
+  | "ticket.created"
+  | "ticket.replied"
+  | "ticket.closed"
+  | "email.sent"
+  | "file.uploaded"
+  | "file.deleted"
+  | "admin.user.banned"
+  | "admin.user.unbanned";
+
+export function logEvent(event: BusinessEvent, data?: LogData): void {
+  logger.info({ event, ...data }, `Event: ${event}`);
+}
+
+export function logError(error: unknown, context?: LogData): void {
+  if (error instanceof Error) {
+    logger.error(
+      {
+        err: {
+          name: error.name,
+          message: error.message,
+          stack: error.stack,
+        },
+        ...context,
+      },
+      error.message
+    );
+    return;
+  }
+  logger.error({ err: error, ...context }, "Unknown error");
+}
+
+export function logWarn(message: string, data?: LogData): void {
+  logger.warn(data ?? {}, message);
+}
+
+export function logDebug(message: string, data?: LogData): void {
+  logger.debug(data ?? {}, message);
+}
+
+export function logApiResponse(
+  request: Request,
+  response: Response,
+  duration: number
+): void {
+  const url = new URL(request.url);
+  const level =
+    response.status >= 500 ? "error" : response.status >= 400 ? "warn" : "info";
+
+  logger[level](
+    {
+      method: request.method,
+      path: url.pathname,
+      status: response.status,
+      duration,
+    },
+    `${request.method} ${url.pathname} ${response.status} ${duration}ms`
+  );
+}

package/template/cloudflare/templates/mail/server.ts

@@ -0,0 +1,6 @@
+export {
+  createResetPasswordEmail,
+  createVerifyEmail,
+} from "./templates";
+export { sendEmail } from "./utils";
+export type { SendEmailParams, SendEmailResult } from "./utils";

package/template/cloudflare/templates/mail/templates.ts

@@ -0,0 +1,87 @@
+export interface RenderedEmail {
+  html: string;
+  text: string;
+}
+
+interface ActionEmailParams {
+  actionLabel: string;
+  actionUrl: string;
+  expiresIn: string;
+  greeting: string;
+  message: string;
+  title: string;
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+function createActionEmail(params: ActionEmailParams): RenderedEmail {
+  const actionLabel = escapeHtml(params.actionLabel);
+  const actionUrl = escapeHtml(params.actionUrl);
+  const expiresIn = escapeHtml(params.expiresIn);
+  const greeting = escapeHtml(params.greeting);
+  const message = escapeHtml(params.message);
+  const title = escapeHtml(params.title);
+
+  return {
+    html: [
+      '<!doctype html><html><body style="background:#fff;color:#111827;font-family:Arial,sans-serif">',
+      '<main style="border:1px solid #e5e7eb;border-radius:8px;margin:40px auto;max-width:576px;padding:32px">',
+      '<h1 style="text-align:center">NextDevTpl</h1>',
+      `<h2>${title}</h2>`,
+      `<p>${greeting}</p>`,
+      `<p>${message}</p>`,
+      '<p style="text-align:center">',
+      `<a href="${actionUrl}" style="background:#7c3aed;border-radius:6px;color:#fff;display:inline-block;padding:12px 24px;text-decoration:none">${actionLabel}</a>`,
+      "</p>",
+      `<p style="color:#6b7280;font-size:14px;text-align:center">This link will expire in ${expiresIn}.</p>`,
+      `<p style="color:#6b7280;font-size:12px;word-break:break-all">If the button does not work, open: ${actionUrl}</p>`,
+      '<p style="color:#9ca3af;font-size:12px;text-align:center">If you did not request this email, you can ignore it.</p>',
+      "</main></body></html>",
+    ].join(""),
+    text: [
+      params.title,
+      "",
+      params.greeting,
+      params.message,
+      "",
+      `${params.actionLabel}: ${params.actionUrl}`,
+      "",
+      `This link will expire in ${params.expiresIn}.`,
+    ].join("\n"),
+  };
+}
+
+export function createResetPasswordEmail(params: {
+  name: string;
+  resetUrl: string;
+}): RenderedEmail {
+  return createActionEmail({
+    actionLabel: "Reset Password",
+    actionUrl: params.resetUrl,
+    expiresIn: "1 hour",
+    greeting: `Hi ${params.name},`,
+    message: "We received a request to reset your password.",
+    title: "Reset Your Password",
+  });
+}
+
+export function createVerifyEmail(params: {
+  name: string;
+  verifyUrl: string;
+}): RenderedEmail {
+  return createActionEmail({
+    actionLabel: "Verify Email",
+    actionUrl: params.verifyUrl,
+    expiresIn: "24 hours",
+    greeting: `Hi ${params.name},`,
+    message: "Please verify your email address to keep your account secure.",
+    title: "Verify Your Email",
+  });
+}

package/template/cloudflare/templates/mail/utils.ts

@@ -0,0 +1,69 @@
+import type { MailAddress } from "@/core/services";
+import { mailService } from "@/services/mail";
+
+import type { RenderedEmail } from "./templates";
+
+export const DEFAULT_FROM_EMAIL =
+  process.env.EMAIL_FROM ?? "NextDevTpl <noreply@example.com>";
+
+export interface SendEmailParams {
+  bcc?: string | string[];
+  cc?: string | string[];
+  content: RenderedEmail;
+  force?: boolean;
+  from?: string;
+  replyTo?: string | string[];
+  subject: string;
+  to: string | string[];
+}
+
+export interface SendEmailResult {
+  error?: string;
+  id?: string;
+  simulated?: boolean;
+  success: boolean;
+}
+
+function parseMailAddress(value: string): MailAddress {
+  const match = /^\s*(.*?)\s*<([^>]+)>\s*$/.exec(value);
+  const email = match?.[2];
+  const name = match?.[1]?.trim();
+
+  if (!email) return { email: value.trim() };
+  return name ? { email, name } : { email };
+}
+
+function toArray(value: string | string[]): string[] {
+  return Array.isArray(value) ? value : [value];
+}
+
+export async function sendEmail(
+  params: SendEmailParams
+): Promise<SendEmailResult> {
+  if (process.env.NODE_ENV === "development" && !params.force) {
+    console.log("Email preview", {
+      from: params.from ?? DEFAULT_FROM_EMAIL,
+      subject: params.subject,
+      to: params.to,
+    });
+    return { simulated: true, success: true };
+  }
+
+  try {
+    const result = await mailService.send({
+      from: parseMailAddress(params.from ?? DEFAULT_FROM_EMAIL),
+      to: toArray(params.to),
+      subject: params.subject,
+      html: params.content.html,
+      text: params.content.text,
+      ...(params.cc ? { cc: toArray(params.cc) } : {}),
+      ...(params.bcc ? { bcc: toArray(params.bcc) } : {}),
+      ...(params.replyTo ? { replyTo: toArray(params.replyTo) } : {}),
+    });
+    return { success: true, ...(result.id ? { id: result.id } : {}) };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    console.error("Email sending error:", message);
+    return { error: message, success: false };
+  }
+}

package/template/cloudflare/worker.mjs

@@ -0,0 +1,25 @@
+import { WorkflowEntrypoint } from "cloudflare:workers";
+
+import nextWorker from "../.open-next/worker.js";
+
+export class NextDevTplWorkflow extends WorkflowEntrypoint {
+  async run(event, step) {
+    return step.do(
+      "complete-job",
+      {
+        retries: {
+          delay: "5 seconds",
+          limit: 3,
+        },
+        timeout: "1 minute",
+      },
+      async () => ({
+        id: event.instanceId,
+        payload: event.payload,
+        status: "completed",
+      })
+    );
+  }
+}
+
+export default nextWorker;

package/template/components.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/app/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "registries": {}
+}

package/template/compose.yaml

@@ -0,0 +1,74 @@
+name: nextdevtpl
+
+x-app-environment: &app-environment
+  APP_VERSION: ${APP_VERSION:-local}
+  BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET:?Set BETTER_AUTH_SECRET in .env.production}
+  BETTER_AUTH_URL: ${BETTER_AUTH_URL:-http://localhost:3000}
+  DATABASE_URL: postgresql://${POSTGRES_USER:-nextdevtpl}:${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env.production}@database:5432/${POSTGRES_DB:-nextdevtpl}
+  NEXT_PUBLIC_APP_URL: ${NEXT_PUBLIC_APP_URL:-http://localhost:3000}
+  PORT: 3000
+
+services:
+  database:
+    image: postgres:17-alpine
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB:-nextdevtpl}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env.production}
+      POSTGRES_USER: ${POSTGRES_USER:-nextdevtpl}
+    healthcheck:
+      test:
+        [
+          "CMD-SHELL",
+          "pg_isready -U ${POSTGRES_USER:-nextdevtpl} -d ${POSTGRES_DB:-nextdevtpl}",
+        ]
+      interval: 5s
+      timeout: 5s
+      retries: 12
+    restart: unless-stopped
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+  migrate:
+    build:
+      context: .
+      target: migrator
+    env_file:
+      - path: .env.production
+        required: false
+    environment: *app-environment
+    depends_on:
+      database:
+        condition: service_healthy
+    restart: "no"
+
+  app:
+    build:
+      context: .
+      target: runner
+      args:
+        NEXT_PUBLIC_APP_URL: ${NEXT_PUBLIC_APP_URL:-http://localhost:3000}
+    env_file:
+      - path: .env.production
+        required: false
+    environment: *app-environment
+    depends_on:
+      migrate:
+        condition: service_completed_successfully
+    healthcheck:
+      test:
+        [
+          "CMD",
+          "node",
+          "-e",
+          "fetch('http://127.0.0.1:3000/api/health').then(r=>{if(!r.ok)process.exit(1)}).catch(()=>process.exit(1))",
+        ]
+      interval: 10s
+      timeout: 5s
+      retries: 6
+      start_period: 20s
+    ports:
+      - "${PORT:-3000}:3000"
+    restart: unless-stopped
+
+volumes:
+  postgres_data:

package/template/deploy/check-health.mjs

@@ -0,0 +1,25 @@
+const target = process.argv[2] ?? process.env.HEALTHCHECK_URL;
+
+if (!target) {
+  throw new Error(
+    "Health URL is required: pnpm deploy:check -- https://example.com/api/health"
+  );
+}
+
+const response = await fetch(target, {
+  headers: { Accept: "application/json" },
+  signal: AbortSignal.timeout(10_000),
+});
+const report = await response.json();
+
+if (!response.ok || report?.status !== "healthy") {
+  throw new Error(`Health check failed with HTTP ${response.status}`);
+}
+
+process.stdout.write(
+  `${JSON.stringify({
+    status: report.status,
+    version: report.version,
+    timestamp: report.timestamp,
+  })}\n`
+);

package/template/deploy/docker/README.md

@@ -0,0 +1,14 @@
+# Docker Compose 部署
+
+Compose 包含 PostgreSQL、一次性迁移服务和应用服务。数据库目录使用
+`postgres_data` named volume，不会写进项目目录。
+
+1. 复制 `.env.example` 为 `.env.production`，至少设置
+   `POSTGRES_PASSWORD`、`BETTER_AUTH_SECRET`、站点 URL 和所选适配器配置。
+2. 首次生成的项目运行 `pnpm install && pnpm db:generate:init`，检查并提交
+   `drizzle/`。后续 Schema 变化继续生成新的迁移。
+3. 执行 `docker compose --env-file .env.production up -d --build`。
+4. 执行 `pnpm deploy:check -- http://localhost:3000/api/health`。
+
+`migrate` 成功退出后应用才会启动。升级时先备份 named volume 或外部数据库，
+再构建新镜像；迁移失败会阻止新应用启动。

package/template/deploy/server/README.md

@@ -0,0 +1,24 @@
+# 服务器部署
+
+要求 Node.js 24、pnpm 10、PostgreSQL 和 systemd。数据库连接建议使用独立托管
+实例；应用服务器只保存可替换的 standalone 产物。
+
+## 首次部署
+
+1. 复制 `.env.example` 为 `.env.production`，填写真实生产配置。不要把这个文件
+   加入 Git 或构建包。
+2. 首次生成的项目先运行 `pnpm install && pnpm db:generate:init`，检查生成的 SQL
+   并提交 `drizzle/`。仓库已经带迁移时跳过这一步。
+3. 加载生产环境变量后运行 `pnpm deploy:server:build`。脚本先执行已提交迁移，
+   再把 standalone 产物写入 `.release/`。
+4. 把 `.release/` 上传到 `/opt/nextdevtpl/current`，把环境文件单独放到
+   `/opt/nextdevtpl/shared/.env.production`。
+5. 按实际用户和目录调整 `nextdevtpl.service`，安装到 systemd 后启动服务。
+
+反向代理应终止 TLS，并把原始协议和主机头转发给端口 3000。发布完成后执行：
+
+```bash
+pnpm deploy:check -- https://your-domain.example/api/health
+```
+
+接口返回 200 且 `status` 为 `healthy` 才表示配置和数据库均已就绪。

package/template/deploy/server/build.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+RELEASE_DIR="${RELEASE_DIR:-$ROOT_DIR/.release}"
+
+if [[ "$RELEASE_DIR" == "/" || "$RELEASE_DIR" == "$ROOT_DIR" ]]; then
+  echo "Refusing unsafe RELEASE_DIR: $RELEASE_DIR" >&2
+  exit 1
+fi
+
+cd "$ROOT_DIR"
+pnpm install --frozen-lockfile
+pnpm db:migrate
+pnpm build
+
+rm -rf -- "$RELEASE_DIR"
+mkdir -p "$RELEASE_DIR/.next"
+cp -R .next/standalone/. "$RELEASE_DIR/"
+cp -R .next/static "$RELEASE_DIR/.next/static"
+cp -R public "$RELEASE_DIR/public"
+cp deploy/server/start.sh "$RELEASE_DIR/start.sh"
+
+echo "Standalone release created at $RELEASE_DIR"

package/template/deploy/server/nextdevtpl.service

@@ -0,0 +1,19 @@
+[Unit]
+Description=NextDevTpl application
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=nextdevtpl
+Group=nextdevtpl
+WorkingDirectory=/opt/nextdevtpl/current
+EnvironmentFile=/opt/nextdevtpl/shared/.env.production
+ExecStart=/opt/nextdevtpl/current/start.sh
+Restart=on-failure
+RestartSec=5
+NoNewPrivileges=true
+PrivateTmp=true
+
+[Install]
+WantedBy=multi-user.target

package/template/deploy/server/start.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+APP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ENV_FILE="${ENV_FILE:-$APP_DIR/.env.production}"
+
+if [[ -f "$ENV_FILE" ]]; then
+  set -a
+  # shellcheck disable=SC1090
+  source "$ENV_FILE"
+  set +a
+fi
+
+export HOSTNAME="${HOSTNAME:-0.0.0.0}"
+export NODE_ENV=production
+export PORT="${PORT:-3000}"
+
+cd "$APP_DIR"
+exec node server.js

package/template/deploy/vercel/README.md

@@ -0,0 +1,16 @@
+# Vercel 部署
+
+Vercel 预设使用 Node.js Serverless 运行时。推荐使用 Neon PostgreSQL、S3 兼容
+对象存储、Upstash Redis 和 Inngest；实际启用项以生成器选择的适配器为准。
+
+1. 在 Vercel 项目中配置 `.env.example` 列出的变量，并把
+   `NEXT_PUBLIC_APP_URL`、`BETTER_AUTH_URL` 设置为正式域名。
+2. 首次生成的项目运行 `pnpm install && pnpm db:generate:init`，检查并提交
+   `drizzle/`。
+3. 在发布前的单实例任务或本机受控环境运行 `pnpm db:migrate`。不要把迁移放进
+   Vercel `buildCommand`，多个构建实例可能并发执行。
+4. 发布后执行
+   `pnpm deploy:check -- https://your-project.vercel.app/api/health`。
+
+`vercel.json` 只声明框架、构建命令和已选模块需要的 Cron。OAuth 回调、支付
+Webhook、Inngest 回调和对象存储 CORS 仍需在各服务后台配置正式域名。