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

package/.env.example

@@ -1,12 +1,20 @@
 # 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
+# Browser CSR requests — use same-origin /api proxy (recommended for remote API)
+NEXT_PUBLIC_REACTPRESS_API_URL=/api
 
 # Public site URL (SEO / sitemap / Open Graph)
 CLIENT_SITE_URL=http://localhost:3001
 
+# Embed ReactPress Admin at /admin/ (local dev: auto-starts static server on :3000)
+# REACTPRESS_EMBED_ADMIN=1
+# REACTPRESS_ADMIN_STATIC_ORIGIN=http://127.0.0.1:3000
+# NEXT_PUBLIC_REACTPRESS_ADMIN_URL=http://localhost:3001/admin
+#
+# Vercel / serverless: bundle admin static assets into public/admin at build time
+# REACTPRESS_BUNDLE_ADMIN=1
+
 # Subpath deployment (optional)
 # BASE_PATH=/blog
 
@@ -15,8 +23,15 @@ CLIENT_SITE_URL=http://localhost:3001
 
 # ── Remote API during dev (equivalent to --remote-origin) ───────────────────
 # REACTPRESS_DEV_REMOTE_ORIGIN=https://api.yoursite.com
+# REACTPRESS_DEV_CLIENT_API_ORIGIN=https://api.yoursite.com
 
 # ── Production (Vercel / self-hosted) ───────────────────────────────────────
+# Same nginx gateway (site + API same origin):
 # REACTPRESS_API_URL=https://api.yoursite.com/api
 # NEXT_PUBLIC_REACTPRESS_API_URL=/api
 # CLIENT_SITE_URL=https://www.yoursite.com
+#
+# Cross-subdomain (e.g. demo.yoursite.com + api.yoursite.com):
+# REACTPRESS_API_URL=https://api.yoursite.com/api
+# NEXT_PUBLIC_REACTPRESS_API_URL=https://api.yoursite.com/api
+# CLIENT_SITE_URL=https://demo.yoursite.com

package/README.md

@@ -1,13 +1,13 @@
+# ReactPress Theme Starter
+
 <div align="center">
 
-<a href="https://reactpress.surge.sh/">
+<a href="https://reactpress.cc/">
   <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">
