create-nextdevtpl 2.6.0

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

@@ -0,0 +1,95 @@
+---
+title: Customization
+description: Common places to customize branding, navigation, pricing, pages, and modules.
+---
+
+# Customization
+
+This page lists the most common places to edit when turning NextDevTpl into your own SaaS.
+
+## Branding
+
+| Edit | Path |
+| --- | --- |
+| Site name, URL, metadata | `src/config/site.ts` |
+| Logo | `public/logo.svg` and header components |
+| Global styles | `src/app/globals.css` |
+| Open Graph image template | `src/features/shared/components/og-image-template.tsx` |
+
+## Navigation
+
+| Area | Path |
+| --- | --- |
+| Header and footer | `src/config/nav.ts` |
+| Dashboard sidebar | `src/config/nav.ts` and `src/features/dashboard/components/sidebar.tsx` |
+| Admin sidebar | `src/config/nav.ts` and `src/features/admin/components/admin-sidebar.tsx` |
+
+## Landing page
+
+Marketing sections live in:
+
+```txt
+src/features/marketing/components
+```
+
+The home route is:
+
+```txt
+src/app/[locale]/(marketing)/page.tsx
+```
+
+Most copy comes from:
+
+```txt
+messages/en.json
+messages/zh.json
+```
+
+## Pricing and plans
+
+| Edit | Path |
+| --- | --- |
+| Plan names and limits | `src/config/subscription-plan.ts` |
+| Payment product mapping | `src/config/payment.ts` |
+| Pricing section UI | `src/features/marketing/components/pricing-section.tsx` |
+| Subscription UI | `src/features/subscription` |
+
+## Product modules
+
+Add new product code under:
+
+```txt
+src/features/<your-feature>
+```
+
+Recommended shape:
+
+```txt
+src/features/example/
+├── actions.ts
+├── components/
+├── schemas/
+├── types.ts
+└── index.ts
+```
+
+Keep route-specific composition in `src/app` and reusable business logic inside the feature module.
+
+## Content
+
+| Content | Path |
+| --- | --- |
+| Docs | `src/content/docs/<locale>` |
+| Blog | `src/content/blog/<locale>` |
+| Legal | `src/content/legal/<locale>` |
+| PSEO data | `src/features/pseo/data/pseo-pages.json` |
+
+## Before committing customizations
+
+```bash
+pnpm typecheck
+pnpm lint
+```
+
+Run focused tests if you changed auth, credits, payments, storage, support, or jobs.
+

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

@@ -0,0 +1,66 @@
+---
+title: Database
+description: Work with PostgreSQL and Drizzle ORM in NextDevTpl.
+---
+
+# Database
+
+NextDevTpl uses PostgreSQL with Drizzle ORM. The schema is the source of truth for auth, credits, payments, support tickets, and user data.
+
+## Main files
+
+| Path | Purpose |
+| --- | --- |
+| `src/db/schema.ts` | Table definitions |
+| `src/db/index.ts` | Database client |
+| `drizzle.config.ts` | Drizzle config |
+| `drizzle/` | Generated migration files and snapshots |
+| `src/test/utils/db.ts` | Test database helpers |
+
+## Development workflow
+
+For a new local database:
+
+```bash
+pnpm db:push
+```
+
+For a change that should be reviewed and deployed:
+
+```bash
+pnpm db:generate
+pnpm db:migrate
+```
+
+Use Drizzle Studio to inspect local data:
+
+```bash
+pnpm db:studio
+```
+
+## When to use push vs migrations
+
+| Command | Use it when |
+| --- | --- |
+| `pnpm db:push` | You are bootstrapping or iterating on a local database |
+| `pnpm db:generate` | You changed `src/db/schema.ts` and need a migration file |
+| `pnpm db:migrate` | You want to apply committed migrations |
+
+## Schema changes checklist
+
+1. Update `src/db/schema.ts`.
+2. Update any feature service/action that reads or writes the changed table.
+3. Generate or push the schema depending on environment.
+4. Add or update tests under `src/test`.
+5. Run `pnpm typecheck` and targeted tests.
+
+## Common table areas
+
+| Area | Used by |
+| --- | --- |
+| Auth users and sessions | Better Auth |
+| Credits and transactions | Credits ledger and purchases |
+| Subscriptions | Payment and plan lookup |
+| Support tickets | User support and admin ticket queue |
+| Storage records | Upload and file security tests |
+

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

