create-nextdevtpl 2.6.0

package/template/src/config/subscription-plan.ts

@@ -0,0 +1,164 @@
+/**
+ * 订阅计划权限配置
+ *
+ * 定义各计划的特权限制和功能访问权限
+ */
+
+import { PRICE_IDS } from "./payment";
+
+// ============================================
+// 计划类型定义
+// ============================================
+
+/**
+ * 订阅计划类型
+ */
+export type SubscriptionPlan = "free" | "starter" | "pro" | "ultra";
+
+/**
+ * 队列优先级
+ */
+export type QueuePriority = "normal" | "priority" | "highest";
+
+/**
+ * 计划特权配置
+ */
+export interface PlanPrivileges {
+  /** 计划名称 */
+  name: string;
+  /** 单文件大小上限 (bytes) */
+  maxFileSizeBytes: number;
+  /** 队列优先级 */
+  queuePriority: QueuePriority;
+  /** 月度积分配额 (免费版为一次性) */
+  monthlyCredits: number;
+}
+
+// ============================================
+// 计划特权配置
+// ============================================
+
+/**
+ * 各计划的特权配置
+ */
+export const PLAN_PRIVILEGES: Record<SubscriptionPlan, PlanPrivileges> = {
+  free: {
+    name: "Free",
+    maxFileSizeBytes: 5 * 1024 * 1024, // 5MB
+    queuePriority: "normal",
+    monthlyCredits: 200, // 一次性
+  },
+  starter: {
+    name: "Starter",
+    maxFileSizeBytes: 20 * 1024 * 1024, // 20MB
+    queuePriority: "normal",
+    monthlyCredits: 3_000,
+  },
+  pro: {
+    name: "Pro",
+    maxFileSizeBytes: 50 * 1024 * 1024, // 50MB
+    queuePriority: "priority",
+    monthlyCredits: 8_000,
+  },
+  ultra: {
+    name: "Ultra",
+    maxFileSizeBytes: 100 * 1024 * 1024, // 100MB
+    queuePriority: "highest",
+    monthlyCredits: 16_000,
+  },
+};
+
+// ============================================
+// Price ID 到计划的映射
+// ============================================
+
+/**
+ * 根据 Price ID 获取计划类型
+ *
+ * @param priceId - 价格/产品 ID
+ * @returns 计划类型，如果未找到则返回 null
+ */
+export function getPlanFromPriceId(priceId: string): SubscriptionPlan | null {
+  // Starter
+  if (
+    priceId === PRICE_IDS.STARTER_MONTHLY ||
+    priceId === PRICE_IDS.STARTER_YEARLY
+  ) {
+    return "starter";
+  }
+
+  // Pro
+  if (priceId === PRICE_IDS.PRO_MONTHLY || priceId === PRICE_IDS.PRO_YEARLY) {
+    return "pro";
+  }
+
+  // Ultra
+  if (
+    priceId === PRICE_IDS.ULTRA_MONTHLY ||
+    priceId === PRICE_IDS.ULTRA_YEARLY
+  ) {
+    return "ultra";
+  }
+
+  return null;
+}
+
+// ============================================
+// 特权检查工具函数
+// ============================================
+
+/**
+ * 获取计划的特权配置
+ *
+ * @param plan - 订阅计划
+ * @returns 计划特权配置
+ */
+export function getPlanPrivileges(plan: SubscriptionPlan): PlanPrivileges {
+  return PLAN_PRIVILEGES[plan];
+}
+
+/**
+ * 检查文件大小是否在限制内
+ *
+ * @param plan - 订阅计划
+ * @param fileSizeBytes - 文件大小（字节）
+ * @returns 是否在限制内
+ */
+export function isWithinFileSizeLimit(
+  plan: SubscriptionPlan,
+  fileSizeBytes: number
+): boolean {
+  return fileSizeBytes <= PLAN_PRIVILEGES[plan].maxFileSizeBytes;
+}
+
+/**
+ * 格式化文件大小限制（用于错误消息）
+ *
+ * @param plan - 订阅计划
+ * @returns 格式化的文件大小字符串（如 "5MB"）
+ */
+export function formatFileSizeLimit(plan: SubscriptionPlan): string {
+  const bytes = PLAN_PRIVILEGES[plan].maxFileSizeBytes;
+  return `${bytes / (1024 * 1024)}MB`;
+}
+
+/**
+ * 获取升级建议（当特权不足时）
+ *
+ * @param currentPlan - 当前计划
+ * @param requiredFeature - 需要的功能描述
+ * @returns 升级建议消息
+ */
+export function getUpgradeMessage(
+  currentPlan: SubscriptionPlan,
+  requiredFeature: string
+): string {
+  const upgradeTo =
+    currentPlan === "free"
+      ? "Starter"
+      : currentPlan === "starter"
+        ? "Pro"
+        : "Ultra";
+
+  return `${requiredFeature} requires ${upgradeTo} plan or higher. Please upgrade to continue.`;
+}

