From 9869001a7dcb2656d8a400534441c2e0a4d3b61c Mon Sep 17 00:00:00 2001 From: Bertrand Yuan Date: Wed, 31 Dec 2025 01:33:25 +0800 Subject: docs: refactor readme --- README | 115 ++++++++++++++++++++++++++++++++++++++++ README-zh | 115 ++++++++++++++++++++++++++++++++++++++++ README-zh.md | 170 ----------------------------------------------------------- README.md | 169 ---------------------------------------------------------- 4 files changed, 230 insertions(+), 339 deletions(-) create mode 100644 README create mode 100644 README-zh delete mode 100644 README-zh.md delete mode 100644 README.md diff --git a/README b/README new file mode 100644 index 0000000..2e81737 --- /dev/null +++ b/README @@ -0,0 +1,115 @@ +Next blog +========= + +A full-stack blog built with Next.js 15 and Payload CMS. Ships authentication, comments, search, RSS, and an email template out of the box. + +Overview +-------- + +Frontend uses Next.js App Router with Tailwind and shadcn, plus fumadocs layout pieces for navigation, pagination, and search. +Content is managed by Payload CMS (payload.config.ts) with support for rich text, tags, cover images, and publish states. +Authentication relies on better-auth with Google and GitHub; sessions and comments are stored in Postgres through Drizzle ORM. +Comments use @fuma-comment, and the site generates both /rss.xml feeds and /api/search indexes. + +Features +-------- + +Post management: Payload admin (/admin) creates drafts or published posts with cover images, tags, and scheduled publish time. +Blog experience: paginated lists, a tag hub, rich post detail rendering, a share button, and one-click copy link. +Social and interaction: Google or GitHub login, better-auth session management, Fuma Comment stored locally. +Enhancements: RSS feed, on-the-fly search index, automatic Open Graph banners, and sitemap via next-sitemap. +Email template: emails/newsletter-welcome.tsx using React Email with Tailwind, ready for Resend. +Ops friendly: .env validation, start-database.sh to boot local Postgres, unified Drizzle and Payload scripts for schema. + +Tech Stack +---------- + +Framework: Next.js 15 (App Router) with server components and hybrid static/dynamic rendering. +UI: Tailwind CSS 4 with shadcn and fumadocs-ui for navigation, pagination, sections, and theming. +Content: Payload CMS for Posts, Users, and Media with Lexical rich text. +Data: PostgreSQL and Drizzle ORM; auth and comments tables are prefixed blog_*. +Auth: better-auth with OAuth (Google/GitHub), sessions, and an extra role field. +Email: Resend with React Email, welcome template styled by Tailwind. + +Quickstart +---------- + +1. Install toolchain. Node 20+ recommended. Use pnpm locked by pnpm-lock.yaml. +2. Set environment variables. Copy .env.example to .env and fill DATABASE_URL, PAYLOAD_SECRET, BETTER_AUTH_SECRET, and OAuth keys if needed. +3. Start Postgres locally. Run ./start-database.sh (Docker/Podman) or connect to your own Postgres instance. +4. Install dependencies and build schema. Run pnpm install; pnpm db:generate && pnpm db:migrate for Drizzle; pnpm payload:migrate for Payload CMS. +5. Run the dev server. pnpm dev (defaults to port 3000; Payload Admin at /admin, blog at /). +6. Optional extras. pnpm payload:generate for types; pnpm email:dev -p 3001 to preview the email template. +Payload in development pre-fills / admin123 on the login form. + +Core Modules +------------ + +Content model lives in payload.config.ts, defining Posts, Users, and Media with cover uploads, tag arrays, publish time, and status. +Data fetching is wrapped in src/lib/payload-posts.ts for post queries, tag stats, pagination, and slug helpers. +Pages and layout reside under src/app/(main); _components includes Hero, CTA, and post list UI. +Auth and comments sit in src/server/auth (better-auth + Drizzle) and src/server/comments storing into blog_comments tables. +Search and feed live in src/app/(main)/api/search/route.ts (indexes) and src/app/(main)/rss.xml/route.ts (Atom/RSS). +Email template is emails/newsletter-welcome.tsx, a React Email component that accepts a posts array. + +Project structure (excerpt) +--------------------------- + +src/ + app/ + (main)/(home)/page.tsx Home with hero, recent posts, CTA + (main)/(home)/posts/[slug]/page.tsx Post detail with comments and share + (main)/(home)/posts/page.tsx Paginated posts list + (main)/(home)/tags/page.tsx Tag hub + (main)/api/search/route.ts Search index API + (main)/rss.xml/route.ts Atom/RSS feed + (payload)/admin/... Payload CMS admin + lib/ Data and utilities (payload-posts, metadata, auth-client) + server/ better-auth and Drizzle schema plus comment storage + emails/ React Email templates + +Environment variables +--------------------- + +Required or commonly used: + DATABASE_URL: Postgres connection string, e.g. postgresql://user:pass@localhost:5432/blog + PAYLOAD_SECRET: Secret used by Payload CMS for JWT + BETTER_AUTH_SECRET: better-auth session secret + BETTER_AUTH_URL: Auth callback base, local is + NEXT_PUBLIC_SERVER_URL: Base URL for links, OG, and RSS + RESEND_API_KEY / RESEND_AUDIENCE_ID / EMAIL_FROM: Needed for sending emails + GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET: Needed if enabling Google login + GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET: Needed if enabling GitHub login + NEXT_PUBLIC_UMAMI_URL / NEXT_PUBLIC_UMAMI_WEBSITE_ID: Optional analytics + +Scripts +------- + +pnpm dev Start Next.js dev server (includes Payload routes). +pnpm build Build production output. +pnpm preview Preview the production build. +pnpm db:generate Generate Drizzle migrations for auth and comments. +pnpm db:migrate Run Drizzle migrations. +pnpm payload:migrate Sync Payload CMS tables. +pnpm lint Run quality checks (biome). +pnpm format Format source (biome). +pnpm email:dev Preview React Email templates locally. + +Routes and APIs +--------------- + +/ Home with hero, latest posts, and CTA. +/posts Paginated posts; /posts/[slug] for detail with rich text, comments, and share. +/tags Tag cloud with counts. +/login Google or GitHub login entry. +/admin Payload CMS admin. +/api/search Search index endpoint (fumadocs search). +/rss.xml Atom/RSS feed. + +Developer notes +--------------- + +Prefer ./start-database.sh to boot Postgres locally; the script warns if the port is in use. +Auth and comment tables use the blog_prefix; keep drizzle.config.ts tablesFilter in sync. +Payload dev mode pre-fills / admin123 to speed up admin login. +If you only need to browse the UI without real data, set SKIP_ENV_VALIDATION=1 and disable features needing external services; full env is recommended for complete coverage. diff --git a/README-zh b/README-zh new file mode 100644 index 0000000..ce565f3 --- /dev/null +++ b/README-zh @@ -0,0 +1,115 @@ +Next blog +========= + +基于 Next.js 15 与 Payload CMS 的全栈博客，内置认证、评论、搜索、RSS 和邮件模板。 + +项目简介 +-------- + +前端使用 Next.js App Router 配合 Tailwind 和 shadcn，并借助 fumadocs 的组件搭建导航、分页与搜索。 +内容由 Payload CMS（payload.config.ts）管理，支持富文本、标签、封面图与发布状态。 +认证使用 better-auth，支持 Google 和 GitHub；会话与评论通过 Drizzle ORM 写入 Postgres。 +评论集成 @fuma-comment，站点同时生成 /rss.xml 订阅源与 /api/search 搜索索引。 + +主要特性 +-------- + +文章管理：Payload 后台 /admin 可创建草稿或已发布文章，支持封面、标签与定时发布时间。 +博客体验：列表分页、标签聚合页、文章详情富文本渲染、分享按钮、一键复制链接。 +社交与互动：Google 或 GitHub 登录，better-auth 会话管理，Fuma Comment 评论存储在本地数据库。 +增强能力：RSS 输出、站内搜索索引、自动 Open Graph Banner、next-sitemap 生成站点地图。 +邮件模板：emails/newsletter-welcome.tsx 提供 React Email + Tailwind 的欢迎邮件，可接入 Resend。 +运维友好：.env 校验、start-database.sh 一键启动本地 Postgres，统一的 Drizzle 与 Payload 脚本。 + +技术栈 +------ + +框架：Next.js 15（App Router），服务端组件，静态与动态混合渲染。 +UI：Tailwind CSS 4、shadcn、fumadocs-ui，用于导航、分页、Section 和主题。 +内容：Payload CMS 管理 Posts、Users、Media，使用 Lexical 富文本。 +数据：PostgreSQL 与 Drizzle ORM，认证与评论表以 blog_* 作为前缀。 +认证：better-auth + OAuth（Google/GitHub），包含会话和额外角色字段。 +邮件：Resend 与 React Email，Tailwind 样式的欢迎模板。 + +快速开始 +-------- + +1. 安装工具链。推荐 Node 20+，使用 pnpm（已锁定 pnpm-lock.yaml）。 +2. 配置环境变量。复制 .env.example 为 .env，填写 DATABASE_URL、PAYLOAD_SECRET、BETTER_AUTH_SECRET，如需社交登录补齐 OAuth。 +3. 启动 Postgres。运行 ./start-database.sh（依赖 Docker/Podman），或连接自带的 Postgres 实例。 +4. 安装依赖并生成结构。执行 pnpm install；pnpm db:generate && pnpm db:migrate 处理 Drizzle；pnpm payload:migrate 同步 Payload CMS。 +5. 运行开发服务器。pnpm dev（默认 3000，后台 /admin，博客 /）。 +6. 可选步骤。pnpm payload:generate 生成类型；pnpm email:dev -p 3001 预览邮件模板。 +开发模式下，Payload 登录框会预填 admin@example.com / admin123。 + +核心模块 +-------- + +内容模型位于 payload.config.ts，定义文章、用户、媒体，支持封面上传、标签数组、发布时间与状态。 +数据访问封装在 src/lib/payload-posts.ts，用于文章查询、标签统计、分页与 slug 工具。 +页面与布局在 src/app/(main)，_components 内含 Hero、CTA、文章列表等 UI。 +认证与评论位于 src/server/auth（better-auth + Drizzle）和 src/server/comments（写入 blog_comments 表）。 +搜索与订阅在 src/app/(main)/api/search/route.ts（索引）与 src/app/(main)/rss.xml/route.ts（Atom/RSS）。 +邮件模板是 emails/newsletter-welcome.tsx，可接受文章数组渲染卡片。 + +项目结构（节选） +---------------- + +src/ + app/ + (main)/(home)/page.tsx 首页：Hero、最近文章、CTA + (main)/(home)/posts/[slug]/page.tsx 文章详情、评论、分享 + (main)/(home)/posts/page.tsx 分页文章列表 + (main)/(home)/tags/page.tsx 标签聚合 + (main)/api/search/route.ts 搜索索引接口 + (main)/rss.xml/route.ts Atom/RSS 输出 + (payload)/admin/... Payload CMS 后台 + lib/ 数据与工具（payload-posts、metadata、auth-client） + server/ better-auth 与 Drizzle schema，评论存储 + emails/ React Email 模板 + +环境变量 +-------- + +常用或必填项： + DATABASE_URL：Postgres 连接串，例如 postgresql://user:pass@localhost:5432/blog + PAYLOAD_SECRET：Payload CMS 的 JWT 密钥 + BETTER_AUTH_SECRET：better-auth 会话密钥 + BETTER_AUTH_URL：认证回调地址，本地可用 http://localhost:3000 + NEXT_PUBLIC_SERVER_URL：生成链接、OG、RSS 的基础地址 + RESEND_API_KEY / RESEND_AUDIENCE_ID / EMAIL_FROM：发送邮件所需 + GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET：启用 Google 登录时必填 + GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET：启用 GitHub 登录时必填 + NEXT_PUBLIC_UMAMI_URL / NEXT_PUBLIC_UMAMI_WEBSITE_ID：可选分析 + +常用脚本 +-------- + +pnpm dev 启动 Next.js 开发服务器（含 Payload routes） +pnpm build 构建生产包 +pnpm preview 预览生产构建 +pnpm db:generate 生成 Drizzle 迁移（认证/评论表） +pnpm db:migrate 执行 Drizzle 迁移 +pnpm payload:migrate 同步 Payload CMS 数据表 +pnpm lint 质量检查（biome） +pnpm format 代码格式化（biome） +pnpm email:dev 本地预览 React Email 模板 + +页面与接口 +---------- + +/ 首页，Hero、最新文章、CTA +/posts 文章分页；/posts/[slug] 展示详情、富文本、评论、分享 +/tags 标签云与计数 +/login Google/GitHub 登录入口 +/admin Payload CMS 后台 +/api/search 站内搜索索引接口（fumadocs search） +/rss.xml Atom/RSS 订阅 + +开发提示 +-------- + +优先使用 ./start-database.sh 启动本地 Postgres，脚本会提示端口占用。 +认证与评论表使用 blog_ 前缀，保持 drizzle.config.ts 中的 tablesFilter 一致。 +开发模式下 Payload 自动填充 / admin123，便于快速登录。 +只想浏览 UI 时可设置 SKIP_ENV_VALIDATION=1，并关闭依赖外部服务的功能；完整环境更可靠。 diff --git a/README-zh.md b/README-zh.md deleted file mode 100644 index a6b1d10..0000000 --- a/README-zh.md +++ /dev/null @@ -1,170 +0,0 @@ -
-

