ReactPress Theme Starter

A lightweight, simple, and easy-to-use Next.js theme, powered by ReactPress.

Live Demo · Documentation · 简体中文

If this project helps you, a ⭐ on GitHub helps others discover it.

---

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:

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

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.

Deploy to Vercel (zero env vars)

One-click deploy uses vercel.json with mock data — no backend required.

---

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.

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 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
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.

Category	Score
Performance	95
Accessibility	100
Best Practices	100
SEO	100

Core Web Vitals (homepage audit on the live demo):

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

---

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. No manual .env wiring for a standard setup.

npm i -g @fecommunity/reactpress@3
reactpress init
reactpress dev

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 to .env if needed — default local API is http://localhost:3002/api.
4. In the theme directory, run:

pnpm dev

Open http://localhost:3001 — the theme loads live content from your ReactPress API.

Remote API during development:

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:

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. This is the same mode used by the Vercel demo.

---

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.

---

Configuration

When using pnpm dev against a live API, copy .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 uses build:mock with mock data. See Deploy to Vercel above for the one-click button with live demo preview.

The live demo 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

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. Appearance (colors, logo, navigation) is configured in the ReactPress admin console.

---

FAQ

Do I need ReactPress to preview the theme?

No. Run pnpm dev:mock for a full UI preview with sample data. Install ReactPress CLI when you want a real CMS, admin panel, and API.

How is this different from WordPress or Ghost themes?

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 for the full stack.

Can I use my own Next.js components or fork the theme?

Yes. MIT licensed. Customize components under app/ and components/, or declare routes in theme.json. Pull requests welcome — see Contributing.

Where do I report bugs in the CMS or CLI?

Theme issues → this repo. Core ReactPress (API, admin, CLI) → fecommunity/reactpress.

---

Community

Channel	Link
Q&A & showcase	GitHub Discussions
Bug reports	Issues
ReactPress core	github.com/fecommunity/reactpress
Documentation	reactpress.surge.sh

---

Contributing

Contributing	Setup, conventions, pull requests
Contributing (中文)	中文贡献指南
Code of Conduct	Community standards
Security	Report vulnerabilities

---

Links

ReactPress docs	reactpress.surge.sh
ReactPress source	github.com/fecommunity/reactpress
Toolkit	@fecommunity/reactpress-toolkit
Theme schema	theme.manifest.schema.json

MIT License · © ReactPress / FECommunity