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

package/scripts/smoke-pages.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * Smoke-test all theme routes against a running dev:mock server.
+ * Usage: node scripts/smoke-pages.mjs [baseUrl]
+ */
+const base = (process.argv[2] || 'http://127.0.0.1:3040').replace(/\/$/, '')
+
+const pages = [
+  ['/', 200],
+  ['/article/what-is-reactpress/', 200],
+  ['/article/quick-start/', 200],
+  ['/article/platform-capabilities/', 200],
+  ['/article/cli-reference/', 200],
+  ['/article/deploy-reactpress/', 200],
+  ['/article/theme-starter/', 200],
+  ['/category/quick-start/', 200],
+  ['/category/platform/', 200],
+  ['/category/cli-deploy/', 200],
+  ['/tag/reactpress/', 200],
+  ['/tag/nextjs/', 200],
+  ['/tags/', 200],
+  ['/archives/', 200],
+  ['/search/', 200],
+  ['/search/?keyword=reactpress', 200],
+  ['/suggestions/', 200],
+  ['/knowledge/', 200],
+  ['/knowledge/reactpress-handbook/', 200],
+  ['/knowledge/reactpress-handbook/cli-overview/', 200],
+  ['/knowledge/reactpress-handbook/api-endpoints/', 200],
+  ['/login/', 200],
+  ['/register/', 200],
+  ['/nav/rp-github/', 200],
+  ['/this-page-does-not-exist/', 404],
+  ['/rss/', 200],
+  ['/sitemap.xml', 200],
+  ['/robots.txt', 200],
+]
+
+const apis = [
+  ['POST', '/api/setting/get'],
+  ['POST', '/api/view'],
+  ['GET', '/api/article'],
+  ['GET', '/api/article/what-is-reactpress'],
+  ['POST', '/api/article/what-is-reactpress/views'],
+  ['GET', '/api/article/recommend?pageSize=15'],
+  ['GET', '/api/category'],
+  ['GET', '/api/tag'],
+  ['GET', '/api/page'],
+  ['GET', '/api/page/suggestions'],
+  ['POST', '/api/page/suggestions/views'],
+  ['GET', '/api/knowledge'],
+  ['GET', '/api/knowledge/reactpress-handbook'],
+  ['GET', '/api/knowledge/cli-overview'],
+  ['GET', '/api/search/article?keyword=reactpress'],
+  ['GET', '/api/comment/host/what-is-reactpress'],
+  ['POST', '/api/knowledge/reactpress-handbook/views'],
+]
+
+async function checkPage(path, expected) {
+  const res = await fetch(`${base}${path}`, { redirect: 'follow' })
+  const ok = res.status === expected
+  return { ok, status: res.status, path, expected }
+}
+
+async function checkApi(method, path) {
+  const res = await fetch(`${base}${path}`, {
+    method,
+    headers: method === 'POST' ? { 'Content-Type': 'application/json' } : undefined,
+    body: method === 'POST' ? '{}' : undefined,
+  })
+  let json = null
+  try {
+    json = await res.json()
+  } catch {
+    // non-json routes like robots.txt tested separately
+  }
+  const ok = res.ok && (json === null || json.success !== false)
+  return { ok, status: res.status, method, path, success: json?.success }
+}
+
+async function main() {
+  let failed = 0
+
+  console.log(`Smoke testing ${base}\n`)
+
+  console.log('--- Pages ---')
+  for (const [path, expected] of pages) {
+    const result = await checkPage(path, expected)
+    const mark = result.ok ? 'OK' : 'FAIL'
+    if (!result.ok) failed += 1
+    console.log(`${mark} ${result.status} (expected ${expected}) ${path}`)
+  }
+
+  console.log('\n--- APIs ---')
+  for (const [method, path] of apis) {
+    const result = await checkApi(method, path)
+    const mark = result.ok ? 'OK' : 'FAIL'
+    if (!result.ok) failed += 1
+    console.log(`${mark} ${result.status} ${method} ${path}`)
+  }
+
+  if (failed) {
+    console.log(`\n${failed} check(s) failed`)
+    process.exit(1)
+  }
+
+  console.log('\nAll checks passed')
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/scripts/start-mock.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * Production server with in-process mock API (after `pnpm build:mock`).
+ *
+ * Usage:
+ *   pnpm build:mock && pnpm start:mock
+ *   pnpm start:mock -- --port 3002
+ */
+import { spawn } from 'node:child_process'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { DEFAULT_THEME_DEV_PORT } from './resolve-api-env.mjs'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const projectRoot = path.resolve(__dirname, '..')
+
+function parseArgs(argv) {
+  let port = DEFAULT_THEME_DEV_PORT
+  const passthrough = []
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '-p' || arg === '--port') {
+      port = Number(argv[++i]) || DEFAULT_THEME_DEV_PORT
+      continue
+    }
+    if (arg.startsWith('--port=')) {
+      port = Number(arg.slice('--port='.length)) || DEFAULT_THEME_DEV_PORT
+      continue
+    }
+    passthrough.push(arg)
+  }
+
+  return { port, passthrough }
+}
+
+function buildEnv(port) {
+  const siteUrl = (process.env.CLIENT_SITE_URL || `http://localhost:${port}`).replace(/\/$/, '')
+  const serverApiUrl = `http://localhost:${port}/api`
+
+  return {
+    ...process.env,
+    INIT_CWD: projectRoot,
+    REACTPRESS_ORIGINAL_CWD: projectRoot,
+    REACTPRESS_MOCK_API: '1',
+    SERVER_API_URL: serverApiUrl,
+    REACTPRESS_API_URL: serverApiUrl,
+    NEXT_PUBLIC_REACTPRESS_API_URL: '/api',
+    CLIENT_SITE_URL: siteUrl,
+    NEXT_TELEMETRY_DISABLED: '1',
+  }
+}
+
+function main() {
+  const { port, passthrough } = parseArgs(process.argv.slice(2))
+  const nextBin = path.join(projectRoot, 'node_modules', 'next', 'dist', 'bin', 'next')
+
+  console.log('')
+  console.log('  ReactPress Theme (production + mock API)')
+  console.log(`  Local:  http://localhost:${port}`)
+  console.log(`  API:    /api (mock routes, same-origin in browser)`)
+  console.log('')
+
+  const child = spawn(process.execPath, [nextBin, 'start', '-p', String(port), ...passthrough], {
+    cwd: projectRoot,
+    env: buildEnv(port),
+    stdio: 'inherit',
+  })
+
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal)
+      return
+    }
+    process.exit(code ?? 0)
+  })
+}
+
+main()