shadcn blog

-

基于 Next.js 15 + Payload CMS 的全栈博客，内置认证、评论、搜索、RSS 与邮件模版。

-

- Next.js 15 - React 19 - PostgreSQL - Payload CMS -

-
- -## 目录 - -- [目录](#目录) -- [项目简介](#项目简介) -- [主要特性](#主要特性) -- [技术栈](#技术栈) -- [快速开始](#快速开始) -- [核心模块速览](#核心模块速览) -- [环境变量](#环境变量) -- [常用脚本](#常用脚本) -- [页面与接口](#页面与接口) -- [开发提示](#开发提示) - -## 项目简介 - -- 前端采用 Next.js App Router，UI 基于 tailwind + shadcn，并用 fumadocs 的布局组件快速搭建导航、分页、搜索等。 -- 内容源由 Payload CMS 提供（`payload.config.ts`），支持富文本、标签、封面图与发布状态。 -- 认证使用 better-auth（Google/GitHub 登录），会话与评论数据通过 Drizzle ORM 写入 Postgres。 -- 评论系统集成 `@fuma-comment`，同时生成 `/rss.xml` 订阅源和 `/api/search` 搜索索引。 - -## 主要特性 - -- 文章管理：Payload 后台（`/admin`）可创建草稿/已发布文章，支持封面、标签与定时发布时间。 -- 博客体验：列表分页、标签聚合页、文章详情页富文本渲染、分享按钮、一键复制链接。 -- 社交与互动：Google/GitHub 登录、基于 better-auth 的会话管理，Fuma Comment 评论组件存储在本地数据库。 -- 增强功能：RSS 输出、站内搜索索引、自动 Open Graph/OG Banner、站点地图（`next-sitemap`）。 -- 邮件模版：`emails/newsletter-welcome.tsx` 提供 React Email/Tailwind 的欢迎邮件示例，可通过 Resend 发送。 -- 运维友好：`.env` 校验、`start-database.sh` 一键启动本地 Postgres、Drizzle/Payload 脚本统一管理数据库。 - -## 技术栈 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
领域选择说明
框架Next.js 15 (App Router)服务端组件、动态/静态混合渲染
UItailwindcss 4 + shadcn + fumadocs-ui快速搭建导航、分页、Section、主题切换
内容Payload CMSPosts/Users/Media 集合，Lexical 富文本
数据PostgreSQL + Drizzle ORM认证与评论表（前缀 blog_*）
认证better-auth + OAuth (Google/GitHub)社交登录、会话、额外角色字段
邮件Resend + React Email欢迎邮件模版、Tailwind 样式
- -## 快速开始 - -1) 安装依赖与 Node - - 推荐 Node 20+，包管理器使用 `pnpm`（已锁定 `pnpm-lock.yaml`）。 -2) 配置环境变量 - - 复制 `.env.example` 为 `.env`，至少填写 `DATABASE_URL`、`PAYLOAD_SECRET`、`BETTER_AUTH_SECRET`，如需社交登录再补齐 OAuth。 -3) 启动本地数据库（Postgres） - - `./start-database.sh`（依赖 Docker/Podman）或使用自带的 Postgres 实例。 -4) 安装依赖并生成数据库结构 - - `pnpm install` - - `pnpm db:generate && pnpm db:migrate`（Drizzle 认证/评论表） - - `pnpm payload:migrate`（Payload CMS 表） -5) 运行开发服务 - - `pnpm dev`（默认监听 3000，Payload Admin `/admin`，博客 `/`）。 -6) 可选：生成 Payload Types 与邮件预览 - - `pnpm payload:generate` - - `pnpm email:dev -p 3001` 查看邮件模版。 - -> 开发模式下 Payload 会自动填充 `admin@example.com` / `admin123` 登录框，无需手动创建账户。 - -## 核心模块速览 - -- 内容模型：`payload.config.ts` 定义 Posts/Users/Media，文章支持封面上传、标签数组、发布时间与状态。 -- 数据获取：`src/lib/payload-posts.ts` 统一封装文章查询、标签统计、分页与 slug 获取，供页面调用。 -- 页面与布局：`src/app/(main)` 为站点主入口，`_components` 目录包含 Hero、CTA、Post 列表等 UI。 -- 认证与评论：`src/server/auth`（better-auth + Drizzle），`src/server/comments` 将评论存入 `blog_comments` 表。 -- 搜索与订阅：`src/app/(main)/api/search/route.ts` 动态生成索引；`src/app/(main)/rss.xml/route.ts` 输出 Atom feed。 -- 邮件：`emails/newsletter-welcome.tsx` React Email 模版，可传入最新文章数组渲染卡片。 - -项目结构（节选）： - -```text -src/ -├── app/ -│ ├── (main)/(home)/page.tsx # 首页：Hero、最近文章、CTA -│ ├── (main)/(home)/posts/[slug]/page.tsx # 文章详情 + 评论 + 分享 -│ ├── (main)/(home)/posts/page.tsx # 分页文章列表 -│ ├── (main)/(home)/tags/page.tsx # 标签聚合 -│ ├── (main)/api/search/route.ts # 站内搜索索引 -│ ├── (main)/rss.xml/route.ts # Atom/RSS 输出 -│ └── (payload)/admin/... # Payload CMS 后台 -├── lib/ # 数据与工具（payload-posts、metadata、auth-client） -├── server/ # better-auth + Drizzle schema + comment storage -└── emails/ # React Email 模版 -``` - -## 环境变量 - -
-必填与可选 - -| 变量 | 说明 | -| --- | --- | -| `DATABASE_URL` | Postgres 连接串，例如 `postgresql://user:pass@localhost:5432/blog` | -| `PAYLOAD_SECRET` | Payload CMS 用于 JWT 加密的密钥 | -| `BETTER_AUTH_SECRET` | better-auth session 密钥 | -| `BETTER_AUTH_URL` | 认证回调地址（本地可设 `http://localhost:3000`） | -| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | 启用 Google 登录时必填 | -| `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` | 启用 GitHub 登录时必填 | -| `RESEND_API_KEY` / `RESEND_AUDIENCE_ID` / `EMAIL_FROM` | 发送邮件时必填 | -| `NEXT_PUBLIC_SERVER_URL` | 生成链接、OG、RSS 的基础地址 | -| `NEXT_PUBLIC_UMAMI_URL` / `NEXT_PUBLIC_UMAMI_WEBSITE_ID` | 可选，埋点统计 | - -
- -## 常用脚本 - -- `pnpm dev`：启动 Next.js 开发服务器（含 Payload routes）。 -- `pnpm build` / `pnpm preview`：构建与预览生产版本。 -- `pnpm db:generate` / `pnpm db:migrate`：生成并执行 Drizzle 迁移（认证/评论表）。 -- `pnpm payload:migrate`：同步 Payload CMS 数据表。 -- `pnpm lint` / `pnpm format`：质量与格式检查（biome）。 -- `pnpm email:dev`：本地预览 React Email 模版。 - -## 页面与接口 - -- `/`：首页，展示 Hero、最新文章、CTA。 -- `/posts`：文章分页列表；`/posts/[slug]`：详情页、富文本、评论、分享。 -- `/tags`：标签云与计数。 -- `/login`：Google/GitHub 登录入口。 -- `/admin`：Payload CMS 后台。 -- `/api/search`：搜索索引接口（fumadocs search）。 -- `/rss.xml`：Atom/RSS 订阅。 - -## 开发提示 - -- 本地优先运行 `./start-database.sh` 启动 Postgres；若端口占用脚本会提示。 -- 认证与评论表前缀为 `blog_`，确保 `drizzle.config.ts` 里的 `tablesFilter` 与迁移脚本保持一致。 -- Payload 在开发环境会预填 `admin@example.com` / `admin123`，方便快速登录后台。 -- 如果只想浏览前端而不接入真实数据，可设置 `SKIP_ENV_VALIDATION=1` 并禁用需要外部服务的功能，但推荐补齐变量以覆盖所有页面。 diff --git a/README.md b/README.md deleted file mode 100644 index 24e47a8..0000000 --- a/README.md +++ /dev/null @@ -1,169 +0,0 @@ -
-