package/template/src/content/blog/en/hello-world.mdx

@@ -0,0 +1,48 @@
+---
+title: Hello World
+description: Welcome to our blog! This is our first post introducing NextDevTpl.
+date: 2024-01-15
+author: NextDevTpl Team
+tags:
+  - announcement
+  - getting-started
+---
+
+# Hello World
+
+Welcome to the NextDevTpl blog! We're excited to share our journey of building the ultimate Next.js starter kit.
+
+## What is NextDevTpl?
+
+NextDevTpl is a modern, production-ready SaaS boilerplate built with:
+
+- **Next.js 16** - The React framework for production
+- **TypeScript** - Type-safe development
+- **Tailwind CSS** - Utility-first styling
+- **Better Auth** - Modern authentication
+- **Drizzle ORM** - Type-safe database access
+
+## Why We Built This
+
+Building a SaaS application from scratch is time-consuming. You need to set up authentication, database connections, styling, and countless other features before you can even start working on your actual product.
+
+NextDevTpl solves this by providing a solid foundation that includes:
+
+1. **Authentication** - Email/password, OAuth providers
+2. **Database** - PostgreSQL with Drizzle ORM
+3. **UI Components** - Beautiful, accessible components
+4. **Internationalization** - Multi-language support
+5. **SEO** - Optimized for search engines
+
+## Getting Started
+
+To get started with NextDevTpl, simply clone the repository and follow the setup instructions in our documentation.
+
+```bash
+git clone https://github.com/nextdevtpl/nextdevtpl.git
+cd nextdevtpl
+pnpm install
+pnpm dev
+```
+
+Stay tuned for more updates and tutorials!

package/template/src/content/blog/zh/hello-world.mdx

@@ -0,0 +1,48 @@
+---
+title: 你好世界
+description: 欢迎来到我们的博客！这是我们介绍 NextDevTpl 的第一篇文章。
+date: 2024-01-15
+author: NextDevTpl 团队
+tags:
+  - 公告
+  - 入门指南
+---
+
+# 你好世界
+
+欢迎来到 NextDevTpl 博客！我们很高兴与您分享构建终极 Next.js 启动模板的旅程。
+
+## 什么是 NextDevTpl？
+
+NextDevTpl 是一个现代化、生产就绪的 SaaS 模板，采用以下技术构建：
+
+- **Next.js 16** - 用于生产环境的 React 框架
+- **TypeScript** - 类型安全的开发体验
+- **Tailwind CSS** - 实用优先的样式方案
+- **Better Auth** - 现代化认证方案
+- **Drizzle ORM** - 类型安全的数据库访问
+
+## 为什么我们要构建它
+
+从零开始构建 SaaS 应用程序非常耗时。在开始开发实际产品之前，您需要设置身份验证、数据库连接、样式和无数其他功能。
+
+NextDevTpl 通过提供坚实的基础来解决这个问题，包括：
+
+1. **身份验证** - 邮箱/密码、OAuth 提供商
+2. **数据库** - PostgreSQL 配合 Drizzle ORM
+3. **UI 组件** - 美观、无障碍的组件
+4. **国际化** - 多语言支持
+5. **SEO** - 搜索引擎优化
+
+## 开始使用
+
+要开始使用 NextDevTpl，只需克隆仓库并按照文档中的设置说明操作。
+
+```bash
+git clone https://github.com/nextdevtpl/nextdevtpl.git
+cd nextdevtpl
+pnpm install
+pnpm dev
+```
+
+敬请期待更多更新和教程！