package/scripts/verify-toolkit.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * Verify installed @fecommunity/reactpress-toolkit includes theme/* exports (3.1.0+).
+ */
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+
+const REQUIRED = [
+  '@fecommunity/reactpress-toolkit/theme/server',
+  '@fecommunity/reactpress-toolkit/theme/next-config',
+  '@fecommunity/reactpress-toolkit/ui',
+]
+
+const missing = REQUIRED.filter((spec) => {
+  try {
+    require.resolve(spec)
+    return false
+  } catch {
+    return true
+  }
+})
+
+if (missing.length === 0) {
+  console.log('[toolkit] theme/* exports OK')
+  process.exit(0)
+}
+
+console.error(`[toolkit] @fecommunity/reactpress-toolkit 缺少 theme/* 导出，请升级到 3.1.0+：
+
+  pnpm add @fecommunity/reactpress-toolkit@^3.1.0
+
+缺失路径：
+${missing.map((item) => `  - ${item}`).join('\n')}
+`)
+
+process.exit(1)

package/svg.d.ts

@@ -0,0 +1,6 @@
+declare module '*.svg' {
+  import type { FC, SVGProps } from 'react'
+
+  const ReactComponent: FC<SVGProps<SVGSVGElement>>
+  export default ReactComponent
+}

package/theme.json