shadcn blog

-

A full-stack blog built with Next.js 15 + Payload CMS, shipping auth, comments, search, RSS, and email templates out of the box.

-

- Next.js 15 - React 19 - PostgreSQL - Payload CMS -

-
- -## Table of Contents - -- [Overview](#overview) -- [Features](#features) -- [Tech Stack](#tech-stack) -- [Quickstart](#quickstart) -- [Core Modules](#core-modules) -- [Environment Variables](#environment-variables) -- [Scripts](#scripts) -- [Routes & APIs](#routes--apis) -- [Developer Notes](#developer-notes) - -## Overview - -- Frontend uses Next.js App Router with Tailwind + shadcn, and fumadocs layout pieces for navigation, pagination, and search. -- Content is managed by Payload CMS (`payload.config.ts`), supporting rich text, tags, cover images, and publish states. -_- Authentication via better-auth (Google/GitHub), sessions and comments stored in Postgres through Drizzle ORM._ -- Comments are powered by `@fuma-comment`, and the site generates both `/rss.xml` feeds and `/api/search` indexes. - -## Features - -- Post management: Payload admin (`/admin`) creates drafts/published posts with cover image, tags, and scheduled publish time. -- Blog UX: paginated lists, tag hub, rich post detail rendering, share button, one-click copy link. -- Social & interaction: Google/GitHub login, better-auth session management, Fuma Comment stored locally. -- Enhancements: RSS feed, on-the-fly search index, automatic Open Graph/OG banners, sitemap via `next-sitemap`. -- Email template: `emails/newsletter-welcome.tsx` using React Email + Tailwind, ready for Resend. -- Ops-friendly: `.env` validation, `start-database.sh` to boot local Postgres, unified Drizzle/Payload scripts for schema. - -## Tech Stack - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
AreaChoiceNotes
FrameworkNext.js 15 (App Router)Server Components with hybrid static/dynamic rendering
UITailwind CSS 4 + shadcn + fumadocs-uiNavigation, pagination, sections, theming
ContentPayload CMSPosts/Users/Media collections, Lexical rich text
DataPostgreSQL + Drizzle ORMAuth and comments tables (prefix blog_*)
Authbetter-auth + OAuth (Google/GitHub)Social login, sessions, extra role field
EmailResend + React EmailWelcome template, Tailwind styling
- -## Quickstart - -1) Install toolchain - - Node 20+ recommended, use `pnpm` (locked by `pnpm-lock.yaml`). -2) Set environment variables - - Copy `.env.example` to `.env`; fill `DATABASE_URL`, `PAYLOAD_SECRET`, `BETTER_AUTH_SECRET`, and OAuth keys if needed. -3) Start Postgres locally - - `./start-database.sh` (Docker/Podman) or your own Postgres instance. -4) Install deps and build schema - - `pnpm install` - - `pnpm db:generate && pnpm db:migrate` (Drizzle auth/comments tables) - - `pnpm payload:migrate` (Payload CMS tables) -5) Run dev server - - `pnpm dev` (default :3000; Payload Admin `/admin`, blog `/`). -6) Optional extras - - `pnpm payload:generate` (types) - - `pnpm email:dev -p 3001` (preview email template). - -> In development, Payload pre-fills `admin@example.com` / `admin123` on the login form. - -## Core Modules - -- Content model: `payload.config.ts` defines Posts/Users/Media with cover uploads, tag arrays, publish time, and status. -- Data fetching: `src/lib/payload-posts.ts` wraps post queries, tag stats, pagination, and slug helpers for pages. -- Pages & layout: `src/app/(main)` hosts the site; `_components` includes Hero, CTA, and post list UI. -- Auth & comments: `src/server/auth` (better-auth + Drizzle) and `src/server/comments` storing into `blog_comments` tables. -- Search & feed: `src/app/(main)/api/search/route.ts` builds indexes; `src/app/(main)/rss.xml/route.ts` emits Atom/RSS. -- Email: `emails/newsletter-welcome.tsx` React Email template that accepts a posts array. - -Project structure (excerpt): - -```text -src/ -├── app/ -│ ├── (main)/(home)/page.tsx # Home: hero, recent posts, CTA -│ ├── (main)/(home)/posts/[slug]/page.tsx # Post detail + comments + share -│ ├── (main)/(home)/posts/page.tsx # Paginated posts list -│ ├── (main)/(home)/tags/page.tsx # Tag hub -│ ├── (main)/api/search/route.ts # Search index API -│ ├── (main)/rss.xml/route.ts # Atom/RSS feed -│ └── (payload)/admin/... # Payload CMS admin -├── lib/ # Data + utilities (payload-posts, metadata, auth-client) -├── server/ # better-auth + Drizzle schema + comment storage -└── emails/ # React Email templates -``` - -## Environment Variables - -
-Required & optional - -| Variable | Description | -| --- | --- | -| `DATABASE_URL` | Postgres connection string, e.g. `postgresql://user:pass@localhost:5432/blog` | -| `PAYLOAD_SECRET` | Secret used by Payload CMS for JWT | -| `BETTER_AUTH_SECRET` | better-auth session secret | -| `BETTER_AUTH_URL` | Auth callback base (local: `http://localhost:3000`) | -| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | Required if enabling Google login | -| `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` | Required if enabling GitHub login | -| `RESEND_API_KEY` / `RESEND_AUDIENCE_ID` / `EMAIL_FROM` | Required for sending emails | -| `NEXT_PUBLIC_SERVER_URL` | Base URL for links/OG/RSS | -| `NEXT_PUBLIC_UMAMI_URL` / `NEXT_PUBLIC_UMAMI_WEBSITE_ID` | Optional analytics | - -
- -## Scripts - -- `pnpm dev`: Start Next.js dev server (includes Payload routes). -- `pnpm build` / `pnpm preview`: Build and preview production. -- `pnpm db:generate` / `pnpm db:migrate`: Generate and run Drizzle migrations (auth/comments). -- `pnpm payload:migrate`: Sync Payload CMS tables. -- `pnpm lint` / `pnpm format`: Quality and formatting checks (biome). -- `pnpm email:dev`: Preview React Email templates locally. - -## Routes & APIs - -- `/`: Home with hero, latest posts, CTA. -- `/posts`: Paginated posts; `/posts/[slug]`: detail with rich text, comments, share. -- `/tags`: Tag cloud with counts. -- `/login`: Google/GitHub login entry. -- `/admin`: Payload CMS admin. -- `/api/search`: Search index endpoint (fumadocs search). -- `/rss.xml`: Atom/RSS feed. - -## Developer Notes - -- Prefer `./start-database.sh` to boot Postgres locally; the script warns if the port is in use. -- Auth/comment tables use the `blog_` prefix—keep `drizzle.config.ts` `tablesFilter` in sync. -- Payload dev mode pre-fills `admin@example.com` / `admin123` to speed up admin login. -- If you only need to browse the UI without real data, set `SKIP_ENV_VALIDATION=1` and disable features needing external services; full env is recommended for complete coverage. -- cgit v1.2.3