package/template/src/content/blog/zh/nextdevtpl-linuxdo-intro.mdx

@@ -0,0 +1,98 @@
+---
+title: "[开源] NextDevTpl：一个面向独立开发者的 Next.js 全栈 SaaS 模板"
+description: "不是能跑 Demo 的脚手架，而是可直接落地业务的全栈模板。内置认证、支付、积分、邮件、存储、工单与后台管理。"
+date: 2026-02-16
+author: NextDevTpl 团队
+tags:
+  - 开源
+  - SaaS
+  - Next.js
+  - 独立开发
+---
+
+# [开源] NextDevTpl：一个面向独立开发者的 Next.js 全栈 SaaS 模板
+
+大家好，最近我把自己在多个项目里反复打磨的一套模板整理成了开源项目：`NextDevTpl`。  
+目标很明确：它不是“能跑起来的 Demo”，而是“可以直接承接真实业务”的全栈模板。
+
+## 为什么做这个模板？
+
+做过几次从 0 到 1 的朋友应该都懂：最耗时间的往往不是业务本身，而是重复基建。
+
+- 登录注册、权限和会话管理
+- 支付订阅、Webhook、账单状态同步
+- 积分扣减、发放、过期与流水
+- 邮件通知、文件上传、用户工单
+- 管理后台、日志监控、错误告警
+
+这些内容每次都要重做，不仅耗时，也容易在上线后暴露隐患。  
+所以我把这些高频模块统一抽成一套可复用模板，尽量做到开箱即用、可持续扩展。
+
+## 技术栈（当前版本）
+
+- **Next.js 16 + React 19 + TypeScript**
+- **Tailwind CSS 4 + Shadcn/UI**
+- **Drizzle ORM + PostgreSQL**
+- **Better Auth（账号体系）**
+- **next-intl（国际化）**
+- **S3/R2 兼容对象存储**
+- **Vitest + Biome 工程化支持**
+
+## 已内置能力（不是空壳）
+
+### 1) 用户与权限
+
+- 邮箱注册/登录与 OAuth
+- 会话管理与角色隔离（user/admin）
+
+### 2) 商业化能力
+
+- 订阅支付流程
+- Webhook 处理
+- 积分账本与扣费逻辑
+
+### 3) 运营支持能力
+
+- 邮件模板与发送
+- 文件上传与管理
+- 工单系统（用户侧 + 管理侧）
+- 管理后台（用户管理、数据面板）
+
+### 4) 工程保障能力
+
+- API 限流（可选）
+- 结构化日志（可选）
+- 错误监控（可选）
+- 外部服务未配置时可自动降级，便于本地开发与调试
+
+## 适合谁使用？
+
+- 想快速上线 MVP 的独立开发者
+- 想统一技术底座的小团队
+- 不想每次项目都从认证、支付、后台重复造轮子的开发者
+
+## 快速启动
+
+```bash
+git clone git@github.com:evepupil/NextDevTpl.git
+cd NextDevTpl
+pnpm install
+cp .env.example .env.local
+pnpm db:push
+pnpm dev
+```
+
+## 我希望它解决的问题
+
+我做这个项目的核心目标并不是“堆技术名词”，而是帮你把时间真正花在更重要的事情上：
+
+1. 业务闭环和核心价值
+2. 用户反馈与迭代效率
+3. 商业化验证与增长
+
+## 欢迎交流与共建
+
+如果你愿意试用，欢迎直接反馈真实问题：  
+你最在意哪些模块？哪些地方还不够生产可用？你希望优先补齐什么能力？
+
+也欢迎提交 Issue / PR，一起把它打磨成真正可落地的生产级模板。欢迎在 linux.do 交流想法，我会持续迭代。