@@ -0,0 +1,123 @@
+{
+  "$schema": "./theme.manifest.schema.json",
+  "id": "reactpress-theme-starter",
+  "name": "ReactPress Theme Starter",
+  "version": "1.0.0",
+  "description": "Tailwind 风格博客主题，Next.js App Router + ReactPress 动态内容，支持深浅色、评论、知识库与网址导航。",
+  "author": "ReactPress",
+  "authorUri": "https://reactpress.surge.sh/",
+  "themeUri": "https://github.com/fecommunity/reactpress-theme-starter",
+  "tags": ["博客", "Tailwind", "App Router", "ReactPress"],
+  "cover": "public/logo-400.png",
+  "requires": ">=3.0.0",
+  "supports": {
+    "darkMode": true,
+    "menus": ["primary"]
+  },
+  "templates": {
+    "404": "app/not-found.tsx",
+    "home": "app/page.tsx",
+    "single": "app/article/[id]/page.tsx",
+    "page": "app/page/[id]/page.tsx",
+    "archive-category": "app/category/[category]/page.tsx",
+    "archive-tag": "app/tag/[tag]/page.tsx",
+    "archives": "app/archives/page.tsx",
+    "search": "app/search/page.tsx"
+  },
+  "appearance": {
+    "panels": [
+      {
+        "id": "basic",
+        "title": "基础配置"
+      },
+      {
+        "id": "style",
+        "title": "样式配置"
+      }
+    ],
+    "sections": [
+      {
+        "id": "identity",
+        "panel": "basic",
+        "title": "站点身份",
+        "settings": [
+          {
+            "id": "displayTitle",
+            "type": "text",
+            "label": "站点标题",
+            "description": "留空则继承后台「站点标题」"
+          },
+          {
+            "id": "displayTagline",
+            "type": "text",
+            "label": "站点副标题",
+            "description": "留空则继承后台「站点副标题」"
+          },
+          {
+            "id": "siteLogo",
+            "type": "image",
+            "label": "站点 Logo"
+          }
+        ]
+      },
+      {
+        "id": "colors",
+        "panel": "style",
+        "title": "颜色",
+        "groups": [
+          {
+            "id": "light",
+            "title": "浅色模式"
+          },
+          {
+            "id": "dark",
+            "title": "深色模式"
+          }
+        ],
+        "settings": [
+          {
+            "id": "primaryColor",
+            "group": "light",
+            "type": "color",
+            "label": "主色",
+            "default": "#e11d48"
+          },
+          {
+            "id": "backgroundColor",
+            "group": "light",
+            "type": "color",
+            "label": "背景色",
+            "default": "#ffffff"
+          },
+          {
+            "id": "darkPrimaryColor",
+            "group": "dark",
+            "type": "color",
+            "label": "主色",
+            "default": "#fb7185"
+          },
+          {
+            "id": "darkBackgroundColor",
+            "group": "dark",
+            "type": "color",
+            "label": "背景色",
+            "default": "#030712"
+          }
+        ]
+      },
+      {
+        "id": "layout",
+        "panel": "basic",
+        "title": "布局",
+        "settings": [
+          {
+            "id": "stickyNav",
+            "type": "checkbox",
+            "label": "固定顶栏",
+            "default": "0"
+          }
+        ]
+      }
+    ]
+  }
+}

package/theme.manifest.schema.json

