@fecommunity/reactpress-theme-starter 1.0.0-beta.0

package/.env.example

@@ -0,0 +1,22 @@
+# ReactPress API (SSR — Next.js server requests)
+REACTPRESS_API_URL=http://localhost:3002/api
+
+# Browser CSR requests (same as SSR, or use same-origin /api via rewrites)
+NEXT_PUBLIC_REACTPRESS_API_URL=http://localhost:3002/api
+
+# Public site URL (SEO / sitemap / Open Graph)
+CLIENT_SITE_URL=http://localhost:3001
+
+# Subpath deployment (optional)
+# BASE_PATH=/blog
+
+# ── Mock mode (offline demo / CI / Vercel starter deploy) ───────────────────
+# REACTPRESS_MOCK_API=1
+
+# ── Remote API during dev (equivalent to --remote-origin) ───────────────────
+# REACTPRESS_DEV_REMOTE_ORIGIN=https://api.yoursite.com
+
+# ── Production (Vercel / self-hosted) ───────────────────────────────────────
+# REACTPRESS_API_URL=https://api.yoursite.com/api
+# NEXT_PUBLIC_REACTPRESS_API_URL=/api
+# CLIENT_SITE_URL=https://www.yoursite.com

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ReactPress / FECommunity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,286 @@
+<div align="center">
+
+<a href="https://reactpress.surge.sh/">
+  <img src="./public/logo.png" alt="ReactPress" width="480" />
+</a>
+
+<br />
+
+**ReactPress Theme Starter**
+
+A lightweight, simple, and easy-to-use Next.js theme, powered by [ReactPress](https://github.com/fecommunity/reactpress).
+
+<a href="https://reactpress-theme-starter.vercel.app">
+  <img src="./public/home-dark.png" alt="ReactPress Theme Starter preview" width="100%" />
+</a>
+
+<br />
+
+[Live Demo](https://reactpress-theme-starter.vercel.app) · [Documentation](https://reactpress.surge.sh/) · [简体中文](./README_zh.md)
+
+<br />
+
+<img src="https://img.shields.io/badge/Next.js_15-000?style=flat-square&logo=next.js&logoColor=white" alt="Next.js 15" />
+<img src="https://img.shields.io/badge/React_19-61dafb?style=flat-square&logo=react&logoColor=white" alt="React 19" />
+<img src="https://img.shields.io/badge/Tailwind_4-38bdf8?style=flat-square&logo=tailwindcss&logoColor=white" alt="Tailwind CSS 4" />
+<img src="https://img.shields.io/badge/TypeScript-0074c1?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" />
+<img src="https://img.shields.io/badge/License-MIT-22c55e?style=flat-square" alt="MIT License" />
+<a href="https://github.com/fecommunity/reactpress-theme-starter/stargazers">
+  <img src="https://img.shields.io/github/stars/fecommunity/reactpress-theme-starter?style=flat-square&logo=github" alt="GitHub stars" />
+</a>
+
+<br />
+
+**If this project helps you, a ⭐ on GitHub helps others discover it.**
+
+</div>
+
+---
+
+## Try in 60 seconds (no backend)
+
+Preview the full theme UI with built-in sample data — no ReactPress install required.
+
+### Option A — `create-next-app` (recommended)
+
+Bootstrap from this repository with the [official Next.js CLI](https://nextjs.org/docs/app/api-reference/cli/create-next-app):
+
+```bash
+npx create-next-app@latest reactpress-theme-starter --example "https://github.com/fecommunity/reactpress-theme-starter" --use-pnpm
+cd reactpress-theme-starter
+pnpm dev:mock
+```
+
+### Option B — clone manually
+
+```bash
+git clone https://github.com/fecommunity/reactpress-theme-starter.git
+cd reactpress-theme-starter
+pnpm install
+pnpm dev:mock
+```
+
+Open **http://localhost:3001** — same mode as the [live demo](https://reactpress-theme-starter.vercel.app).
+
+### Deploy to Vercel (zero env vars)
+
+One-click deploy uses [`vercel.json`](./vercel.json) with mock data — no backend required.
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Ffecommunity%2Freactpress-theme-starter&project-name=reactpress-theme&repository-name=reactpress-theme&demo-title=ReactPress%20Theme%20Starter&demo-description=Next.js%2015%20headless%20blog%20theme%20with%20mock%20mode%20%E2%80%94%20no%20backend%20required&demo-url=https%3A%2F%2Freactpress-theme-starter.vercel.app&demo-image=https%3A%2F%2Fraw.githubusercontent.com%2Ffecommunity%2Freactpress-theme-starter%2Fmaster%2Fpublic%2Fhome-dark.png)
+
+---
+
+## What is this?
+
+This repository is the **public-facing theme** for ReactPress: routing, layout, SEO, and UI. It does **not** include a CMS or admin panel — all content comes from a ReactPress backend via [`@fecommunity/reactpress-toolkit`](https://www.npmjs.com/package/@fecommunity/reactpress-toolkit).
+
+```text
+ReactPress API  ──REST──▶  Theme Starter (Next.js)  ──▶  Public Site
+```
+
+**Stack:** Next.js 15 · React 19 · Tailwind CSS 4 · Node.js 20+ · pnpm 9
+
+**Includes:** articles, archives, search, CMS pages, knowledge base, comments, light/dark mode, RSS/sitemap, and an optional embedded mock API for offline development.
+
+### Why this theme?
+
+|                           | ReactPress Theme Starter                                                 | Generic Next.js blog template |
+| :------------------------ | :----------------------------------------------------------------------- | :---------------------------- |
+| CMS & admin               | ✅ [ReactPress](https://github.com/fecommunity/reactpress) backend + CLI | ❌ Build or wire your own     |
+| Try without backend       | ✅ `pnpm dev:mock`                                                       | ❌ Usually needs content/API  |
+| Knowledge base & comments | ✅ Built-in                                                              | ❌ Roll your own              |
+| Customizable appearance   | ✅ Admin console + `theme.json`                                          | ❌ Hard-coded or manual       |
+
+---
+
+## Quick Start
+
+**Requirements:** Node.js 20+, pnpm 9+
+
+### Recommended — ReactPress CLI
+
+The fastest way to run a full stack (visitor site, admin console, and API) is the [ReactPress CLI](https://reactpress.surge.sh/). No manual `.env` wiring for a standard setup.
+
+```bash
+npm i -g @fecommunity/reactpress@3
+reactpress init
+reactpress dev
+```
+
+<div align="center">
+
+<img src="./public/cli.png" alt="ReactPress CLI interactive menu" width="100%" />
+
+</div>
+
+After startup, open the URLs printed in the terminal (typically the public site, admin, and API). Use `reactpress doctor` if something fails to start.
+
+**Use this theme with the CLI**
+
+1. Clone this repository and install dependencies (`pnpm install`).
+2. Start the API with `reactpress dev --api-only` (or run the full stack and point the theme at the API).
+3. Copy [`.env.example`](./.env.example) to `.env` if needed — default local API is `http://localhost:3002/api`.
+4. In the theme directory, run:
+
+```bash
+pnpm dev
+```
+
+Open **http://localhost:3001** — the theme loads live content from your ReactPress API.
+
+Remote API during development:
+
+```bash
+pnpm dev -- --remote-origin api.yoursite.com
+```
+
+### Local theme preview (mock — no backend)
+
+To work on UI, layout, or styling **without** installing ReactPress or running the API, use the built-in mock server:
+
+```bash
+git clone https://github.com/fecommunity/reactpress-theme-starter.git
+cd reactpress-theme-starter
+pnpm install
+pnpm dev:mock
+```
+
+Open **http://localhost:3001** — sample data comes from [`lib/mock-api/data.ts`](./lib/mock-api/data.ts). This is the same mode used by the [Vercel demo](https://reactpress-theme-starter.vercel.app).
+
+---
+
+## Commands
+
+| Command              | Purpose                                                       |
+| :------------------- | :------------------------------------------------------------ |
+| `pnpm dev`           | Theme dev server + live ReactPress API (CLI or remote)        |
+| `pnpm dev:mock`      | Theme dev server + built-in mock API (no backend)             |
+| `pnpm build:mock`    | Production build with mock data (Vercel demo / offline build) |
+| `pnpm build`         | Production build (API must be reachable at build time)        |
+| `pnpm start`         | Run production server on port **3001**                        |
+| `pnpm run check`     | ESLint + Prettier                                             |
+| `pnpm run typecheck` | TypeScript check                                              |
+
+For full-stack local development (site + admin + API), prefer **`reactpress dev`** from the ReactPress CLI — see [Quick Start](#quick-start).
+
+---
+
+## Configuration
+
+When using **`pnpm dev`** against a live API, copy [`.env.example`](./.env.example) to `.env`. Mock mode (`pnpm dev:mock`) and the ReactPress CLI handle most setup for you.
+
+| Variable                         | Description                                     |
+| :------------------------------- | :---------------------------------------------- |
+| `REACTPRESS_API_URL`             | Server-side API base URL (include `/api`)       |
+| `NEXT_PUBLIC_REACTPRESS_API_URL` | Client-side API URL; use `/api` for same-origin |
+| `CLIENT_SITE_URL`                | Public site URL for SEO and Open Graph          |
+| `REACTPRESS_MOCK_API`            | Set to `1` to enable the embedded mock API      |
+
+See `.env.example` for optional variables (subpath deploy, GitHub OAuth, remote dev origin).
+
+---
+
+## Deployment
+
+### Demo (Vercel)
+
+Import this repo as-is — [`vercel.json`](./vercel.json) uses `build:mock` with mock data. See [Deploy to Vercel](#deploy-to-vercel-zero-env-vars) above for the one-click button with live demo preview.
+
+> The [live demo](https://reactpress-theme-starter.vercel.app) runs in mock mode (UI + sample data only).
+
+### Production
+
+Deploy as a headless frontend pointed at your ReactPress API:
+
+1. Set `REACTPRESS_API_URL`, `NEXT_PUBLIC_REACTPRESS_API_URL`, and `CLIENT_SITE_URL`
+2. Build with `pnpm build` (not `build:mock`)
+3. Start with `pnpm start` or your platform's Next.js runtime
+
+`pnpm build` prefetches pages from the API — ensure the API is reachable at build time.
+
+---
+
+## Project Layout
+
+```text
+app/           App Router pages, feeds, sitemap, mock API route
+components/    Layout, article, search, widgets
+lib/           mock-api/, reactpress/ utilities
+scripts/       dev, build, and smoke-test scripts
+theme.json     Theme manifest (routes, appearance schema)
+```
+
+Route templates are declared in [`theme.json`](./theme.json). Appearance (colors, logo, navigation) is configured in the ReactPress admin console.
+
+---
+
+## FAQ
+
+<details>
+<summary><strong>Do I need ReactPress to preview the theme?</strong></summary>
+
+No. Run `pnpm dev:mock` for a full UI preview with sample data. Install [ReactPress CLI](https://reactpress.surge.sh/) when you want a real CMS, admin panel, and API.
+
+</details>
+
+<details>
+<summary><strong>How is this different from WordPress or Ghost themes?</strong></summary>
+
+This is a **headless frontend** — content lives in ReactPress (REST API + admin). You deploy the Next.js theme separately and point it at your API. See [ReactPress docs](https://reactpress.surge.sh/) for the full stack.
+
+</details>
+
+<details>
+<summary><strong>Can I use my own Next.js components or fork the theme?</strong></summary>
+
+Yes. MIT licensed. Customize components under `app/` and `components/`, or declare routes in [`theme.json`](./theme.json). Pull requests welcome — see [Contributing](./CONTRIBUTING.md).
+
+</details>
+
+<details>
+<summary><strong>Where do I report bugs in the CMS or CLI?</strong></summary>
+
+Theme issues → [this repo](https://github.com/fecommunity/reactpress-theme-starter/issues). Core ReactPress (API, admin, CLI) → [fecommunity/reactpress](https://github.com/fecommunity/reactpress/issues).
+
+</details>
+
+---
+
+## Community
+
+| Channel         | Link                                                                                      |
+| :-------------- | :---------------------------------------------------------------------------------------- |
+| Q&A & showcase  | [GitHub Discussions](https://github.com/fecommunity/reactpress-theme-starter/discussions) |
+| Bug reports     | [Issues](https://github.com/fecommunity/reactpress-theme-starter/issues)                  |
+| ReactPress core | [github.com/fecommunity/reactpress](https://github.com/fecommunity/reactpress)            |
+| Documentation   | [reactpress.surge.sh](https://reactpress.surge.sh/)                                       |
+
+---
+
+## Contributing
+
+|                                             |                                   |
+| :------------------------------------------ | :-------------------------------- |
+| [Contributing](./CONTRIBUTING.md)           | Setup, conventions, pull requests |
+| [Contributing (中文)](./CONTRIBUTING_zh.md) | 中文贡献指南                      |
+| [Code of Conduct](./CODE_OF_CONDUCT.md)     | Community standards               |
+| [Security](./SECURITY.md)                   | Report vulnerabilities            |
+
+---
+
+## Links
+
+|                   |                                                                                                  |
+| :---------------- | :----------------------------------------------------------------------------------------------- |
+| ReactPress docs   | [reactpress.surge.sh](https://reactpress.surge.sh/)                                              |
+| ReactPress source | [github.com/fecommunity/reactpress](https://github.com/fecommunity/reactpress)                   |
+| Toolkit           | [@fecommunity/reactpress-toolkit](https://www.npmjs.com/package/@fecommunity/reactpress-toolkit) |
+| Theme schema      | [theme.manifest.schema.json](./theme.manifest.schema.json)                                       |
+
+<br />
+
+<div align="center">
+
+[MIT License](./LICENSE) · © ReactPress / FECommunity
+
+</div>

package/app/api/[[...path]]/route.ts

@@ -0,0 +1,69 @@
+import { isMockApiEnabled } from '@/lib/mock-api/config'
+import { corsPreflightResponse, withCors } from '@/lib/mock-api/cors'
+import { matchMockRoute } from '@/lib/mock-api/match-route'
+import { proxyToUpstreamApi } from '@/lib/mock-api/proxy'
+
+export const dynamic = 'force-dynamic'
+
+type RouteContext = {
+  params: Promise<{ path?: string[] }>
+}
+
+async function readJsonBody(request: Request): Promise<unknown> {
+  if (request.method === 'GET' || request.method === 'HEAD') return undefined
+  try {
+    const text = await request.text()
+    if (!text.trim()) return undefined
+    return JSON.parse(text) as unknown
+  } catch {
+    return undefined
+  }
+}
+
+async function handleRequest(request: Request, context: RouteContext): Promise<Response> {
+  if (request.method === 'OPTIONS') {
+    return corsPreflightResponse(request)
+  }
+
+  const { path = [] } = await context.params
+  const keyword = new URL(request.url).searchParams.get('keyword')?.trim() ?? ''
+  const body = await readJsonBody(request)
+
+  let response: Response
+  if (isMockApiEnabled()) {
+    const mockResponse = matchMockRoute(request.method, path, { keyword, body })
+    response = mockResponse ?? Response.json({ success: true, data: null })
+  } else {
+    response = await proxyToUpstreamApi(request, path)
+  }
+
+  return withCors(request, response)
+}
+
+export function GET(request: Request, context: RouteContext) {
+  return handleRequest(request, context)
+}
+
+export function POST(request: Request, context: RouteContext) {
+  return handleRequest(request, context)
+}
+
+export function PUT(request: Request, context: RouteContext) {
+  return handleRequest(request, context)
+}
+
+export function PATCH(request: Request, context: RouteContext) {
+  return handleRequest(request, context)
+}
+
+export function DELETE(request: Request, context: RouteContext) {
+  return handleRequest(request, context)
+}
+
+export function HEAD(request: Request, context: RouteContext) {
+  return handleRequest(request, context)
+}
+
+export function OPTIONS(request: Request, context: RouteContext) {
+  return handleRequest(request, context)
+}

package/app/archives/page.tsx

@@ -0,0 +1,28 @@
+import ArchivesClient from '@/components/views/ArchivesClient'
+import { buildLocalizedListPageMetadata } from '@/lib/reactpress/siteMetadata'
+import {
+  fetchArchivesPageProps,
+  themeApi,
+  withApiRetry,
+  type ArchiveTree,
+} from '@fecommunity/reactpress-toolkit/theme/server'
+import type { Metadata } from 'next'
+
+export const revalidate = 60
+
+export async function generateMetadata(): Promise<Metadata> {
+  return buildLocalizedListPageMetadata('archives', undefined, { path: '/archives' })
+}
+
+export default async function ArchivesPage() {
+  let articles: ArchiveTree = {}
+
+  try {
+    const data = await withApiRetry(() => fetchArchivesPageProps(themeApi))
+    articles = data.articles
+  } catch (error) {
+    console.error('[reactpress-theme-starter] archives fetch failed', error)
+  }
+
+  return <ArchivesClient articles={articles} />
+}

package/app/article/[id]/page.tsx

@@ -0,0 +1,92 @@
+import ArticleViewClient from '@/components/article/ArticleViewClient'
+import {
+  buildArticleJsonLd,
+  buildArticleMetadata,
+  parseSiteSeoContext,
+} from '@/lib/reactpress/contentSeo'
+import { generateArticleStaticParams } from '@/lib/reactpress/staticParams'
+import {
+  fetchArticleDetailProps,
+  fetchSiteMeta,
+  resolveImageUrl,
+  themeApi,
+  unwrapSetting,
+  withApiRetry,
+} from '@fecommunity/reactpress-toolkit/theme/server'
+import type { Metadata } from 'next'
+import { notFound } from 'next/navigation'
+
+export const revalidate = 60
+
+export async function generateStaticParams() {
+  return generateArticleStaticParams()
+}
+
+interface PageProps {
+  params: Promise<{ id: string }>
+}
+
+function resolveAbsoluteImageUrl(cover: string | undefined, siteUrl?: string) {
+  if (!cover) return undefined
+  const imageUrl = resolveImageUrl(cover, 'large')
+  if (!siteUrl) return imageUrl
+  try {
+    return new URL(imageUrl, siteUrl).href
+  } catch {
+    return imageUrl
+  }
+}
+
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+  const { id } = await params
+
+  try {
+    const [{ article }, siteMeta, settingRow] = await Promise.all([
+      withApiRetry(() => fetchArticleDetailProps(themeApi, id)),
+      withApiRetry(() => fetchSiteMeta(themeApi)),
+      withApiRetry(() => themeApi.setting.findAll()).then(unwrapSetting),
+    ])
+
+    if (!article?.id || article.status !== 'publish') {
+      return {}
+    }
+
+    const site = parseSiteSeoContext(settingRow, siteMeta)
+    const imageUrl = resolveAbsoluteImageUrl(article.cover, site.siteUrl)
+    return buildArticleMetadata(article, site, imageUrl)
+  } catch (error) {
+    console.error('[reactpress-theme-starter] article metadata fetch failed', error)
+    return {}
+  }
+}
+
+export default async function ArticlePage({ params }: PageProps) {
+  const { id } = await params
+
+  try {
+    const [{ article }, siteMeta] = await Promise.all([
+      withApiRetry(() => fetchArticleDetailProps(themeApi, id)),
+      withApiRetry(() => fetchSiteMeta(themeApi)),
+    ])
+
+    if (!article?.id || article.status !== 'publish') {
+      notFound()
+    }
+
+    const coverUrl = resolveAbsoluteImageUrl(article.cover, siteMeta.siteUrl)
+    const jsonLd = buildArticleJsonLd(article, siteMeta.siteUrl, coverUrl)
+
+    return (
+      <>
+        <script
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+        />
+        <ArticleViewClient article={article} />
+      </>
+    )
+  } catch (error) {
+    console.error('[reactpress-theme-starter] article page fetch failed', error)
+    notFound()
+  }
+}

package/app/category/[category]/page.tsx

@@ -0,0 +1,60 @@
+import CategoryClient from '@/components/views/CategoryClient'
+import { buildLocalizedListPageMetadata } from '@/lib/reactpress/siteMetadata'
+import { generateCategoryStaticParams } from '@/lib/reactpress/staticParams'
+import {
+  fetchCategoryArchivePageProps,
+  themeApi,
+  withApiRetry,
+} from '@fecommunity/reactpress-toolkit/theme/server'
+import type { Metadata } from 'next'
+import { notFound } from 'next/navigation'
+
+export const revalidate = 60
+
+export async function generateStaticParams() {
+  return generateCategoryStaticParams()
+}
+
+interface PageProps {
+  params: Promise<{ category: string }>
+}
+
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+  const { category } = await params
+  const categoryValue = decodeURIComponent(category)
+
+  try {
+    const data = await withApiRetry(() => fetchCategoryArchivePageProps(themeApi, categoryValue))
+    const label = data.category?.label || categoryValue
+    return buildLocalizedListPageMetadata(
+      'pageTitleCategory',
+      { label },
+      {
+        path: `/category/${encodeURIComponent(categoryValue)}`,
+      }
+    )
+  } catch {
+    return buildLocalizedListPageMetadata(
+      'pageTitleCategory',
+      { label: categoryValue },
+      {
+        path: `/category/${encodeURIComponent(categoryValue)}`,
+      }
+    )
+  }
+}
+
+export default async function CategoryArchivePage({ params }: PageProps) {
+  const { category } = await params
+  const categoryValue = decodeURIComponent(category)
+
+  try {
+    const data = await withApiRetry(() => fetchCategoryArchivePageProps(themeApi, categoryValue))
+    return (
+      <CategoryClient initialArticles={data.articles} total={data.total} category={data.category} />
+    )
+  } catch (error) {
+    console.error('[reactpress-theme-starter] category archive fetch failed', error)
+    notFound()
+  }
+}