package/template/src/content/docs/en/admin-and-support.mdx

@@ -0,0 +1,65 @@
+---
+title: Admin and Support
+description: Manage users, roles, tickets, and customer support workflows.
+---
+
+# Admin and Support
+
+The template includes a simple but practical admin area and support ticket system.
+
+## Admin area
+
+Admin routes live under:
+
+```txt
+src/app/[locale]/(admin)/admin
+```
+
+Main components:
+
+| Path | Purpose |
+| --- | --- |
+| `src/features/admin/components/admin-sidebar.tsx` | Admin navigation |
+| `src/app/[locale]/(admin)/admin/page.tsx` | Admin overview |
+| `src/app/[locale]/(admin)/admin/users/page.tsx` | User management |
+| `src/app/[locale]/(admin)/admin/tickets/page.tsx` | Ticket queue |
+| `src/app/[locale]/(admin)/admin/tickets/[id]/page.tsx` | Ticket detail |
+
+## Support tickets
+
+User ticket routes live under:
+
+```txt
+src/app/[locale]/(dashboard)/dashboard/support
+```
+
+Feature files:
+
+| Path | Purpose |
+| --- | --- |
+| `src/features/support/actions/ticket.ts` | Ticket actions |
+| `src/features/support/actions/admin-users.ts` | Admin user helpers |
+| `src/features/support/components` | Ticket forms, replies, status controls |
+| `src/features/support/schemas` | Validation schemas |
+| `src/test/support` | Ticket and admin user tests |
+
+## Ticket lifecycle
+
+Recommended status flow:
+
+```txt
+open -> in_progress -> resolved
+```
+
+Keep user-facing replies clear and avoid exposing internal logs or secrets.
+
+## Admin access
+
+Admin access depends on the authenticated user's role. For local testing, create a user and set `role = 'admin'` in the database.
+
+## Tests
+
+```bash
+pnpm test:run src/test/support
+```
+

package/template/src/content/docs/en/authentication.mdx

@@ -0,0 +1,71 @@
+---
+title: Authentication
+description: Understand Better Auth integration, auth routes, roles, and protected pages.
+---
+
+# Authentication
+
+Authentication is built with Better Auth and integrated into the App Router, middleware, dashboard, and admin area.
+
+## Main files
+
+| Path | Purpose |
+| --- | --- |
+| `src/lib/auth/api.ts` | Better Auth API configuration |
+| `src/lib/auth/client.ts` | Client-side auth helpers |
+| `src/lib/auth/server.ts` | Server-side session helpers |
+| `src/lib/auth/edge.ts` | Middleware-safe auth checks and public route config |
+| `src/lib/auth/admin.ts` | Admin-specific helpers |
+| `src/app/api/auth/[...all]/route.ts` | Better Auth route handler |
+| `src/features/auth/components` | Sign-in, sign-up, forgot-password UI |
+
+## Supported flows
+
+| Flow | Notes |
+| --- | --- |
+| Email/password | Baseline local auth flow |
+| GitHub OAuth | Requires GitHub OAuth app credentials |
+| Google OAuth | Requires Google Cloud OAuth credentials |
+| Password reset | Requires email delivery to send reset messages |
+| Role-based access | `user` and `admin` roles are used by dashboard/admin protection |
+
+## Public and protected routes
+
+The middleware/auth edge helpers decide which routes are public and which need a session. Public routes include marketing pages, auth pages, blog, legal pages, docs, and selected API endpoints.
+
+Authenticated pages live under:
+
+```txt
+src/app/[locale]/(dashboard)/dashboard
+```
+
+Admin pages live under:
+
+```txt
+src/app/[locale]/(admin)/admin
+```
+
+## Make yourself an admin
+
+After creating a local user, update the user's role in the database:
+
+```sql
+update "user"
+set role = 'admin'
+where email = 'you@example.com';
+```
+
+Then visit:
+
+```txt
+/en/admin
+```
+
+## Adding an OAuth provider
+
+1. Create credentials in the provider console.
+2. Add the provider credentials to `.env.local`.
+3. Register callback URLs that match `BETTER_AUTH_URL`.
+4. Update the auth UI if you want to expose a new provider button.
+5. Test sign-in locally before enabling it in production.
+