@@ -0,0 +1,265 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://reactpress.surge.sh/schemas/theme.manifest.json",
+  "title": "Theme Manifest",
+  "description": "Portable theme manifest for ReactPress and compatible platforms. Parsed by `parseThemeManifest()`; stored at `themes/{id}/theme.json`. Platform fields are top-level (no vendor namespace). Appearance controls map to WordPress theme_mod storage.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "name", "version"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference. Use \"../theme.manifest.schema.json\" for editor validation.",
+      "examples": ["../theme.manifest.schema.json"]
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "description": "Theme slug / Text Domain. Matches directory `themes/{id}/`, kebab-case.",
+      "examples": ["twentytwentyfive", "hello-world"]
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable theme name (WordPress Theme Name).",
+      "examples": ["Twenty Twenty-Five", "Hello World"]
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$",
+      "description": "Semantic version (WordPress Version header).",
+      "examples": ["3.0.4", "1.0.0"]
+    },
+    "description": { "type": "string", "description": "Theme description." },
+    "author": { "type": "string", "description": "Author name." },
+    "authorUri": { "type": "string", "description": "Author homepage URL." },
+    "themeUri": { "type": "string", "description": "Theme homepage or documentation URL." },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "description": "Theme tags for marketplace or admin filters."
+    },
+    "cover": {
+      "type": "string",
+      "description": "Theme cover image for admin theme list and preview. Path relative to theme root (recommended 1200×900, e.g. cover.png).",
+      "examples": ["cover.png", "public/cover.jpg"]
+    },
+    "requires": {
+      "type": "string",
+      "description": "Minimum host platform version (semver range). WordPress: Requires at least.",
+      "examples": [">=3.0.0"]
+    },
+    "supports": {
+      "type": "object",
+      "description": "Theme feature flags. WordPress: add_theme_support().",
+      "properties": {
+        "darkMode": { "type": "boolean", "description": "Visitor-facing light/dark toggle." },
+        "menus": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["primary", "footer", "social"] },
+          "description": "Registered navigation menu locations."
+        }
+      },
+      "additionalProperties": true
+    },
+    "templates": {
+      "type": "object",
+      "description": "Template hierarchy slug → page file path. WordPress Template Hierarchy.",
+      "propertyNames": {
+        "enum": [
+          "home",
+          "single",
+          "page",
+          "archive-category",
+          "archive-tag",
+          "archives",
+          "search",
+          "404"
+        ]
+      },
+      "additionalProperties": {
+        "type": "string",
+        "examples": ["pages/index.tsx", "pages/article/[id].tsx"]
+      }
+    },
+    "options": {
+      "$ref": "#/definitions/themeOptions"
+    },
+    "appearance": {
+      "type": "object",
+      "description": "Appearance editor: panels, sections, and theme_mod controls. Stored in `globalSetting.theme.mods[themeId]`.",
+      "additionalProperties": false,
+      "required": ["sections"],
+      "properties": {
+        "panels": {
+          "type": "array",
+          "description": "Sidebar navigation panels (WordPress Customizer panels).",
+          "items": { "$ref": "#/definitions/appearancePanel" }
+        },
+        "sections": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Appearance sections (WordPress Customizer sections).",
+          "items": { "$ref": "#/definitions/appearanceSection" }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "themeOptions": {
+      "type": "object",
+      "description": "JSON Schema for structured theme options. Persisted in `globalSetting.config[themeId]`.",
+      "required": ["type"],
+      "properties": {
+        "$schema": { "type": "string", "const": "http://json-schema.org/draft-07/schema#" },
+        "title": { "type": "string" },
+        "description": { "type": "string" },
+        "type": { "const": "object" },
+        "properties": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/definitions/optionsProperty" }
+        },
+        "required": { "type": "array", "items": { "type": "string" } },
+        "additionalProperties": { "type": "boolean" }
+      },
+      "additionalProperties": true
+    },
+    "optionsProperty": {
+      "type": "object",
+      "properties": {
+        "type": {},
+        "title": { "type": "string" },
+        "description": { "type": "string" },
+        "default": {},
+        "properties": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/definitions/optionsProperty" }
+        },
+        "items": { "$ref": "#/definitions/optionsProperty" },
+        "required": { "type": "array", "items": { "type": "string" } },
+        "additionalProperties": { "type": "boolean" },
+        "x-ui": {
+          "type": "object",
+          "description": "Admin UI metadata (schema-only, not persisted).",
+          "properties": {
+            "widget": {
+              "type": "string",
+              "examples": ["navLinkList", "urlConfigEditor", "navSearchEditor"]
+            },
+            "section": { "type": "string" },
+            "order": { "type": "number" },
+            "scope": { "type": "string", "enum": ["site", "locale"] },
+            "hidden": { "type": "boolean" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": true
+    },
+    "appearancePanel": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+          "examples": ["basic", "style", "layout"]
+        },
+        "title": { "type": "string" },
+        "description": { "type": "string" }
+      }
+    },
+    "appearanceSection": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-zA-Z0-9]*(?:-[a-z0-9]+)*$",
+          "examples": ["identity", "colors", "themeConfiguration"]
+        },
+        "panel": {
+          "type": "string",
+          "description": "Parent panel id (`appearance.panels[].id`)."
+        },
+        "title": { "type": "string" },
+        "description": { "type": "string" },
+        "embed": {
+          "type": "string",
+          "enum": ["options"],
+          "description": "Embed the theme `options` schema form instead of inline controls."
+        },
+        "groups": {
+          "type": "array",
+          "description": "Control groups within the section (e.g. light / dark palettes).",
+          "items": { "$ref": "#/definitions/appearanceGroup" }
+        },
+        "settings": {
+          "type": "array",
+          "description": "theme_mod controls.",
+          "items": { "$ref": "#/definitions/appearanceSetting" }
+        }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "embed": { "const": "options" } }, "required": ["embed"] },
+          "then": { "not": { "required": ["settings"] } },
+          "else": { "required": ["settings"] }
+        }
+      ]
+    },
+    "appearanceGroup": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+          "examples": ["light", "dark"]
+        },
+        "title": { "type": "string" },
+        "description": { "type": "string" }
+      }
+    },
+    "appearanceSetting": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "type", "label"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-zA-Z0-9]*$",
+          "description": "theme_mod key (camelCase). Path: `globalSetting.theme.mods[themeId][id]`.",
+          "examples": ["displayTitle", "primaryColor", "siteLogo"]
+        },
+        "type": {
+          "type": "string",
+          "enum": ["color", "text", "image", "textarea", "checkbox", "select", "noticeList"]
+        },
+        "label": { "type": "string" },
+        "description": { "type": "string" },
+        "default": { "type": "string" },
+        "group": {
+          "type": "string",
+          "description": "Parent group id within the section (`appearance.sections[].groups[].id`)."
+        },
+        "choices": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["value", "label"],
+            "properties": {
+              "value": { "type": "string" },
+              "label": { "type": "string" }
+            },
+            "additionalProperties": false
+          }
+        }
+      }
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,41 @@
+{
+  "compilerOptions": {
+    "incremental": true,
+    "target": "ES6",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": false,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "baseUrl": ".",
+    "paths": {
+      "@/components/*": ["components/*"],
+      "@/lib/*": ["lib/*"]
+    },
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "strictNullChecks": false
+  },
+  "include": [
+    "**/*.js",
+    "**/*.json",
+    "**/*.mjs",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/dev/types/**/*.ts",
+    ".next/types/**/*.ts",
+    "next-env.d.ts",
+    ".next-dev/types/**/*.ts"
+  ],
+  "exclude": ["node_modules"]
+}

package/vercel.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "framework": "nextjs",
+  "installCommand": "pnpm install --frozen-lockfile",
+  "buildCommand": "pnpm run build:mock",
+  "env": {
+    "REACTPRESS_MOCK_API": "1",
+    "REACTPRESS_API_URL": "https://reactpress-theme-starter.vercel.app/api",
+    "NEXT_PUBLIC_REACTPRESS_API_URL": "/api",
+    "CLIENT_SITE_URL": "https://reactpress-theme-starter.vercel.app"
+  }
+}