@@ -0,0 +1,62 @@
+---
+title: Deployment
+description: Deploy NextDevTpl with the existing scripts or a managed Next.js platform.
+---
+
+# Deployment
+
+The repository includes a self-hosted deployment flow and can also be deployed on managed Next.js platforms.
+
+## Self-hosted flow
+
+The existing script pair is:
+
+| File | Runs on | Purpose |
+| --- | --- | --- |
+| `deploy-build.bat` | Windows/local machine | Build, package, upload artifacts |
+| `start-prod.sh` | Linux/server | Install production dependencies and start/restart app |
+
+Typical flow:
+
+1. Configure SSH host, deploy path, and key path in `deploy-build.bat`.
+2. Confirm production `.env` exists on the server.
+3. Run the script locally:
+
+```bat
+deploy-build.bat
+```
+
+4. The script builds locally, creates an archive, uploads it, then starts the app on the server.
+
+## Production environment
+
+At minimum, production needs:
+
+```bash
+DATABASE_URL="postgresql://..."
+BETTER_AUTH_SECRET="strong-production-secret"
+BETTER_AUTH_URL="https://your-domain.com"
+```
+
+Add the optional services you actually use: Creem, Resend, storage, Redis, Sentry, Axiom, Inngest, and AI provider credentials.
+
+## Vercel
+
+For Vercel:
+
+1. Import the GitHub repository.
+2. Set all production environment variables.
+3. Make sure the database is reachable from Vercel.
+4. Configure webhook URLs with the Vercel production domain.
+5. Run migrations before or during release.
+
+## Release checklist
+
+- `pnpm typecheck` passes.
+- `pnpm build` passes.
+- Database migrations are ready.
+- `BETTER_AUTH_URL` uses the production domain.
+- OAuth callback URLs use the production domain.
+- Creem webhook URL points to `/api/webhooks/creem`.
+- Sentry/Axiom do not receive raw secrets.
+

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

@@ -0,0 +1,48 @@
+---
+title: Email
+description: Send product emails with Resend and React Email templates.
+---
+
+# Email
+
+Email delivery uses Resend and React Email templates.
+
+## Main files
+
+| Path | Purpose |
+| --- | --- |
+| `src/features/mail/client.ts` | Resend client setup |
+| `src/features/mail/actions.ts` | Email send actions |
+| `src/features/mail/utils.ts` | Email helpers |
+| `src/features/mail/templates` | React Email templates |
+| `src/test/mail/newsletter.test.ts` | Email-related test coverage |
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `RESEND_API_KEY` | Authenticates with Resend |
+| `EMAIL_FROM` | Sender address displayed to users |
+
+Example:
+
+```bash
+RESEND_API_KEY="re_xxxxxxxxx"
+EMAIL_FROM="NextDevTpl <noreply@example.com>"
+```
+
+## Templates
+
+Templates are React components. Current examples include:
+
+| Template | Purpose |
+| --- | --- |
+| `welcome-email.tsx` | Welcome/onboarding email |
+| `primary-action-email.tsx` | Generic action email with a button |
+
+When editing templates, keep copy short and avoid relying on app-only CSS. Email clients have limited CSS support.
+
+## Local behavior
+
+If Resend is not configured, email-dependent features should be treated as unavailable. Use email/password flows that do not require delivery first, then enable Resend when testing verification and reset flows.
+

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