package/template/src/content/docs/en/background-jobs.mdx

@@ -0,0 +1,53 @@
+---
+title: Background Jobs
+description: Run async product workflows with Inngest.
+---
+
+# Background Jobs
+
+Background jobs are powered by Inngest. Use jobs for workflows that should not block a request, such as credit expiration, delivery retries, email batching, or async product processing.
+
+## Main files
+
+| Path | Purpose |
+| --- | --- |
+| `src/inngest/client.ts` | Inngest client |
+| `src/inngest/functions.ts` | Function definitions |
+| `src/inngest/index.ts` | Exports |
+| `src/app/api/inngest/route.ts` | Inngest route handler |
+| `src/app/api/jobs/credits/expire/route.ts` | Credit expiration job endpoint |
+| `src/test/jobs/cron-expire.test.ts` | Job test coverage |
+
+## Local development
+
+Start the app:
+
+```bash
+pnpm dev
+```
+
+Then use the Inngest dev server if you need to inspect or trigger functions locally.
+
+## Production variables
+
+| Variable | Purpose |
+| --- | --- |
+| `INNGEST_EVENT_KEY` | Sends events to Inngest |
+| `INNGEST_SIGNING_KEY` | Verifies requests from Inngest |
+
+## Job design rules
+
+- Keep jobs idempotent.
+- Store enough state to recover from retries.
+- Do not grant credits or change subscription state twice for the same external event.
+- Prefer small composable functions over one large workflow.
+- Log job identifiers and external event IDs.
+
+## Testing
+
+Run job tests after touching expiration logic:
+
+```bash
+pnpm test:run src/test/jobs
+```
+

package/template/src/content/docs/en/configuration.mdx