@@ -16,7 +16,7 @@ A lightweight, simple, and easy-to-use Next.js theme, powered by [ReactPress](ht
 
 <br />
 
-[Live Demo](https://reactpress-theme-starter.vercel.app) · [Documentation](https://reactpress.surge.sh/) · [简体中文](./README_zh.md)
+[Live Demo](https://reactpress-theme-starter.vercel.app) · [Documentation](https://reactpress.cc/) · [简体中文](./README_zh.md)
 
 <br />
 
@@ -90,6 +90,41 @@ ReactPress API  ──REST──▶  Theme Starter (Next.js)  ──▶  Public
 | 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       |
+| Lighthouse performance    | ✅ **95** out of the box (see below)                                     | ❌ Varies widely              |
+
+### Performance
+
+Built on Next.js 15 App Router with server rendering, static generation, and minimal client JavaScript — the theme delivers strong Core Web Vitals without extra tuning.
+
+<div align="center">
+
+<img src="./public/lighthouse.png" alt="Lighthouse audit: Performance 95, Accessibility 100, Best Practices 100, SEO 100" width="720" />
+
+</div>
+
+| Category       | Score   |
+| :------------- | :------ |
+| Performance    | **95**  |
+| Accessibility  | **100** |
+| Best Practices | **100** |
+| SEO            | **100** |
+
+**Core Web Vitals** (homepage audit on the [live demo](https://reactpress-theme-starter.vercel.app)):
+
+| Metric                         | Result     |
+| :----------------------------- | :--------- |
+| First Contentful Paint (FCP)   | **0.4 s**  |
+| Largest Contentful Paint (LCP) | **1.0 s**  |
+| Total Blocking Time (TBT)      | **150 ms** |
+| Cumulative Layout Shift (CLS)  | **0**      |
+| Speed Index                    | **1.1 s**  |
+
+**Why it feels fast:**
+
+- **SSR + SSG** — pages render on the server; static routes are pre-built at deploy time
+- **Zero layout shift** — stable typography and layout from first paint
+- **Light client bundle** — content-first UI without heavy runtime overhead
+- **SEO-ready** — metadata, Open Graph, RSS, and sitemap included
 
 ---
 
@@ -99,7 +134,7 @@ ReactPress API  ──REST──▶  Theme Starter (Next.js)  ──▶  Public
 
 ### 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.
+The fastest way to run a full stack (visitor site, admin console, and API) is the [ReactPress CLI](https://reactpress.cc/). No manual `.env` wiring for a standard setup.
 
 ```bash
 npm i -g @fecommunity/reactpress@3
@@ -219,14 +254,14 @@ Route templates are declared in [`theme.json`](./theme.json). Appearance (colors
 <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.
+No. Run `pnpm dev:mock` for a full UI preview with sample data. Install [ReactPress CLI](https://reactpress.cc/) 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.
+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.cc/) for the full stack.
 
 </details>
 
@@ -253,7 +288,7 @@ Theme issues → [this repo](https://github.com/fecommunity/reactpress-theme-sta
 | 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/)                                       |
+| Documentation   | [reactpress.cc](https://reactpress.cc/)                                                   |
 
 ---
 
@@ -272,7 +307,7 @@ Theme issues → [this repo](https://github.com/fecommunity/reactpress-theme-sta
 
 |                   |                                                                                                  |
 | :---------------- | :----------------------------------------------------------------------------------------------- |
-| ReactPress docs   | [reactpress.surge.sh](https://reactpress.surge.sh/)                                              |
+| ReactPress docs   | [reactpress.cc](https://reactpress.cc/)                                                          |
 | 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)                                       |

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

@@ -27,10 +27,10 @@ async function handleRequest(request: Request, context: RouteContext): Promise<R
 
   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 body = await readJsonBody(request)
     const mockResponse = matchMockRoute(request.method, path, { keyword, body })
     response = mockResponse ?? Response.json({ success: true, data: null })
   } else {

package/app/layout.tsx

@@ -7,7 +7,11 @@ import ConditionalSiteFooter from '@/components/layout/ConditionalSiteFooter'
 import PageContainer from '@/components/layout/PageContainer'
 import { loadAppBootstrap } from '@/lib/reactpress/bootstrap'
 import { buildThemeStarterAppearanceCss } from '@/lib/reactpress/appearance'
-import { getApiPreconnectOrigin } from '@/lib/reactpress/env'
+import {
+  buildClientApiRuntimeScript,
+  getApiPreconnectOrigin,
+  getServerResolvedPublicApiUrl,
+} from '@/lib/reactpress/env'
 import { ReactPressAppProviders } from '@/lib/reactpress/providers'
 import { buildRootMetadata } from '@/lib/reactpress/siteMetadata'
 import { DEFAULT_DESCRIPTION } from '@/lib/reactpress/seoMetadata'
@@ -31,6 +35,7 @@ export default async function RootLayout({ children }: { children: React.ReactNo
   const bootstrap = await loadAppBootstrap('/')
   const appearanceCss = buildThemeStarterAppearanceCss(bootstrap.themeMods)
   const basePath = process.env.BASE_PATH || ''
+  const clientApiBase = getServerResolvedPublicApiUrl()
   const apiPreconnect = getApiPreconnectOrigin()
   const rootMetadata = await buildRootMetadata()
   const siteDescription =
@@ -42,6 +47,11 @@ export default async function RootLayout({ children }: { children: React.ReactNo
     <html lang={bootstrap.initialLocale} suppressHydrationWarning>
       <head>
         <meta name="description" content={siteDescription} />
+        <script
+          dangerouslySetInnerHTML={{
+            __html: buildClientApiRuntimeScript(clientApiBase),
+          }}
+        />
         <script
           dangerouslySetInnerHTML={{
             __html: `document.documentElement.setAttribute('data-rp-loading','');`,

package/components/layout/UserAuth.tsx

@@ -2,7 +2,6 @@
 
 import Link from '@/components/shared/Link'
 import ThemeImage from '@/components/shared/ThemeImage'
-import { getAdminBaseUrl } from '@/lib/reactpress/env'
 import { useLocale } from '@fecommunity/reactpress-toolkit/ui'
 import { resolveImageUrl, useSiteUser } from '@fecommunity/reactpress-toolkit/theme'
 import { usePathname } from 'next/navigation'
@@ -10,9 +9,24 @@ import { useMemo, useState } from 'react'
 
 function resolveAdminHref(): string {
   const configured = process.env.NEXT_PUBLIC_REACTPRESS_ADMIN_URL?.trim()
-  if (configured) return configured.endsWith('/') ? configured : `${configured}/`
-  if (typeof window !== 'undefined') return `${window.location.origin}/admin/`
-  return `${getAdminBaseUrl()}/`
+  if (!configured) return '/admin/'
+  if (configured.startsWith('/')) {
+    return configured.endsWith('/') ? configured : `${configured}/`
+  }
+  if (typeof window !== 'undefined') {
+    try {
+      const parsed = new URL(configured)
+      if (
+        parsed.pathname.replace(/\/$/, '') === '/admin' &&
+        parsed.origin === window.location.origin
+      ) {
+        return '/admin/'
+      }
+    } catch {
+      // fall through to configured absolute URL
+    }
+  }
+  return configured.endsWith('/') ? configured : `${configured}/`
 }
 
 function resolveThemeAuthHref(path: 'login' | 'register', from: string): string {

package/lib/mock-api/proxy.ts

@@ -1,5 +1,14 @@
 import { resolveUpstreamApiBase } from './config'
 
+/** Strip hop-by-hop / encoding headers — fetch may decompress the body. */
+function sanitizeProxyResponseHeaders(headers: Headers): Headers {
+  const next = new Headers(headers)
+  for (const name of ['content-encoding', 'content-length', 'transfer-encoding', 'connection']) {
+    next.delete(name)
+  }
+  return next
+}
+
 export async function proxyToUpstreamApi(request: Request, segments: string[]): Promise<Response> {
   const base = resolveUpstreamApiBase()
   const pathname = segments.map((segment) => decodeURIComponent(segment)).join('/')
@@ -21,8 +30,12 @@ export async function proxyToUpstreamApi(request: Request, segments: string[]):
     redirect: 'manual',
   })
 
-  return new Response(upstream.body, {
+  // Buffer body — piping upstream.body through a new Response is unreliable on Vercel.
+  const upstreamBody = request.method === 'HEAD' ? null : Buffer.from(await upstream.arrayBuffer())
+
+  return new Response(upstreamBody, {
     status: upstream.status,
-    headers: upstream.headers,
+    statusText: upstream.statusText,
+    headers: sanitizeProxyResponseHeaders(upstream.headers),
   })
 }

package/lib/providers/client.ts

@@ -1,6 +1,7 @@
-import { createThemeHttpStack } from '@fecommunity/reactpress-toolkit/theme'
+import { resolveClientApiBaseUrl } from '@/lib/reactpress/env'
 import { normalizeList, normalizePaginated } from '@/lib/reactpress/normalizeApiResponse'
 import { materializeProvider } from '@/lib/providers/materializeProvider'
+import { createThemeHttpStack } from '@fecommunity/reactpress-toolkit/theme'
 
 /** API messages already shown in UI (login form, etc.) — skip dev console noise. */
 function isExpectedClientError(message: string, status?: number): boolean {
@@ -11,6 +12,7 @@ function isExpectedClientError(message: string, status?: number): boolean {
 }
 
 const stack = createThemeHttpStack({
+  baseURL: resolveClientApiBaseUrl(),
   onError: (msg: string, status?: number) => {
     if (process.env.NODE_ENV !== 'development') return
     if (isExpectedClientError(msg, status)) return
@@ -18,6 +20,12 @@ const stack = createThemeHttpStack({
   },
 })
 
+// Module init may run before layout runtime script; refresh baseURL on every request.
+stack.httpProvider.interceptors.request.use((config) => {
+  config.baseURL = resolveClientApiBaseUrl()
+  return config
+})
+
 export const { CommentProvider, UserProvider, SettingProvider } = stack
 
 export const ArticleProvider = {

package/lib/reactpress/env.ts

@@ -1,5 +1,10 @@
 /** App/runtime helpers — values are injected via next.config `env` when possible. */
-import { DEFAULT_LOCAL_ADMIN, DEFAULT_LOCAL_SITE } from '../../scripts/resolve-api-env.mjs'
+import {
+  DEFAULT_LOCAL_ADMIN,
+  DEFAULT_LOCAL_API,
+  DEFAULT_LOCAL_SITE,
+  resolveThemeApiEnv,
+} from '../../scripts/resolve-api-env.mjs'
 
 export {
   DEFAULT_LOCAL_ADMIN,
@@ -7,6 +12,15 @@ export {
   DEFAULT_LOCAL_SITE,
 } from '../../scripts/resolve-api-env.mjs'
 
+declare global {
+  interface Window {
+    /** Injected in root layout at SSR time — avoids stale build-time NEXT_PUBLIC_* in the browser. */
+    __REACTPRESS_CLIENT_API__?: string
+  }
+}
+
+export const RUNTIME_CLIENT_API_KEY = '__REACTPRESS_CLIENT_API__'
+
 export function getClientSiteUrl(): string {
   return (process.env.CLIENT_SITE_URL || DEFAULT_LOCAL_SITE).replace(/\/$/, '')
 }
@@ -17,11 +31,44 @@ export function getAdminBaseUrl(): string {
   return DEFAULT_LOCAL_ADMIN
 }
 
+/** Server-side resolved browser API base (honours runtime env on each request). */
+export function getServerResolvedPublicApiUrl(): string {
+  return resolveThemeApiEnv().NEXT_PUBLIC_REACTPRESS_API_URL.replace(/\/$/, '')
+}
+
+/** Inline script for `<head>` — must run before client bundles evaluate. */
+export function buildClientApiRuntimeScript(apiBase: string): string {
+  return `window.${RUNTIME_CLIENT_API_KEY}=${JSON.stringify(apiBase.replace(/\/$/, ''))};`
+}
+
+function readRuntimeClientApiBaseUrl(): string | undefined {
+  if (typeof window === 'undefined') return undefined
+  const value = window[RUNTIME_CLIENT_API_KEY]?.trim()
+  return value ? value.replace(/\/$/, '') : undefined
+}
+
+/** Axios/fetch base URL for browser CSR — never fall back to localhost:3002 in the browser. */
+export function resolveClientApiBaseUrl(): string {
+  if (typeof window === 'undefined') {
+    return (
+      process.env.REACTPRESS_API_URL?.trim() ||
+      process.env.NEXT_PUBLIC_REACTPRESS_API_URL?.trim() ||
+      DEFAULT_LOCAL_API
+    ).replace(/\/$/, '')
+  }
+
+  const runtime = readRuntimeClientApiBaseUrl()
+  if (runtime) return runtime
+
+  const publicUrl = process.env.NEXT_PUBLIC_REACTPRESS_API_URL?.trim()
+  if (publicUrl) return publicUrl.replace(/\/$/, '')
+
+  return '/api'
+}
+
 export function getApiPreconnectOrigin(): string | null {
-  const api =
-    process.env.REACTPRESS_API_URL?.trim() ||
-    process.env.SERVER_API_URL?.trim() ||
-    process.env.NEXT_PUBLIC_REACTPRESS_API_URL?.trim()
+  const apiEnv = resolveThemeApiEnv()
+  const api = apiEnv.NEXT_PUBLIC_REACTPRESS_API_URL.trim()
 
   if (!api || api.startsWith('/')) return null
 

package/lib/reactpress/fetchSetting.ts

@@ -1,7 +1,9 @@
 /** Same-origin visitor setting fetch — avoids toolkit axios onError console noise. */
+import { resolveClientApiBaseUrl } from '@/lib/reactpress/env'
+
 export async function fetchVisitorSetting(): Promise<Record<string, unknown> | null> {
-  const apiBase = (process.env.NEXT_PUBLIC_REACTPRESS_API_URL || '/api').replace(/\/$/, '')
-  const url = apiBase.startsWith('http') ? `${apiBase}/setting/get` : `${apiBase}/setting/get`
+  const apiBase = resolveClientApiBaseUrl()
+  const url = `${apiBase}/setting/get`
 
   try {
     const response = await fetch(url, {

package/lib/reactpress/layout-shell.tsx

@@ -1,6 +1,6 @@
 'use client'
 
-import { useReportPageView } from '@fecommunity/reactpress-toolkit/ui'
+import { useReportPageView } from '@/lib/reactpress/useReportPageView'
 import { type ReactNode } from 'react'
 
 import BackToTop from '@/components/layout/BackToTop'

package/lib/reactpress/useReportPageView.ts

@@ -0,0 +1,36 @@
+'use client'
+
+import { resolveClientApiBaseUrl } from '@/lib/reactpress/env'
+import { useEffect, useRef } from 'react'
+
+interface UseReportPageViewOptions {
+  url?: string
+  skipLocalhost?: boolean
+  enabled?: boolean
+}
+
+/** Report page view via resolved public API base (runtime-injected in production). */
+export function useReportPageView(options: UseReportPageViewOptions = {}) {
+  const { url, skipLocalhost = true, enabled = true } = options
+  const lastUrl = useRef<string | undefined>(undefined)
+
+  useEffect(() => {
+    if (!enabled || typeof window === 'undefined') return undefined
+
+    const target = url ?? window.location.href
+    if (skipLocalhost && /localhost|127\.0\.0\.1/.test(target)) return undefined
+    if (lastUrl.current === target) return undefined
+    lastUrl.current = target
+
+    const apiBase = resolveClientApiBaseUrl()
+    fetch(`${apiBase}/view`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ url: target }),
+    }).catch((error) => {
+      console.error('[reactpress] report page view failed', error)
+    })
+
+    return undefined
+  }, [enabled, skipLocalhost, url])
+}

package/next.config.js

@@ -6,6 +6,12 @@ const {
   resolveClientSiteUrl,
   isLocalhostUrl,
 } = require('./scripts/resolve-api-env.mjs')
+const {
+  isEmbedAdminEnabled,
+  isBundledAdminEnabled,
+  createLocalAdminRewrites,
+  createBundledAdminFallbackRewrites,
+} = require('./scripts/embed-admin.cjs')
 
 // App Router (Next 15): do not use createReactPressNextConfig's react webpack alias —
 // it conflicts with Next's compiled React and causes SSR "useContext" null errors.
@@ -73,7 +79,16 @@ module.exports = {
     return webpackConfig
   },
   async rewrites() {
-    return [{ source: '/uploads/:path*', destination: `${uploadRewriteOrigin}/uploads/:path*` }]
+    const beforeFiles = [
+      { source: '/uploads/:path*', destination: `${uploadRewriteOrigin}/uploads/:path*` },
+    ]
+    if (isEmbedAdminEnabled()) {
+      beforeFiles.push(...createLocalAdminRewrites())
+    }
+
+    const fallback = isBundledAdminEnabled() ? createBundledAdminFallbackRewrites() : []
+
+    return { beforeFiles, fallback }
   },
   async redirects() {
     return [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fecommunity/reactpress-theme-starter",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.1",
   "description": "ReactPress 博客主题 Starter：Tailwind CSS + Next.js App Router，对接 toolkit 动态内容",
   "license": "MIT",
   "keywords": [
@@ -47,7 +47,9 @@
   "scripts": {
     "dev": "node scripts/dev.mjs",
     "dev:mock": "cross-env REACTPRESS_MOCK_API=1 node scripts/dev.mjs",
+    "dev:admin": "node node_modules/@fecommunity/reactpress-web/bin/reactpress-web.js start --port 3000",
     "clean": "rm -rf .next .next-dev",
+    "prebuild": "node scripts/copy-admin-dist.mjs",
     "build": "cross-env INIT_CWD=$PWD next build",
     "build:mock": "node scripts/build-mock.mjs",
     "build:ci": "pnpm clean && cross-env INIT_CWD=$PWD next build",
@@ -63,6 +65,7 @@
   },
   "dependencies": {
     "@fecommunity/reactpress-toolkit": "^3.1.0",
+    "@fecommunity/reactpress-web": "^3.7.0",
     "@tailwindcss/forms": "^0.5.11",
     "@tailwindcss/postcss": "^4.1.18",
     "@tailwindcss/typography": "^0.5.19",

package/scripts/copy-admin-dist.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * Copy @fecommunity/reactpress-web/dist → public/admin for Vercel / serverless deploys.
+ * Admin SPA expects base /admin/ and same-origin /api (proxied by app/api/[[...path]]).
+ */
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import { createRequire } from 'node:module'
+import { fileURLToPath } from 'node:url'
+
+const require = createRequire(import.meta.url)
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const projectRoot = path.resolve(__dirname, '..')
+const { isBundledAdminEnabled } = require('./embed-admin.cjs')
+
+function resolveAdminDistDir() {
+  const dist = path.join(projectRoot, 'node_modules', '@fecommunity/reactpress-web', 'dist')
+  return fs.realpathSync(dist)
+}
+
+async function copyEntry(src, dest) {
+  const stat = await fsp.stat(src)
+  if (stat.isDirectory()) {
+    await fsp.mkdir(dest, { recursive: true })
+    for (const name of await fsp.readdir(src)) {
+      await copyEntry(path.join(src, name), path.join(dest, name))
+    }
+    return
+  }
+  await fsp.copyFile(src, dest)
+}
+
+async function main() {
+  if (!isBundledAdminEnabled()) {
+    console.log('[copy-admin] skipped (REACTPRESS_BUNDLE_ADMIN=0 or not a Vercel production build)')
+    return
+  }
+
+  const src = resolveAdminDistDir()
+  const indexHtml = path.join(src, 'index.html')
+  if (!fs.existsSync(indexHtml)) {
+    throw new Error(
+      `Admin dist not found at ${src}. Ensure @fecommunity/reactpress-web is installed.`
+    )
+  }
+
+  const dest = path.join(projectRoot, 'public/admin')
+  await fsp.rm(dest, { recursive: true, force: true })
+  await copyEntry(src, dest)
+
+  console.log(`[copy-admin] copied ${src} → public/admin`)
+}
+
+main().catch((error) => {
+  console.error('[copy-admin]', error.message || error)
+  process.exit(1)
+})

package/scripts/dev.mjs

@@ -17,11 +17,16 @@ import {
   resolveDevApiOrigins,
   resolveRemoteThemeApiBase,
 } from './remote-dev.mjs'
+import { createRequire } from 'node:module'
 import {
   DEFAULT_LOCAL_API,
   DEFAULT_THEME_DEV_PORT,
   resolveThemeApiEnv as resolveProjectApiEnv,
 } from './resolve-api-env.mjs'
+import { spawnEmbeddedAdmin } from './spawn-admin.mjs'
+
+const require = createRequire(import.meta.url)
+const { isEmbedAdminEnabled, resolveAdminStaticOrigin } = require('./embed-admin.cjs')
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const projectRoot = path.resolve(__dirname, '..')
@@ -176,8 +181,9 @@ function buildChildEnv(apiEnv, port) {
   }
 }
 
-function printBanner(apiEnv, port) {
+function printBanner(apiEnv, port, childEnv) {
   const mockEnabled = process.env.REACTPRESS_MOCK_API === '1'
+  const embedAdmin = isEmbedAdminEnabled(childEnv)
   console.log('')
   console.log('  ReactPress Theme Dev')
   console.log(`  Local:  http://localhost:${port}`)
@@ -188,18 +194,42 @@ function printBanner(apiEnv, port) {
   } else {
     console.log(`  API:    ${apiEnv.serverApiUrl} (local)`)
   }
+  if (embedAdmin) {
+    console.log(
+      `  Admin:  http://localhost:${port}/admin/  (static → ${resolveAdminStaticOrigin(childEnv)})`
+    )
+  }
   console.log('')
 }
 
+function shutdownChildren(children, signal = 'SIGTERM') {
+  for (const child of children) {
+    if (child && !child.killed) {
+      child.kill(signal)
+    }
+  }
+}
+
 function main() {
   const cli = parseArgs(process.argv.slice(2))
   const apiEnv = resolveThemeApiEnv(cli)
   const childEnv = buildChildEnv(apiEnv, cli.port)
+  const children = []
 
-  printBanner(apiEnv, cli.port)
+  if (isEmbedAdminEnabled(childEnv)) {
+    childEnv.REACTPRESS_EMBED_ADMIN = '1'
+    try {
+      children.push(spawnEmbeddedAdmin(childEnv))
+    } catch (error) {
+      console.error(`[dev] Failed to start embedded admin: ${error.message}`)
+      process.exit(1)
+    }
+  }
+
+  printBanner(apiEnv, cli.port, childEnv)
 
   const nextBin = path.join(projectRoot, 'node_modules', 'next', 'dist', 'bin', 'next')
-  const child = spawn(
+  const nextChild = spawn(
     process.execPath,
     [nextBin, 'dev', '-p', String(cli.port), ...cli.passthrough],
     {
@@ -208,8 +238,17 @@ function main() {
       stdio: 'inherit',
     }
   )
+  children.push(nextChild)
+
+  const onSignal = (signal) => {
+    shutdownChildren(children, signal)
+    process.exit(0)
+  }
+  process.on('SIGINT', onSignal)
+  process.on('SIGTERM', onSignal)
 
-  child.on('exit', (code, signal) => {
+  nextChild.on('exit', (code, signal) => {
+    shutdownChildren(children.filter((c) => c !== nextChild))
     if (signal) {
       process.kill(process.pid, signal)
       return

package/scripts/embed-admin.cjs

@@ -0,0 +1,67 @@
+/** Shared helpers for embedding @fecommunity/reactpress-web (CJS — next.config.js). */
+
+const DEFAULT_ADMIN_STATIC_PORT = 3000
+
+function trimUrl(value) {
+  if (typeof value !== 'string') return ''
+  return value.trim().replace(/\/$/, '')
+}
+
+function isEmbedAdminEnabled(processEnv = process.env) {
+  const flag = processEnv.REACTPRESS_EMBED_ADMIN
+  if (flag === '0' || flag === 'false') return false
+  if (flag === '1' || flag === 'true') return true
+  // Default on for local theme dev when not on Vercel.
+  return processEnv.VERCEL !== '1' && processEnv.REACTPRESS_MOCK_API !== '1'
+}
+
+function resolveAdminStaticOrigin(processEnv = process.env) {
+  const explicit = trimUrl(processEnv.REACTPRESS_ADMIN_STATIC_ORIGIN)
+  if (explicit) return explicit
+  const port = Number(processEnv.WEB_ADMIN_PORT || DEFAULT_ADMIN_STATIC_PORT)
+  return `http://127.0.0.1:${port}`
+}
+
+/** Next.js rewrites — browser hits /admin on the theme origin, upstream serves static SPA. */
+function createLocalAdminRewrites(processEnv = process.env) {
+  const adminOrigin = resolveAdminStaticOrigin(processEnv)
+  return [
+    { source: '/admin', destination: `${adminOrigin}/admin/` },
+    { source: '/admin/:path*', destination: `${adminOrigin}/admin/:path*` },
+  ]
+}
+
+function resolveEmbeddedAdminPublicUrl(processEnv = process.env, clientSiteUrl) {
+  const site = trimUrl(clientSiteUrl)
+  if (!site) return null
+  return `${site}/admin`
+}
+
+/**
+ * Vercel / serverless: copy @fecommunity/reactpress-web/dist into public/admin at build time.
+ * REACTPRESS_EMBED_ADMIN=0 only disables the Node custom-server embed, not bundled static admin.
+ */
+function isBundledAdminEnabled(processEnv = process.env) {
+  const flag = processEnv.REACTPRESS_BUNDLE_ADMIN
+  if (flag === '0' || flag === 'false') return false
+  if (flag === '1' || flag === 'true') return true
+  return processEnv.VERCEL === '1' && processEnv.REACTPRESS_MOCK_API !== '1'
+}
+
+/** SPA fallback — use in Next.js rewrites().fallback after public/admin static files. */
+function createBundledAdminFallbackRewrites() {
+  return [
+    { source: '/admin', destination: '/admin/index.html' },
+    { source: '/admin/:path*', destination: '/admin/index.html' },
+  ]
+}
+
+module.exports = {
+  DEFAULT_ADMIN_STATIC_PORT,
+  isEmbedAdminEnabled,
+  isBundledAdminEnabled,
+  resolveAdminStaticOrigin,
+  createLocalAdminRewrites,
+  createBundledAdminFallbackRewrites,
+  resolveEmbeddedAdminPublicUrl,
+}

package/scripts/ensure-env.mjs

@@ -18,12 +18,14 @@ const MERGE_KEYS = [
   'BASE_PATH',
   'REACTPRESS_MOCK_API',
   'NEXT_PUBLIC_REACTPRESS_ADMIN_URL',
+  'REACTPRESS_EMBED_ADMIN',
+  'REACTPRESS_ADMIN_STATIC_ORIGIN',
   'REACTPRESS_DEV_REMOTE_ORIGIN',
 ]
 
 const FALLBACK_ENV = `# Auto-generated for CI / Vercel mock build
 REACTPRESS_API_URL=http://localhost:3002/api
-NEXT_PUBLIC_REACTPRESS_API_URL=http://localhost:3002/api
+NEXT_PUBLIC_REACTPRESS_API_URL=/api
 CLIENT_SITE_URL=http://localhost:3001
 `
 

package/scripts/resolve-api-env.mjs

@@ -1,9 +1,23 @@
+function isEmbedAdminEnabled(processEnv = process.env) {
+  const flag = processEnv.REACTPRESS_EMBED_ADMIN
+  if (flag === '0' || flag === 'false') return false
+  if (flag === '1' || flag === 'true') return true
+  return processEnv.VERCEL !== '1' && processEnv.REACTPRESS_MOCK_API !== '1'
+}
+
+function isBundledAdminEnabled(processEnv = process.env) {
+  const flag = processEnv.REACTPRESS_BUNDLE_ADMIN
+  if (flag === '0' || flag === 'false') return false
+  if (flag === '1' || flag === 'true') return true
+  return processEnv.VERCEL === '1' && processEnv.REACTPRESS_MOCK_API !== '1'
+}
+
 /**
  * Single source of truth for ReactPress theme URL resolution (build, dev, Vercel).
  */
 export const DEFAULT_LOCAL_API = 'http://localhost:3002/api'
 export const DEFAULT_LOCAL_SITE = 'http://localhost:3001'
-export const DEFAULT_LOCAL_ADMIN = 'http://localhost:3000'
+export const DEFAULT_LOCAL_ADMIN = 'http://localhost:3000/admin'
 export const DEFAULT_THEME_DEV_PORT = 3001
 export const DEFAULT_VERCEL_DEMO_SITE = 'https://reactpress-theme-starter.vercel.app'
 
@@ -30,6 +44,35 @@ function apiOriginFromBase(serverApi) {
   return serverApi.replace(/\/api\/?$/, '')
 }
 
+function parseHttpOrigin(value) {
+  const normalized = value.startsWith('http') ? value : `https://${value}`
+  return new URL(normalized).origin
+}
+
+/** True when public site and API share the same origin (nginx /api gateway). */
+export function isSameSiteAndApiOrigin(serverApi, processEnv) {
+  if (isLocalhostUrl(serverApi)) return true
+
+  const apiOriginRaw = apiOriginFromBase(serverApi)
+  const siteUrl = resolveClientSiteUrl(processEnv)
+
+  try {
+    return parseHttpOrigin(siteUrl) === parseHttpOrigin(apiOriginRaw)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Default browser API URL when NEXT_PUBLIC_REACTPRESS_API_URL is unset.
+ * Same-origin (nginx /api gateway) → `/api`; cross-subdomain → direct API URL.
+ */
+function resolvePublicApiDefault(serverApi, processEnv) {
+  if (isLocalhostUrl(serverApi)) return serverApi
+  if (isSameSiteAndApiOrigin(serverApi, processEnv)) return '/api'
+  return serverApi
+}
+
 /**
  * @param {NodeJS.ProcessEnv} [processEnv]
  */
@@ -71,11 +114,14 @@ export function resolveThemeApiEnv(processEnv = process.env) {
     // Browser must hit same-origin mock routes; ignore .env localhost:3002.
     publicApi = '/api'
   } else if (!publicApi) {
-    if (processEnv.NODE_ENV === 'production' && !isLocalhostUrl(serverApi)) {
-      publicApi = '/api'
-    } else {
-      publicApi = serverApi
-    }
+    publicApi = resolvePublicApiDefault(serverApi, processEnv)
+  } else if (
+    publicApi === '/api' &&
+    !isLocalhostUrl(serverApi) &&
+    !isSameSiteAndApiOrigin(serverApi, processEnv)
+  ) {
+    // `.env.example` defaults to `/api`; cross-subdomain deploys must hit the API host directly.
+    publicApi = serverApi
   }
 
   const nginxEntry = trimUrl(processEnv.REACTPRESS_NGINX_ENTRY_URL || processEnv.NGINX_ENTRY_URL)
@@ -83,7 +129,10 @@ export function resolveThemeApiEnv(processEnv = process.env) {
     trimUrl(processEnv.NEXT_PUBLIC_REACTPRESS_ADMIN_URL) ||
     (nginxEntry ? `${nginxEntry}/admin` : DEFAULT_LOCAL_ADMIN)
 
-  if (processEnv.VERCEL === '1' && isLocalhostUrl(adminUrl) && !isLocalhostUrl(serverApi)) {
+  if (isEmbedAdminEnabled(processEnv) || isBundledAdminEnabled(processEnv)) {
+    // Same-origin rewrite/bundle — relative path keeps port and host in sync with the theme.
+    adminUrl = '/admin'
+  } else if (processEnv.VERCEL === '1' && isLocalhostUrl(adminUrl) && !isLocalhostUrl(serverApi)) {
     adminUrl = `${apiOriginFromBase(serverApi)}/admin`
   }
 

package/scripts/spawn-admin.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+const { DEFAULT_ADMIN_STATIC_PORT, resolveAdminStaticOrigin } = require('./embed-admin.cjs')
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const projectRoot = path.resolve(__dirname, '..')
+
+function resolveAdminBin() {
+  const local = path.join(
+    projectRoot,
+    'node_modules',
+    '@fecommunity/reactpress-web',
+    'bin',
+    'reactpress-web.js'
+  )
+  if (fs.existsSync(local)) return local
+  throw new Error(
+    'Missing @fecommunity/reactpress-web. Run pnpm install (see package.json dependency).'
+  )
+}
+
+function adminPortFromOrigin(origin) {
+  try {
+    const url = new URL(origin)
+    if (url.port) return Number(url.port)
+    return url.protocol === 'https:' ? 443 : 80
+  } catch {
+    return DEFAULT_ADMIN_STATIC_PORT
+  }
+}
+
+/**
+ * Start embedded Admin static server. Returns child process (stdio inherited).
+ * @param {NodeJS.ProcessEnv} [processEnv]
+ */
+export function spawnEmbeddedAdmin(processEnv = process.env) {
+  const origin = resolveAdminStaticOrigin(processEnv)
+  const port = adminPortFromOrigin(origin)
+  const bin = resolveAdminBin()
+
+  return spawn(process.execPath, [bin, 'start', '--port', String(port), '--host', '127.0.0.1'], {
+    cwd: projectRoot,
+    env: processEnv,
+    stdio: 'inherit',
+  })
+}