@@ -0,0 +1,48 @@
+---
+title: Introduction
+description: Learn what NextDevTpl includes and how to use the template as a production SaaS starting point.
+---
+
+# NextDevTpl Documentation
+
+NextDevTpl is a production-oriented SaaS starter built on Next.js, React, TypeScript, PostgreSQL, Drizzle ORM, Better Auth, next-intl, Creem payments, credits, admin tools, support tickets, email, storage, observability, and background jobs.
+
+The goal of the template is not only to show a landing page. It gives you a working product shell that can be customized into a real SaaS application.
+
+## What is included
+
+| Area | What you get |
+| --- | --- |
+| App shell | Localized marketing site, blog, docs, dashboard, admin area, and legal pages |
+| Authentication | Better Auth with email/password, OAuth providers, session handling, and roles |
+| Database | PostgreSQL schema with Drizzle ORM, migrations, and integration tests |
+| Billing | Creem checkout, subscription flow, webhook handling, and one-time credit purchases |
+| Credits | Ledger-style credit accounting, FIFO batch expiration, and balance reads |
+| Operations | Admin users, support tickets, logging, monitoring, rate limiting, and jobs |
+| Content | Fumadocs-powered docs, MDX blog, and next-intl translated UI |
+
+## Recommended reading path
+
+If you are evaluating the template, start with:
+
+- [Quick Start](/en/docs/quick-start)
+- [Project Structure](/en/docs/project-structure)
+- [Configuration](/en/docs/configuration)
+
+If you are integrating product features, read:
+
+- [Authentication](/en/docs/authentication)
+- [Payments](/en/docs/payments)
+- [Credits](/en/docs/credits)
+- [Internationalization](/en/docs/internationalization)
+
+If you are preparing production, read:
+
+- [Deployment](/en/docs/deployment)
+- [Observability](/en/docs/observability)
+- [Background Jobs](/en/docs/background-jobs)
+
+## Core principle
+
+Most external services are optional during local development. The app should boot with only database and auth basics, then enable OAuth, email, payments, storage, Redis, Sentry, Axiom, and Inngest as your product needs them.
+

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

@@ -0,0 +1,78 @@
+---
+title: Internationalization
+description: Work with next-intl routes, UI messages, and localized documentation.
+---
+
+# Internationalization
+
+NextDevTpl uses `next-intl` for UI translations and locale-aware routing. Documentation content is localized through Fumadocs content folders.
+
+## Current locales
+
+Locales are configured in:
+
+```txt
+src/i18n/routing.ts
+```
+
+Current values:
+
+```ts
+locales: ["en", "zh"]
+defaultLocale: "en"
+```
+
+## UI messages
+
+| File | Purpose |
+| --- | --- |
+| `messages/en.json` | English UI copy |
+| `messages/zh.json` | Chinese UI copy |
+| `src/i18n/request.ts` | Loads locale messages |
+| `src/features/shared/components/language-switcher.tsx` | Header language switcher |
+
+Use `useTranslations()` in client components and server translation helpers in server components.
+
+## Route structure
+
+Most pages live under:
+
+```txt
+src/app/[locale]
+```
+
+Examples:
+
+```txt
+/en
+/zh
+/en/dashboard
+/zh/dashboard
+/en/docs
+/zh/docs
+```
+
+## Documentation i18n
+
+Docs are stored by language:
+
+```txt
+src/content/docs/en
+src/content/docs/zh
+```
+
+The loader in `src/lib/source.ts` uses Fumadocs i18n with the `dir` parser. The docs route reads pages by `params.locale`, so `/en/docs` and `/zh/docs` get separate page trees.
+
+## Adding a locale
+
+1. Add the locale to `src/i18n/routing.ts`.
+2. Add `messages/<locale>.json`.
+3. Add docs under `src/content/docs/<locale>`.
+4. Add blog/legal content if those routes should support the locale.
+5. Update sitemap metadata if needed.
+6. Test navigation and language switching.
+
+## Translation quality
+
+Do not mechanically translate product terms that are better left in English. Keep framework and API names unchanged: Next.js, Drizzle, Better Auth, Creem, Inngest, Sentry, Axiom, Fumadocs, next-intl.
+

package/template/src/content/docs/en/meta.json