@@ -0,0 +1,71 @@
+---
+title: Configuration
+description: Configure the required and optional services used by NextDevTpl.
+---
+
+# Configuration
+
+Configuration is environment-variable driven. Start with the required variables, then enable optional services as needed.
+
+## Required for local boot
+
+| Variable | Purpose |
+| --- | --- |
+| `DATABASE_URL` | PostgreSQL connection string used by Drizzle and Better Auth |
+| `BETTER_AUTH_SECRET` | Secret used to sign auth/session data |
+| `BETTER_AUTH_URL` | Base URL for Better Auth callbacks and cookies |
+
+Example:
+
+```bash
+DATABASE_URL="postgresql://postgres:password@localhost:5432/nextdevtpl"
+BETTER_AUTH_SECRET="replace-with-a-random-secret"
+BETTER_AUTH_URL="http://localhost:3000"
+```
+
+## Recommended during development
+
+| Service | Variables | Notes |
+| --- | --- | --- |
+| GitHub OAuth | `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` | Callback: `/api/auth/callback/github` |
+| Google OAuth | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` | Callback: `/api/auth/callback/google` |
+| Resend | `RESEND_API_KEY`, `EMAIL_FROM` | Enables real email verification and reset emails |
+
+If email is not configured, test authentication flows that do not require delivery first.
+
+## Optional product services
+
+| Service | Variables | Used by |
+| --- | --- | --- |
+| Creem | `CREEM_API_KEY`, `CREEM_WEBHOOK_SECRET` | Subscription checkout, credit purchases, webhooks |
+| S3/R2 | `STORAGE_ENDPOINT`, `STORAGE_REGION`, `STORAGE_BUCKET`, `STORAGE_ACCESS_KEY_ID`, `STORAGE_SECRET_ACCESS_KEY` | File uploads and proxy routes |
+| Upstash Redis | `UPSTASH_REDIS_REST_URL`, `UPSTASH_REDIS_REST_TOKEN` | API and anonymous rate limiting |
+| Axiom | `AXIOM_TOKEN`, `AXIOM_DATASET` | Structured cloud logs |
+| Sentry | `NEXT_PUBLIC_SENTRY_DSN`, `SENTRY_AUTH_TOKEN` | Error capture and release uploads |
+| OpenAI-compatible AI | `OPENAI_API_KEY`, provider-specific base URL/model vars if configured | AI abstraction in `src/lib/ai` |
+| Inngest | `INNGEST_EVENT_KEY`, `INNGEST_SIGNING_KEY` | Background jobs in production |
+
+## Degradation model
+
+Optional services should not block a basic local boot. The intended behavior is:
+
+| Missing service | Expected behavior |
+| --- | --- |
+| Redis | Rate limiter falls back instead of crashing |
+| Axiom | Logger writes locally |
+| Sentry | Monitoring hooks become no-op or console-only |
+| Storage | Upload flows are unavailable, app shell still runs |
+| Creem | Payment flows are unavailable, non-payment pages still run |
+| Inngest keys | Local development can run without production signing keys |
+
+## Where configuration lives
+
+| Path | What to edit |
+| --- | --- |
+| `src/config/site.ts` | Site name, URL, metadata, social links |
+| `src/config/nav.ts` | Header, footer, dashboard, and admin navigation |
+| `src/config/payment.ts` | Payment product and checkout configuration |
+| `src/config/subscription-plan.ts` | Plan limits and pricing display |
+| `messages/*.json` | UI copy |
+| `.env.local` | Local secrets and service credentials |
+

package/template/src/content/docs/en/credits.mdx

@@ -0,0 +1,69 @@
+---
+title: Credits
+description: Understand the built-in credit system, ledger entries, and expiration model.
+---
+
+# Credits
+
+The credits module is one of the main product primitives in NextDevTpl. It is designed for AI tools, usage-based SaaS products, paid exports, and other metered features.
+
+## Main files
+
+| Path | Purpose |
+| --- | --- |
+| `src/features/credits/core.ts` | Core balance and transaction logic |
+| `src/features/credits/actions.ts` | Server Actions for credit operations |
+| `src/features/credits/config.ts` | Credit packages and display config |
+| `src/features/credits/components` | Balance, usage, purchase, and history UI |
+| `src/app/[locale]/(dashboard)/dashboard/credits/buy` | Credit purchase page |
+| `src/test/credits` | Credit integrity and purchase tests |
+
+## Concepts
+
+| Concept | Meaning |
+| --- | --- |
+| Balance | Current spendable credits for a user |
+| Transaction | A recorded credit movement |
+| Batch | Credits granted together with shared expiration metadata |
+| FIFO expiration | Older credits are consumed before newer credits |
+| Purchase package | A configured one-time purchase amount |
+
+## Typical flows
+
+### Purchase credits
+
+1. User opens `/dashboard/credits/buy`.
+2. User selects a package.
+3. The app creates a checkout through the payment layer.
+4. The webhook confirms payment.
+5. Credits are granted to the user.
+6. Transaction history reflects the purchase.
+
+### Spend credits
+
+Feature code should use the credits core instead of manually decrementing a number. This keeps transactions auditable and preserves expiration rules.
+
+### Expire credits
+
+Expiration is handled by batch metadata and background jobs. See [Background Jobs](/en/docs/background-jobs) for the job route and Inngest integration.
+
+## Customizing packages
+
+Edit:
+
+```txt
+src/features/credits/config.ts
+```
+
+Keep package IDs stable once they are used in payment or audit records.
+
+## Testing
+
+Run focused tests when touching credits:
+
+```bash
+pnpm test:run src/test/credits
+```
+
+Always preserve transaction integrity. Bugs in credits are financial/accounting bugs, not only UI bugs.
+