@@ -0,0 +1,22 @@
+{
+  "title": "NextDevTpl",
+  "root": true,
+  "pages": [
+    "index",
+    "quick-start",
+    "project-structure",
+    "configuration",
+    "authentication",
+    "database",
+    "credits",
+    "payments",
+    "email",
+    "storage",
+    "internationalization",
+    "background-jobs",
+    "admin-and-support",
+    "observability",
+    "deployment",
+    "customization"
+  ]
+}

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

@@ -0,0 +1,69 @@
+---
+title: Observability
+description: Configure logging, monitoring, rate limits, and request diagnostics.
+---
+
+# Observability
+
+NextDevTpl includes structured logging, optional cloud log shipping, Sentry monitoring, rate limiting, and API request logging utilities.
+
+## Logging
+
+| Path | Purpose |
+| --- | --- |
+| `src/lib/logger/index.ts` | Pino logger wrapper |
+| `src/lib/api-logger.ts` | API logging helpers |
+
+When Axiom is configured, logs can be shipped to Axiom. Without Axiom, logs should still be available locally.
+
+Common variables:
+
+```bash
+AXIOM_TOKEN="xaat-..."
+AXIOM_DATASET="nextdevtpl"
+```
+
+## Error monitoring
+
+Sentry config files:
+
+| Path | Purpose |
+| --- | --- |
+| `sentry.client.config.ts` | Browser Sentry setup |
+| `sentry.server.config.ts` | Server Sentry setup |
+| `sentry.edge.config.ts` | Edge Sentry setup |
+| `src/instrumentation.ts` | Next.js instrumentation hook |
+| `src/lib/monitoring/index.ts` | Monitoring helpers |
+
+Common variables:
+
+```bash
+NEXT_PUBLIC_SENTRY_DSN="https://..."
+SENTRY_AUTH_TOKEN="sntrys_..."
+```
+
+## Rate limiting
+
+Rate limiting lives in:
+
+```txt
+src/lib/rate-limit
+```
+
+Upstash variables:
+
+```bash
+UPSTASH_REDIS_REST_URL="https://..."
+UPSTASH_REDIS_REST_TOKEN="..."
+```
+
+If Redis is missing, development should continue without a hard startup failure.
+
+## Production checklist
+
+- Enable Sentry for user-visible errors.
+- Enable structured logs for webhook and payment debugging.
+- Log external event IDs for payment and job retries.
+- Avoid logging raw credentials, tokens, or authorization headers.
+- Verify rate limits on public mutation endpoints.
+

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

@@ -0,0 +1,64 @@
+---
+title: Payments
+description: Configure Creem payments, subscriptions, one-time purchases, and webhooks.
+---
+
+# Payments
+
+Payments are implemented through Creem. The template includes subscription billing, one-time credit purchases, webhook handling, and plan lookup.
+
+## Main files
+
+| Path | Purpose |
+| --- | --- |
+| `src/features/payment/creem.ts` | Creem client and API integration |
+| `src/features/payment/actions.ts` | Checkout and payment Server Actions |
+| `src/features/payment/types.ts` | Payment-related types |
+| `src/config/payment.ts` | Product/payment configuration |
+| `src/config/subscription-plan.ts` | Plan definitions |
+| `src/app/api/webhooks/creem/route.ts` | Creem webhook endpoint |
+| `src/features/subscription` | User plan lookup and subscription UI |
+| `src/test/payment` | Payment and subscription tests |
+
+## Required environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `CREEM_API_KEY` | Calls Creem APIs |
+| `CREEM_WEBHOOK_SECRET` | Verifies webhook signatures |
+
+Production callback and webhook URLs should use your deployed domain.
+
+## Subscription flow
+
+1. Plans are defined in `src/config/subscription-plan.ts`.
+2. The pricing UI renders available plans.
+3. A checkout action creates a Creem checkout session.
+4. Creem sends webhook events.
+5. The webhook updates subscription state.
+6. The dashboard reads the current user plan.
+
+## Credit purchase flow
+
+One-time credit purchases share the payment layer but grant credit packages after successful payment. See [Credits](/en/docs/credits) for ledger behavior.
+
+## Webhook checklist
+
+Before going live:
+
+1. Configure the Creem webhook URL:
+
+```txt
+https://your-domain.com/api/webhooks/creem
+```
+
+2. Set `CREEM_WEBHOOK_SECRET`.
+3. Test a checkout in sandbox mode if available.
+4. Confirm subscription state updates.
+5. Confirm duplicate webhook events do not double-grant credits.
+6. Run payment tests.
+
+```bash
+pnpm test:run src/test/payment
+```
+

package/template/src/content/docs/en/project-structure.mdx

@@ -0,0 +1,82 @@
+---
+title: Project Structure
+description: Understand how the application is organized and where to customize each feature.
+---
+
+# Project Structure
+
+NextDevTpl uses a feature-based structure. Routes live under `src/app`, reusable product modules live under `src/features`, and infrastructure helpers live under `src/lib`.
+
+## Top-level files
+
+| Path | Purpose |
+| --- | --- |
+| `package.json` | Scripts and dependency versions |
+| `next.config.mjs` | Next.js, MDX, and build configuration |
+| `source.config.ts` | Fumadocs content collections |
+| `drizzle.config.ts` | Drizzle migration configuration |
+| `.env.example` | Environment variable reference |
+| `deploy-build.bat` | Windows-side production build and upload script |
+| `start-prod.sh` | Linux production start script |
+
+## Application routes
+
+```txt
+src/app/
+├── [locale]/
+│   ├── (marketing)/     # Home, blog, legal, PSEO, public pages
+│   ├── (auth)/          # Sign in, sign up, password reset
+│   ├── (dashboard)/     # Authenticated customer dashboard
+│   ├── (admin)/         # Admin-only area
+│   └── docs/            # Fumadocs documentation
+└── api/                 # Route handlers and webhooks
+```
+
+The locale segment is handled by `next-intl`. Current locales are configured in `src/i18n/routing.ts`.
+
+## Feature modules
+
+| Module | Main purpose |
+| --- | --- |
+| `src/features/auth` | Auth UI and client hooks |
+| `src/features/credits` | Credit ledger, purchases, and balance utilities |
+| `src/features/payment` | Creem checkout and payment actions |
+| `src/features/subscription` | User plan lookup and subscription UI |
+| `src/features/settings` | Profile, security, billing, and account settings |
+| `src/features/support` | User tickets and admin replies |
+| `src/features/admin` | Admin UI components |
+| `src/features/marketing` | Header, footer, hero, pricing, FAQ, and landing sections |
+| `src/features/storage` | S3/R2 upload and provider abstraction |
+| `src/features/mail` | React Email templates and send actions |
+| `src/features/shared` | Providers, theme toggle, language switcher, shared icons |
+
+## Infrastructure modules
+
+| Path | Responsibility |
+| --- | --- |
+| `src/db/schema.ts` | Database tables and relations |
+| `src/lib/auth` | Better Auth server, client, edge helpers, and admin helpers |
+| `src/lib/rate-limit` | Upstash-backed rate limiting with safe fallback |
+| `src/lib/logger` | Pino logger wrapper and Axiom integration |
+| `src/lib/monitoring` | Sentry integration helpers |
+| `src/lib/source.ts` | Fumadocs, blog, and legal content loaders |
+| `src/lib/safe-action.ts` | Server Action client setup |
+| `src/inngest` | Inngest client and background functions |
+
+## Content
+
+| Path | Content type |
+| --- | --- |
+| `src/content/docs/en` | English documentation |
+| `src/content/docs/zh` | Chinese documentation |
+| `src/content/blog/en` | English blog posts |
+| `src/content/blog/zh` | Chinese blog posts |
+| `src/content/legal/en` | English legal pages |
+| `src/content/legal/zh` | Chinese legal pages |
+| `messages/en.json` | English UI translations |
+| `messages/zh.json` | Chinese UI translations |
+
+## Testing
+
+Integration tests live under `src/test`. They cover payment, credits, support tickets, storage security, settings, jobs, and email flows.
+