I Spent 2 Years Building a React Publishing Solution — Here Is What I Learned

If you are a front-end engineer, you have probably lived this loop:

1. The team decides the marketing site or blog should run on React / Next.js.
2. You evaluate Strapi, Payload, Contentful, Sanity, Ghost, Tina — each is good at something, yet none ships a complete publishing platform you can install, write in, and publish from on day one.
3. You fork a Next.js blog starter, wire up a Headless backend, then build media handling, comment moderation, SEO metadata, preview mode, and deployment scripts yourself.
4. Three months later the blog is still not live — but you are maintaining five repositories.

I spent the last two years focused on that loop — not as a weekend side project, but as the primary effort behind ReactPress. We shipped 4.0 after the same pattern kept appearing in GitHub Issues, team channels, and release planning: backend marked done, blog still not live, editorial still blocked.

This article is the field guide I wished existed on day one — before committing to another Headless assembly. It covers why the five-repository week keeps happening, what we built to shorten it, and how the platform works when you run it locally.

If you have already chosen a Headless backend, started a Next.js theme, and are still wiring preview mode late in the sprint — the rest of this is written for you.

Meanwhile, WordPress still powers more than 40% of the web. PHP is mocked as legacy. Gutenberg is criticized. And yet WordPress remains the default choice for solo bloggers, content teams, agencies, and SMBs worldwide.

React has ruled the front end for ten years. Why does it still not have its own WordPress?

That is not a skills problem. It is a product category problem. Community feedback across ReactPress releases kept returning to the same question: "Can we manage content like WordPress, but deliver it with Next.js?" Existing answers either ship only an API, weld Admin and theme into one unmaintainable app, or require Docker + MySQL + six npm packages before you can write a single paragraph.

We built ReactPress 4.0 to close that gap — an open-source React publishing platform, not another Headless backend you must assemble yourself.

This article is structured as Why → What → How:

• WHY (§1–§3): the impossible triangle, WordPress lessons, React ecosystem gap — why assembly keeps failing
• WHAT (§4 + Executive summary): ReactPress 4.0 definition, boundaries, vs Headless CMS
• HOW (§5–§19): architecture, Admin, themes, plugins, deploy, reactpress init

See Why, What, How — the causal chain for the one-screen version.

What you will learn (structured path)

Lens	Sections	Question answered
WHY	§1–§3	Why React still has no WordPress — and why Headless assembly keeps failing
WHAT	Executive summary, §4	What ReactPress 4.0 is — and what it is not
HOW	§5–§19	How it works (architecture) and how to run it (CLI, Admin, theme, deploy)
Then	§16–§18, Conclusion	Who it fits, what's on the roadmap, where I landed after two years

Keywords: React CMS · Next.js CMS · WordPress alternative · React publishing platform · Open source CMS

---

Why, What, How — the causal chain

Read this section first if you want the full story before the deep dive. Everything else in this article expands one row below.

WHY — the cause chain

Step	What happened	Consequence
1. Demand	Teams want React / Next.js blogs with WordPress-style editing	Marketing cannot wait three months for engineering assembly
2. Market split	WordPress, SSG, and Headless CMS each solve part of the problem	Teams must pick two of three: editing, frontend freedom, out-of-the-box completeness — the impossible triangle (§1)
3. React gap	Next.js ships rendering, not publishing; Headless CMS ships APIs, not visitor sites	Every team rebuilds Admin glue, SEO, media, comments, deploy — five repos, no first post (§1.3)
4. WordPress lesson missed	WordPress won on one front door + core/theme/plugin boundaries, not PHP (§2)	React copied excellent parts but never shipped a platform category (§3)
5. Our response	Two years of Issues asking: "WordPress workflow, Next.js delivery — one install?"	We stopped optimizing Headless backends and built an integrated publishing platform

One-line WHY: React did not fail at front-end skill — it failed to ship the product category WordPress owns. That is why teams still maintain five repositories for a blog.

WHAT — the outcome

ReactPress 4.0 is an open-source React publishing platform — not another Headless CMS you must assemble.

You get out of the box	You do not get
CLI — reactpress init in ~60s	A drag-and-drop page builder for marketers
Admin at /admin/ — write, media, moderate	60,000 plugins on day one
NestJS REST API + Swagger + API keys	Mandatory Docker or SaaS lock-in
Next.js theme — SSR/ISR, SEO defaults	PHP compatibility layer
Hook plugins — SEO, summaries, image jobs	Ecommerce core
Electron desktop — offline SQLite writing	A finished mobile app

Boundary rule (one sentence):

Admin owns content · Theme owns presentation · Plugin owns logic · API owns data

Full definition and Headless comparison: §4.

HOW — the mechanism

How it works (architecture):

Author (Admin / Desktop) → Toolkit (typed API client) → NestJS API + Hooks → SQLite/MySQL
                                                              ↓
                                              Next.js theme SSR/ISR → visitors & crawlers

Four hard boundaries keep it maintainable: Admin never serves visitor pages; themes never touch the DB; server never imports front-end packages; all clients use Toolkit only. Details: §5–§11.

How you try it (60 seconds):

npm i -g @fecommunity/reactpress@beta
mkdir my-blog && cd my-blog
reactpress init

Surface	URL
Public site	http://localhost:3001
Admin	http://localhost:3001/admin/
API health	http://localhost:3002/api/health

How you operate it: SEO and Lighthouse defaults (§12), security model (§13), VPS/Docker deploy (§14), WordPress/Headless migration (§15). Step-by-step first article: §19.

Where to go from here

• Choosing a stack? Read WHY (§1–§3), then WHAT (§4), then the fit matrix (§16).
• Implementing this week? Jump to HOW (§5–§11), then §19 Getting started.
• Migrating from WordPress or Headless? §15 and the ReactPress vs WordPress guide.

---

Table of contents

Reading tip: Start with Why, What, How — the causal chain for the full story in one screen. Then skim WHY (§1–§3), WHAT (§4), or HOW (§5–§19) depending on your role.

1. Why, What, How — the causal chain
2. Executive summary
3. The industry problem (WHY)
4. Why WordPress succeeded (WHY)
5. The React ecosystem gap (WHY)
6. ReactPress philosophy (WHAT)
7. System architecture (HOW)
8. See it in action (HOW)
9. Admin: the writing surface (HOW)
10. Theme system (HOW)
11. Plugin system (HOW)
12. Desktop client (HOW)
13. Headless API (HOW)
14. SEO and performance (HOW)
15. Security model (HOW)
16. Deployment patterns (HOW)
17. Migration paths (HOW)
18. Who should use ReactPress
19. Roadmap
20. FAQ
21. Getting started
22. Conclusion

---

Executive summary

Question	Short answer
What is ReactPress?	A self-hosted React publishing platform: NestJS API + Vite Admin + Next.js theme + Hook plugins + CLI + Electron desktop.
Is it a Headless CMS?	It includes Headless REST, but delivers far more — visitor site, Admin, and extensions out of the box.
WordPress alternative?	Yes, for teams that want WordPress-style workflows with a modern React / Next.js stack.
How fast to start?	npm i -g @fecommunity/reactpress@beta → reactpress init → live stack in ~60 seconds.
License	MIT — fork, self-host, commercial use allowed.
Source	github.com/fecommunity/reactpress
Current release	4.0 (codename Extend) — plugins, desktop, npm theme catalog.

npm i -g @fecommunity/reactpress@beta
mkdir my-site && cd my-site
reactpress init

Surface	URL
Public site	http://localhost:3001
Admin	http://localhost:3001/admin/
API	http://localhost:3002/api/health

---

1. The industry problem

Modern content infrastructure forces a bad trade-off. Teams must pick two of three: great editing, frontend freedom, and a complete system you can run tomorrow.

1.1 The impossible triangle

Over the last decade, content tooling split into three paths. Each solves real problems — and each leaves a hole.

Path A: WordPress-style monolithic CMS

WordPress binds content management, theme rendering, and plugin extension inside one PHP runtime. For non-technical users it is extraordinary: install a theme, add plugins, launch ecommerce, memberships, forms, and SEO without writing code.

The costs are equally well known:

• Theme and plugin quality varies wildly — one bad plugin can tank performance or security.
• The front end is locked to the PHP theme system — React teams cannot reuse component libraries or design systems without a Headless detour.
• Headless mode is bolted on, not the default mental model; REST works, but often needs extra plugins and glue.
• Core Web Vitals frequently depend on caching layers (Redis, CDN, page-cache plugins) instead of SSR/ISR as a first-class design choice.

WordPress optimizes for "let people who cannot code publish" — not "let people who code in React publish with the same ease."

Path B: Static site generators

Hugo, Jekyll, early Gatsby, Astro — they maximize build-time HTML and deliver excellent Lighthouse scores at low hosting cost.

SSG hides a strict assumption: content change = developer edits Markdown + CI rebuild. Non-technical editors cannot ship articles independently. Drafts, scheduled posts, media libraries, comment moderation, and multi-author permissions — routine in WordPress — are absent or Git-shaped in pure SSG flows.

Next.js App Router and ISR help, but three questions remain unanswered in most setups:

• Where do posts live?
• Who can write in a browser without touching the repo?
• Where do uploaded images go?

Path C: Headless CMS

Strapi, Payload, Directus, Sanity, Contentful — they excel at content APIs: customizable schemas, multi-channel delivery, permissions.

What they typically do not ship is the visitor-facing website and the daily writing UI your authors expect as a finished product.

A typical Headless rollout:

Pick Headless CMS → define schema → tolerate or customize Admin
→ build Next.js front end → wire API → implement SEO / sitemap / OG
→ configure media storage → build or buy comments → write deploy scripts
→ train editors on a new back office

That is viable for mature platform teams. It is heavy for "we need a React-stack blog this week."

1.2 The contradiction, summarized

Path	Editing	Frontend freedom	Out of the box	Modern performance
WordPress	✅	❌	✅	△
SSG / bare Next.js	❌	✅	△	✅
Headless CMS	△	✅	❌	Depends on front end
Target: React publishing platform	✅	✅	✅	✅

React won on frontend freedom and performance. It never shipped the complete publishing platform category WordPress owns.

That is why ReactPress exists.

1.3 A front-end lead's real week

I have seen this sequence repeat across multiple teams:

Monday: Product wants a blog with SEO; marketing must publish without developers. You open the tech spec and list Strapi, Payload, Ghost, and Headless WordPress.

Tuesday: You pick Strapi. Docker, PostgreSQL, Content Types. The Admin works, but marketing complains that uploading an image requires four fields when they only want Markdown articles.

Wednesday: You start the Next.js front end — routing, layout, dark mode, syntax highlighting. Work that belongs in a theme is being rebuilt inside a product application.

Thursday: SEO — sitemap, Open Graph, JSON-LD, canonical URLs — three more pull requests. Comments? Disqus or build your own; the CMS backend does not include them by default.

Friday: Deploy API on a VPS, front end on Vercel, media on object storage, four CI pipelines. Marketing asks: "Where do I preview drafts?" You answer: "Preview mode is still in progress."

Next Monday: Product asks for status. You say "the backend is done." They ask: "When can we publish?"

The failure is not any single tool. Nobody delivered the full loop of publishing — install, write, preview, ship, extend.

ReactPress targets that gap — not with a better API alone, but with an integrated stack that is runnable on first install.

1.4 Why "one more Headless CMS" is not enough

Every new TypeScript Headless CMS launch gets praise for schema design. We celebrate those projects — they push content modeling forward.

For "ship our team blog this week," however, a prettier Content Type editor does not reduce the number of Next.js pages you must write.

The industry does not lack Headless CMS options. It lacks:

1. A production-grade visitor site by default — not a demo repo.
2. A writing Admin authors open daily — not Swagger's neighbor.
3. Extension points — install plugins, not fork core.
4. Operations entry points — doctor, not a forty-page deploy guide.

When all four are true, the category name should be Publishing Platform, not Headless CMS. ReactPress chooses the former.

1.5 Total cost of ownership: assembly vs platform

Hidden costs dominate Headless assembly projects:

Cost center	Headless assembly (typical)	ReactPress (default)
Initial engineering	2–8 weeks	~60 seconds to running stack
Ongoing repos	3–5 (API, web, infra, theme, scripts)	1 site directory + optional theme fork
Editor onboarding	Custom docs for bespoke Admin	WordPress-familiar /admin/
SEO baseline	Build sitemap, OG, JSON-LD yourself	Theme starter + SEO plugin
Offline writing	Not standard	Electron desktop + SQLite
Diagnostics	Log diving across services	reactpress doctor

Platforms win when time-to-first-article matters more than infinite schema flexibility on day one.

---

2. Why WordPress succeeded

Before asking for "React's WordPress," understand what WordPress actually won — beyond PHP and early hosting deals.

2.1 One front door, zero decision fatigue

WordPress users rarely choose among backend frameworks, front-end stacks, and deployment patterns. Download, database credentials, /wp-admin/ — one path.

That "zero decisions" feels limiting to engineers. For most site owners, fewer choices is the product.

ReactPress 4.0 adopts the lesson: npm i -g @fecommunity/reactpress@beta → reactpress init → API + Admin + theme in ~60 seconds. No Docker by default. No hand-written .env. No three terminal tabs.

2.2 Core / Theme / Plugin boundaries

Early WordPress established a durable split:

Layer	Responsibility
Core	Data model, admin framework, user roles
Theme	What visitors see
Plugin	Cross-cutting logic — SEO, forms, security, ecommerce

That separation enabled "change skin without changing bones" and "add capability without forking theme." A theme market and a plugin market followed.

React projects often lack an official, community-recognized boundary. Next.js apps merge CMS concerns, marketing UI, and product code. Changing "theme" means rewriting the repo.

ReactPress maps the model explicitly:

WordPress	ReactPress	Role
wp-admin	Admin (/admin/)	Content, media, settings
Theme	themes/* (Next.js)	Visitor SSR/ISR site
Plugin	plugins/* (Hooks)	Server-side extension
REST API	/api/*	Headless access, on by default
—	Desktop (Electron)	Local-first writing

2.3 Plugins as longevity

WordPress hosts 60,000+ plugins. Search, install, activate — that loop built a civilization of extensions without waiting for core releases.

React "plugins" are usually private npm packages or forks — high skill floor, not hot-swappable, no marketplace gravity.

ReactPress 4.0 ships Hook + plugin.json, Admin slots, and built-in SEO / summary / image-optimizer plugins so "extend without touching core" is platform-native.

2.4 Hosting democratization

WordPress succeeded with one-click installers on shared hosts. Users should not need to understand Nginx or PM2 on day one.

ReactPress defaults to embedded SQLite, documents VPS/Docker paths for growth, and ships reactpress doctor — lowering "will it run on my machine?"

2.5 What we learn — and what we refuse to copy

We learn: single entry point, theme/plugin boundaries, author-first workflows, data portability.

We refuse: welding visitor rendering and Admin into one PHP theme; plugin quantity over architectural debt; requiring Docker/MySQL for a first article.

Same editing workflow. Modern Next.js delivery. That is the accurate relationship to WordPress — and what WordPress alternative should mean in 2026: not PHP cosplay, but rebuilding the publishing platform category on React.

2.6 Gutenberg: writing UI as product, not afterthought

WordPress 5.0's block editor was controversial, but one decision was right: treat the writing surface as core product, not a database form with labels.

ReactPress Admin uses Markdown — our primary audience is technical teams and developer blogs — yet the principle holds: drag-and-drop media, categories, tags, schedules, comment moderation, and plugin settings live in Admin.

We deliberately avoid stuffing React presentation components into Admin as "blocks." That would leak theme logic into core. Presentation components belong in themes.

2.7 Data ownership and open source

WordPress's GPL heritage and MySQL-on-disk model made migration and self-hosting credible.

ReactPress is MIT. SQLite lives at .reactpress/reactpress.db. Backup can be tar czf backup.tar.gz .reactpress uploads. For teams searching open source CMS, that means auditable source, no mandatory cloud, and fork-friendly customization.

When content is an asset, the platform must be portable too.

2.8 The WordPress economy — lessons for ReactPress

WordPress created parallel economies:

• Hosting (managed WordPress)
• Themes (marketplace + custom agencies)
• Plugins (free + premium)
• Agencies (implementation + care plans)

ReactPress 4.0's roadmap — npm theme catalog, plugin catalog, marketplace — targets the same extension economies, but with npm + TypeScript + Next.js as the distribution layer instead of zip uploads to wp-content/.

The goal is not to clone ThemeForest on day one. The goal is to make theme and plugin authors have a standard addressable runtime so ecosystem gravity can accumulate.

---

3. The React ecosystem gap

"React CMS" is not an empty keyword. Many projects exist. Few occupy the Publishing Platform quadrant — editor-friendly and developer-friendly and complete out of the box.

3.1 Positioning map

Approach	Editor-friendly	Developer-friendly	Complete out of the box
WordPress	High	Low	High
ReactPress (target)	High	High	High
Headless CMS (Strapi, etc.)	Medium	High	Low
Next.js blog templates	Low	High	Low
Markdown + Git (Tina, Decap)	Low	High	Low
SaaS publishing (Ghost, Medium)	High	Varies	High

• Next.js blog templates: beautiful front ends, no CMS.
• Headless CMS: strong APIs; you build Admin UX and visitor site.
• Notion / docs → static: great drafting, weak custom domain + SEO control.
• Git-based CMS (Tina, Decap): developer-native; higher friction for non-technical editors.
• SaaS publishing (Ghost, Medium): complete loops, varying self-host and theme freedom.

The gap is upper-right: both editors and engineers happy, unified on React / Next.js.

3.2 Why Next.js did not ship a CMS

Next.js is a rendering and routing framework, not a content platform. Contentlayer, MDX, Draft Mode — excellent for developer-driven sites, not daily editorial operations.

Expecting Next.js to bundle WordPress-style Admin is like expecting React to bundle a database. Framework teams correctly stay in lane.

So Next.js CMS became an integration problem: every team wires Headless + custom Admin + SEO + deploy. The community has brilliant parts, not a standard whole.

3.3 Search intent behind the keywords

Keyword	Surface need	Deep need
React CMS	React admin	No PHP; unified stack
Next.js CMS	Next integration	SSR SEO + customizable front end
WordPress alternative	Leave WordPress	Keep workflow, lose PHP baggage
Open source CMS	Self-host	Data sovereignty, auditability
React publishing platform	End-to-end	One command, not five repos

ReactPress answers the last row: Publish with React. Ship like WordPress.

3.4 Our own iteration history

ReactPress evolved inside the FECommunity ecosystem:

Era	Codename	Lesson
2.x	—	Proved demand; packages too fragmented
3.0	Platform	One CLI, ~60s stack; Docker MySQL default felt heavy
3.1+	Toolkit	Unified API contract; Next 14 / React 18
4.0	Extend	Plugins, desktop, npm themes; SQLite default; bundled CLI runtime

Each release responded to Issues — not roadmap bingo. 4.0's bundled runtime, SQLite, npm themes, Hook plugins, and Electron desktop each map to repeated user stories.

3.5 Landscape comparison (default deliverables)

Solution	Ships by default	Visitor site	Typical friction
Strapi	API + Admin	No	Build Next.js front end
Payload	API + Admin (React)	No	Same
Sanity	API + Studio	No	SaaS pricing, vendor path
Contentful	API + web app	No	Enterprise Headless
Ghost	API + Admin + theme	Handlebars theme	Not React stack
TinaCMS	Git / API hybrid	Varies	Git conflicts, dev-centric
Next.js blog example	Sample code	Yes	No CMS; Markdown in repo
Headless WordPress	REST API	You build	Plugin/config sprawl
ReactPress	API + Admin + theme + plugins + CLI + desktop	Next.js SSR	Young plugin market

Google "Next.js CMS" and you mostly find tutorials on connecting Next.js to Headless — not installing a full CMS in one command. That tutorial-shaped gap is the product gap.

3.6 Signals from the community

Recurring sentences in discussions and Issues:

• "We already use Next.js — we don't want PHP WordPress for the blog."
• "Strapi works but I lost two weekends on the front end."
• "Is there a self-hosted open source option that isn't another assembly kit?"

These are engineering pain, not marketing copy. ReactPress 4.0 is built as a response.

3.7 The missing "default stack" moment

React has a default bundler story (Vite / webpack era), a default framework story (Next.js for full stack), a default UI story (component libraries) — but no default publish story.

When a junior developer asks "how do I launch my blog?" the answers fork:

• WordPress (PHP)
• Medium / Substack (platform lock-in)
• "Fork this Next.js template and use Notion as CMS"
• "Spin up Strapi"

There is no answer equivalent to create-react-app or next new for publishing. ReactPress aims to be that answer: reactpress init.

3.8 Framework churn vs platform stability

React teams rewrite front ends every few years — Pages Router to App Router, CSS-in-JS to Tailwind, REST to tRPC. Content outlives framework fashion.

A publishing platform must separate durable content (articles, media, URLs) from replaceable presentation (themes). WordPress survived because themes churn while posts remain. ReactPress copies that separation with Next.js themes + stable REST — not by freezing your entire app in one Next repo.

---

4. ReactPress philosophy

ReactPress is not only a Headless CMS. It is an open-source publishing platform for the React era.

4.1 One-sentence definition

Admin owns content · Theme owns presentation · Plugin owns logic
· API owns data · Toolkit owns the contract

• Content belongs to the system — posts, pages, media, taxonomy, comments, settings.
• Presentation belongs to themes — swappable Next.js apps.
• Logic belongs to plugins — SEO, summaries, image pipelines via Hooks.
• Data exposes through API — REST, Swagger, API keys.
• Toolkit unifies clients — one typed HTTP layer for Admin, theme, plugin UI.

4.2 vs Headless CMS

Dimension	Headless CMS	ReactPress
Deliverable	API (+ Admin)	API + Admin + theme + plugins + CLI + desktop
Visitor site	Your problem	Official Next.js theme; swappable
Onboarding	Deploy backend → build front end	reactpress init ~60s
Extension	Webhooks, custom fields	Hooks + plugin.json + Admin slots
Stack	Mixed	React + Next.js + NestJS

Need only an API and custom everything? Headless may be lighter.

Need WordPress workflow + React front end + one CLI? ReactPress fits — the practical WordPress alternative for JS teams.

4.3 Design principles

From ARCHITECTURE.md:

Maintainability → Extensibility → Tech fit → Low cost

Hard rules:

1. Admin does not serve visitor pages. Themes do not serve /admin/.
2. All front ends talk to the API only through Toolkit.
3. Server depends on no front-end package.
4. Themes never touch the database.

4.4 Two audiences, two paths

Audience	Goal	Entry
Site owners	Launch blog, team publishing	npm i -g @fecommunity/reactpress@beta → init
Contributors	Core, themes, plugins	Clone monorepo → pnpm dev

4.5 Thirty-second start

npm i -g @fecommunity/reactpress@beta
mkdir my-site && cd my-site
reactpress init

Service	URL
Public site	http://localhost:3001
Admin	http://localhost:3001/admin/ (admin / admin)
API	http://localhost:3002/api/health

SQLite by default. No Docker. reactpress doctor when something fails.

4.6 "Content in the system, front end for developers" in practice

Anti-pattern A: Embed full theme preview in Admin with global theme CSS — couples Admin to theme; theme swap breaks back office.

Anti-pattern B: Theme reads DB connection strings — kills Headless path and security boundaries.

ReactPress approach: Preview on :3003; themes use NEXT_PUBLIC_API_URL; mutations go through authenticated REST.

Editors and theme developers work in parallel pipelines — essential for multi-disciplinary teams.

4.7 vs visual site builders

Webflow, Framer, Wix solve publishing through visual editors + hosted lock-in. Great for landing pages; narrow for teams that need Git-reviewed theme code, CI deploy, API integrations.

ReactPress is not a drag-and-drop page builder. It serves teams who treat code as asset — themes in Git, plugins in monorepo, content in CMS.

4.8 What "platform" means operationally

A platform provides:

• Stable contracts (REST + Toolkit types)
• Lifecycle tools (init, doctor, logs, stop)
• Extension registries (themes, plugins)
• Opinionated defaults (SQLite, official theme, SEO plugin)
• Escape hatches (Headless-only, custom theme, MySQL)

A CMS backend alone provides APIs. ReactPress provides the full operational loop.

---

5. System architecture

ReactPress 4.0 uses a monorepo + multi-process model: content management, visitor delivery, and API services are decoupled; Toolkit unifies contracts.

5.1 Architecture overview

ReactPress splits presentation (Admin, Desktop, theme, plugin UI), contract (Toolkit), and platform (NestJS server, CLI, database). Admin, Desktop, and themes never talk to the database directly — they call the API through Toolkit. Plugins extend the server through Hooks. The CLI orchestrates processes on a single machine or VPS.

See the package matrix below and the authoring flow in §5.2.

5.2 Authoring-to-delivery flow

Step-by-step:

1. Author creates content in Admin or Desktop.
2. Request flows through Toolkit to NestJS API.
3. Plugins run on Hooks — summaries, SEO validation, image jobs.
4. Data persists to SQLite (default) or MySQL.
5. Theme fetches published content and SSR/ISR renders for visitors and crawlers.

5.3 Package responsibility matrix

Package	npm	Role	Rendering	SEO
server	Bundled in CLI	Business logic, persistence, auth, Hooks	—	—
web	Bundled in CLI	Admin UI	Vite CSR	No
themes/	Per theme	Visitor site	Next SSR/ISR	Yes
toolkit	@fecommunity/reactpress-toolkit	API client, types	—	—
plugins/	Per plugin	Hook logic + Admin slots	Mixed	Plugin-driven
desktop	GitHub Releases	Electron + local API	Loads web/dist	No
cli	@fecommunity/reactpress	init, doctor, orchestration	—	—

5.4 Technology choices

Decision	Choice	Rationale
API	NestJS	Modular TS, Hook-friendly
Admin	Vite + React SPA	Interactive; no SSR needed
Visitor site	Next.js App Router	SSR/ISR, SEO primitives
Extension	Hooks + manifest	WordPress mental model
Default DB	SQLite	Zero config
Desktop	Electron	Reuse Admin SPA

5.5 Runtime ports

Process	Default port	Notes
Theme (public)	3001	Includes /admin/ proxy
API	3002	REST + Swagger
Theme preview	3003	Admin iframe preview
Admin (monorepo dev)	3000	Standalone Vite dev server

5.6 Directory layout after init

my-site/
├── .reactpress/
│   ├── config.json          # ports, database, URLs
│   ├── runtime/{theme-id}/  # installed theme copy
│   ├── plugins/{plugin-id}/ # installed plugins
│   └── reactpress.db        # SQLite (default)
├── .env                       # CLI-generated
└── uploads/                   # media

Think of .reactpress/ as WordPress wp-content/ + database — backup with:

tar czf backup.tar.gz .reactpress uploads

5.7 Toolkit: single API client discipline

Early 3.x allowed ad-hoc fetch per package → field drift between Admin and theme. 4.0 enforces Toolkit only:

• OpenAPI-aligned types and paths
• Unified errors and auth headers
• createThemeApi, PluginContext, Admin React hooks

You lose "raw axios everywhere" freedom; you gain fewer production surprises on upgrade.

5.8 Headless without leaving the platform

curl -H "X-API-Key: YOUR_KEY" \
  "http://localhost:3002/api/article/headless/list?status=publish&page=1&pageSize=10"

Use API-only for mobile apps, secondary sites, or microservices — same content, many surfaces. That is how a React CMS should flex.

5.9 Monorepo map for contributors

Directory	Purpose
cli/	Global CLI, process orchestration, bundled runtime
server/	NestJS modules, entities, Hook service
web/	Admin SPA
themes/	Theme registry + hello-world + catalog anchors
plugins/	Plugin registry + built-ins
toolkit/	Shared types and HTTP clients
desktop/	Electron main/preload, local API bootstrap

End users never clone this. They install @fecommunity/reactpress and run init.

5.10 Failure modes and boundaries

Failure	Guardrail
Theme bypasses API	Architecture review; no DB drivers in theme
Plugin injects Next routes	Forbidden — plugins are server-side
Admin embeds business rules	Belongs in plugins via Hooks
Multiple API clients	Toolkit enforcement

These boundaries feel strict until you maintain the project for three years — then they feel like oxygen.

---

6. See it in action

Platforms are judged by whether they run, not only whether they diagram well.

6.1 CLI: install to live site in ~60 seconds

One global install. One init. Browser opens to visitor site and Admin. No Docker pull. No six terminals. No handwritten env files.

This is the WordPress "single front door" lesson — delivered as React + Next.js + NestJS.

6.2 Visitor site: search, comments, knowledge base, dark mode

The official reactpress-theme-starter demo includes:

• Full-text search
• Comment system
• Knowledge base / docs navigation
• Dark mode
• Responsive layout
• sitemap.xml, robots.txt, JSON-LD

6.3 Lighthouse: performance and SEO as defaults

On the official theme demo, scores reach Performance 95 / SEO 100 (your production numbers depend on hosting and content).

For Next.js CMS evaluations, this matters: you should not trade WordPress-style workflow for a slow visitor experience. The default theme exists to prove workflow + speed coexist.

6.4 Live demos

Demo	URL
Production blog	blog.gaoredu.com
Theme starter	reactpress-theme-starter.vercel.app
Documentation	docs.gaoredu.com

6.5 Before / after assembly

Typical Headless assembly	With ReactPress
Pick CMS backend	reactpress init
Build or customize Admin	Admin at /admin/
Develop Next.js visitor site	http://localhost:3001
Debug env / ports / DB	reactpress doctor

---

7. Admin: the writing surface

Visitors see the theme. Authors live in Admin. If Admin fails, the platform fails — regardless of API elegance.

7.1 Post editor

Admin provides:

• Markdown editor with code blocks, tables, paste-to-upload images
• Draft / publish workflow
• Categories and tags
• Pages and knowledge base content types
• Revision history (server-side)

7.2 Media library

Centralized media under uploads/ with optional OSS configuration (Aliyun OSS supported in server modules). Authors should not FTP files or open S3 consoles for a blog image.

7.3 Plugins panel

Install, enable, and configure plugins without SSH. Built-in plugins:

Plugin	Capability
seo	Slug, keywords, meta description + editor slot
hello-world	Auto-generate summaries on publish
image-optimizer	Batch WebP optimization for legacy media

7.4 Appearance and themes

Appearance → Themes — install from registry, preview on :3003, activate for :3001. Swapping themes does not migrate content; it changes presentation only.

7.5 Site settings

Site title, URLs, API keys, comment policies, and integration settings — the operational layer authors and admins share.

7.6 Comments moderation

Comments flow through API with JWT for creation, server-side HTML sanitization after Markdown parsing (security hardening in 3.7+), and moderation UI in Admin. Stored XSS and spam are platform concerns, not theme afterthoughts.

7.7 Default credentials warning

Local admin / admin is for trial only. Change passwords before production; reactpress doctor surfaces common security omissions.

---

8. Theme system

Theme = presentation. What visitors see is a replaceable Next.js app.

8.1 Two sources, three layers

Sources

Source	Origin	Installed to
Local	themes/{id}/ in monorepo	.reactpress/runtime/{id}/
npm	Theme package	.reactpress/runtime/{id}/

Layers

Layer	Role
themes/	Registry — what can be installed
.reactpress/runtime/	Materialized copy the CLI runs
Database + config	Which theme is active on port 3001

8.2 Official themes

Theme	Source	Use case
hello-world	Monorepo local	Learning, fork base
reactpress-theme-starter	npm catalog	Production — search, KB, comments

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

8.3 Mock development without API

npx create-next-app@latest my-blog \
  --example "https://github.com/fecommunity/reactpress-theme-starter" \
  --use-pnpm
cd my-blog && pnpm dev:mock

Theme authors iterate UI without booting full platform — faster design cycles.

8.4 Data fetching in themes

import { createThemeApi } from '@fecommunity/reactpress-toolkit/theme';

const api = createThemeApi({ baseURL: process.env.NEXT_PUBLIC_API_URL });
const { data } = await api.article.list({ status: 'publish', page: 1 });

Environment variables align with reactpress init output (CLIENT_SITE_URL, API URL).

8.5 App Router conventions

Official starter routes (illustrative):

Route	Purpose
/	Home
/blog/[slug]	Article detail
/blog	Article list
/docs/[...slug]	Knowledge base
/search	Search results

Customize freely — contract is fetch via Toolkit, not specific folder names.

8.6 SEO responsibilities in themes

As the Next.js CMS visitor layer, themes own:

• SSR/ISR HTML completeness for crawlers
• Per-route <title>, meta description, OG tags from API fields
• /sitemap.xml and robots.txt
• JSON-LD structured data

Admin + SEO plugin write metadata; theme renders it. Change SEO strategy by swapping plugins, not forking themes.

8.7 Deployment patterns for themes

Pattern	When
Unified	API + theme same VPS — reactpress init style
Split	Theme on Vercel Edge, API on VPS — classic Jamstack
Custom	Mobile app or second Next site via Headless API only

One content graph, many surfaces — the publishing platform difference.

8.8 Migrating from WordPress themes

There is no magic PHP→JSX converter. You rewrite presentation in React — cost upfront, benefits long-term:

• Reuse design system components
• Storybook and unit tests on UI
• Predictable performance without unknown PHP plugins

Migrate content via WordPress REST export scripts into ReactPress API. ReactPress offers new front end, familiar workflow.

8.9 Theme catalog and version compatibility

theme.json + theme.manifest.schema.json declare requires: ">=4.0.0". CLI blocks silently incompatible installs. Roadmap theme marketplace adds discovery and ratings — WordPress theme shop proved skin-swapping demand; we distribute via npm + Next.js.

---

9. Plugin system

ReactPress 4.0 (codename Extend) makes Hook + plugin.json a first-class extension model.

Theme = presentation · Plugin = logic

9.1 Lifecycle

Discover → Install → Enable → Configure → (optional) Uninstall

• Admin → Plugins for GUI
• CLI: reactpress plugin list, reactpress plugin install <id>
• Manifest: plugin.json declares hooks, Admin slots, settings schema

9.2 Registry model

Location	Purpose
plugins/	Registry — available plugins
.reactpress/plugins/	Installed copy + built dist
Database globalSetting	Enabled list and per-plugin config

On activate, HookService loads the plugin module and registers its hooks — the same three-layer pattern as themes.

9.3 Server plugin example

import type { PluginContext } from '@fecommunity/reactpress-toolkit/plugin';

export function register(hooks: PluginContext['hooks'], ctx: PluginContext) {
  hooks.addFilter('article.beforePublish', async (article) => {
    if (!article.summary) {
      article.summary = article.content.slice(0, 160);
    }
    return article;
  });
}

Build: pnpm run build:plugins in monorepo; reactpress plugin install for end users.

9.4 Hooks vs webhooks

Mechanism	Direction	Can mutate data	Example
Hook	In-process inbound	Yes (filters)	SEO validation, auto summary
Webhook	Outbound HTTP	No	Slack notify, CI trigger

Publish pipeline:

article.service
  ├─ applyFilters('article.beforePublish')   ← plugins
  ├─ persist
  ├─ doAction('article.afterPublish')        ← plugins
  └─ webhookService.dispatch('article.published')

9.5 Admin slots

Plugins register UI slots — seo adds fields beside the article editor. Authors experience meta boxes, not scattered settings pages.

9.6 Security

• Manifest JSON Schema validation
• Module path constraints
• Ajv config validation

Stricter than "install zip and hope" — appropriate for self-hosted open source CMS.

9.7 Building your first plugin

Fork plugins/hello-world → rename id → implement register() → pnpm build:plugins → enable in Admin. An afternoon for NestJS-comfortable teams.

WordPress has more hooks today; ReactPress hooks are fewer but fully typed and testable — optimized for engineering teams customizing for themselves.

9.8 SEO plugin collaboration example

seo validates slug uniqueness on article.beforePublish, injects Admin fields, theme SSR reads metaTitle, metaDescription, keywords. Plugin writes, theme reads, core stays dumb — ideal React CMS + Next.js CMS split.

9.9 Honest comparison to WordPress plugins

WordPress: 60,000+ plugins, search-and-install economy.

ReactPress: young catalog, strong mechanism, built-in essentials, best for teams who can code extensions.

If you need off-the-shelf ecommerce, membership, or form builders today, WordPress may win — see ReactPress vs WordPress.

---

10. Desktop client

WordPress has no true peer for offline-first, local-database writing in the core product. ReactPress Desktop fills that gap.

10.1 Architecture

Electron shell + same Admin SPA as web — one UI codebase, consistent behavior, lower maintenance than a separate native editor.

10.2 Modes

Mode	Scenario	Behavior
Local (default)	Offline, try without Docker	Embedded SQLite API at 127.0.0.1:3002
Remote	Production/staging API	Admin points at remote REST

Switch under Settings → Desktop client or workspace panel on login.

10.3 Sync

Local → remote push for articles, pages, and selected settings (requires remote admin JWT). Recommended flow: validate on staging before production push.

10.4 Installers

GitHub Releases ship macOS DMG, Windows NSIS, Linux AppImage via CI matrix builds.

pnpm dev:desktop      # monorepo development
pnpm build:desktop    # installers → desktop/release/

Docs: Desktop client guide.

10.5 vs Notion-class editors

Notion, Google Docs, and wikis draft well but publish poorly to custom-domain Next.js — export steps, style loss, proprietary sync.

Desktop local mode means the writing UI is the production Admin, synced via standard REST — closer to Obsidian drafting + WordPress publishing, integrated and open source.

10.6 Security notes

Sync is one-way push with credentials. Test conflict behavior on staging. Treat like any CMS bulk import — rehearse before production.

---

11. Headless API

ReactPress is a publishing platform first — and a Headless React CMS by default. Any client that speaks HTTP can participate.

11.1 Explore with Swagger

http://localhost:3002/api

Swagger UI documents routes, parameters, and response shapes — generated from NestJS decorators. Production: https://your-api-domain.com/api.

11.2 Authentication

Method	Use case
Session / JWT	Admin SPA same-origin requests
API Key (X-API-Key)	Headless servers, scripts, mobile

Create keys in Admin → Settings → API. Keys carry admin-level power — HTTPS only, rotate regularly, never commit to git.

11.3 Core endpoints

Method	Path	Description
GET	/api/health	Health check
GET	/api/article/headless/list	Paginated published articles
GET	/api/article/:id	Single article
GET	/api/page/list	Pages
GET	/api/category/list	Categories
GET	/api/tag/list	Tags
GET	/api/comment/list	Comments
GET	/api/setting/public	Public site settings
POST	/api/article	Create article (auth required)

Exact contracts live in Swagger — treat this table as a map, not the spec.

11.4 curl examples

Health:

curl http://localhost:3002/api/health

Published articles:

curl -H "X-API-Key: YOUR_KEY" \
  "http://localhost:3002/api/article/headless/list?status=publish&page=1&pageSize=10"

11.5 Toolkit TypeScript SDK

import { createApiClient } from '@fecommunity/reactpress-toolkit';

const client = createApiClient({
  baseURL: process.env.REACTPRESS_API_URL,
  apiKey: process.env.REACTPRESS_API_KEY,
});

const articles = await client.article.headlessList({
  status: 'publish',
  page: 1,
  pageSize: 10,
});

One SDK for Admin, themes, plugins, and external apps — types track API evolution.

11.6 Headless-only deployments

Run API without caring about the bundled theme:

• Marketing site on a custom Next repo
• Mobile app consuming articles
• Multi-brand networks sharing one content backend

You still benefit from ReactPress Admin for editors. You only opt out of the default visitor theme.

11.7 WordPress REST vs ReactPress Headless

WordPress REST exists but Headless is not the default product story. Field shapes vary with plugins; performance tuning often still assumes PHP rendering.

ReactPress assumes Headless consumers from day one — list endpoints, API keys, Toolkit, and OpenAPI as first-class docs.

11.8 Webhooks for external systems

Beyond in-process Hooks, server dispatches outbound webhooks (e.g. article.published) for Slack, CI, search indexers, or data warehouses — async integration without blocking publish latency.

---

12. SEO and performance

Teams choose Next.js CMS stacks largely for search visibility and Core Web Vitals. ReactPress splits SEO across plugins (data) and themes (rendering).

12.1 Rendering strategy

Layer	Strategy	SEO impact
Admin	CSR (Vite)	Not indexed — correct
Theme	SSR / ISR	Full HTML for crawlers
API	JSON	Feeds theme and Headless

12.2 Built-in SEO plugin

Authors set slug, focus keywords, and meta description in Admin. Theme emits:

• <title> and meta description
• Open Graph and Twitter cards
• Canonical URLs
• JSON-LD (Article, WebSite, etc. in starter)

12.3 Sitemap and robots

Official theme generates /sitemap.xml and robots.txt from API content — no manual XML editing.

12.4 Performance practices in starter theme

• Next.js code splitting and image optimization
• ISR for high-traffic lists where configured
• Minimal client JS on article pages
• Dark mode without hydration flash (theme-dependent)

Lighthouse 95 Performance / 100 SEO on demo is achievable baseline — not a guarantee for every host.

12.5 ReactPress vs WordPress SEO plugins

WordPress often stacks Yoast or Rank Math on top of theme-dependent markup. ReactPress defaults to structured SEO fields + SSR theme — fewer moving parts for standard blogs and docs.

12.6 Internationalization note

Docs site supports en and zh locales. Themes can implement i18n routes; content model supports multiple sites via settings and custom theme logic — i18n at theme layer keeps core simpler.

12.7 Measuring before launch

1. Run Lighthouse on staging theme URL
2. Validate rich results with Google Search Console
3. Fetch as Google / inspect rendered HTML (not only JSON API)
4. Confirm sitemap.xml lists published URLs only

---

13. Security model

Self-hosted open source CMS must be safe by default and auditable by admins.

13.1 Highlights (3.7+)

• SQL injection: whitelist filter columns in public list APIs (GHSA-wmw4-mw6x-6vfm)
• Stored XSS: sanitize comment HTML post-Markdown; JWT required for POST /comment; Helmet CSP headers
• Reporting: SECURITY.md

13.2 Plugin sandboxing

Manifest validation, constrained require paths, schema-validated plugin config — reduce "malicious plugin" surface compared to unrestricted PHP includes.

13.3 API keys

Equivalent to admin power. Store in secrets manager; scope CI keys read-only where possible; rotate on team churn.

13.4 Production checklist

• [ ] Change default admin password
• [ ] HTTPS everywhere
• [ ] MySQL credentials not in git
• [ ] Rate limiting at reverse proxy
• [ ] Backup .reactpress/ and uploads/ on schedule
• [ ] Keep @fecommunity/reactpress updated for security patches

13.5 Comments attack surface

Public write endpoints are classic XSS/spam targets. Server-side sanitization + auth + CSP is platform duty — themes should not "fix" unsafe HTML alone.

---

14. Deployment patterns

reactpress init targets local and small self-hosted production. Scale up when traffic demands.

14.1 SQLite → MySQL

Edit .reactpress/config.json database.mode, apply config, migrate data per deployment docs. MySQL suits concurrent writers and larger catalogs.

14.2 Docker Compose

Orchestrate API + theme + reverse proxy + MySQL — good for VPS teams wanting reproducible infra. See Docker deployment.

14.3 PM2 process management

Node processes for API and theme under PM2 on a single VPS — simple middle ground without Kubernetes.

14.4 Split hosting

Component	Host	Notes
API	VPS / container	SQLite or MySQL
Theme	Vercel / Netlify	NEXT_PUBLIC_API_URL points remote
Media	Local disk or OSS	Configure in server settings

Classic Jamstack + Headless — still using ReactPress Admin for editors.

14.5 Backups

# SQLite + uploads snapshot
tar czf backup-$(date +%F).tar.gz .reactpress uploads

For MySQL, add mysqldump to cron. Test restores quarterly — backups are wishes until restored.

14.6 CI/CD

• Theme repo: deploy on push to main
• API: deploy on tag or manual workflow
• Content: lives in DB — not redeployed with theme unless static export pattern

Separate content lifecycle from code lifecycle — another WordPress lesson.

14.7 Environment variables

CLI generates .env from .reactpress/config.json. Avoid hand-editing unless you understand sync direction — reactpress config --apply is safer.

---

15. Migration paths

15.1 New sites

npm i -g @fecommunity/reactpress@beta
mkdir my-site && cd my-site
reactpress init

Fastest path to a React publishing platform proof of concept.

15.2 ReactPress 3.x → 4.0

4.0 adds plugins, desktop, npm theme catalog — no forced breaking config migration.

npm i -g @fecommunity/reactpress@beta
cd your-site
reactpress doctor

Optional: enable hello-world / seo plugins; try reactpress-theme-starter; install desktop client.

Guide: 3.x → 4.0 migration.

15.3 WordPress → ReactPress

Asset	Migration approach
Posts / pages	WordPress REST export → script → ReactPress API
Media	Download uploads; re-upload or mirror URLs
Categories/tags	Map taxonomy via API
Theme	Rewrite in Next.js — plan engineering time
Plugins	Reimplement critical logic as ReactPress plugins

Expect theme rewrite as main cost — not data model translation.

15.4 Strapi / other Headless → ReactPress

If you already shaped content in another Headless CMS, write import scripts against ReactPress POST endpoints or DB seed tools. You may adopt ReactPress Admin gradually while keeping an existing front end temporarily via parallel APIs.

15.5 Static Markdown repos → ReactPress

Many teams store posts in content/*.md. Import scripts can create articles via API, preserving slugs and dates. Editors then use Admin for new content — Git-as-CMS graduations without losing history.

---

16. Who should use ReactPress

16.1 Fit matrix

Scenario	Why ReactPress fits
Personal dev blog	Admin + fast Next theme
Open source docs + changelog	Knowledge base + articles in one theme
SaaS marketing site	Headless API + custom Next front
Multi-editor teams	Admin for writers, theme repo for engineers
Offline-first authors	Desktop + SQLite + sync
WordPress alternative evaluation	Familiar workflow, modern stack

16.2 User stories

Alice — indie developer

Uses Next.js for side projects; hates git commit per typo fix. reactpress init, publishes Sunday afternoon, Lighthouse green, VPS serves :3001. No Strapi, no PHP.

Open source maintainers

Docs versioned in knowledge base API; release notes as articles; same theme, different routes. Contributors use Admin; engineers keep custom React components in theme Git.

Marketing + front-end parallel

Marketing schedules drafts in Admin; front-end fork theme-starter for brand motion; plugin Hook posts to Slack on article.afterPublish. Nobody pastes Markdown into production code.

16.3 Self-assessment checklist

ReactPress is likely worth a trial if ≥3 are true:

• [ ] Primary stack is React / Next.js
• [ ] Non-developers must publish
• [ ] Self-hosted open source required
• [ ] Tired of maintaining CMS + front end + deploy separately
• [ ] Evaluated WordPress, want to avoid PHP
• [ ] Care about SSR SEO and Core Web Vitals
• [ ] Want offline or local-first writing

16.4 When to choose WordPress instead

• Need mature plugin marketplace (ecommerce, memberships, complex forms)
• Large existing WordPress theme/plugin investment
• Fully non-technical team depends on off-the-shelf plugins without engineering

Honest comparison: ReactPress vs WordPress.

16.5 When to choose pure Headless

• Mobile-only product consuming content
• Content model changes weekly in early product discovery
• You already invested in Strapi/Payload and only need a new Next front end

ReactPress shines when Admin + default theme + CLI matter — not API-only experiments.

---

17. Roadmap

4.0 is the extensible base, not the finish line.

17.1 Near term (4.x)

• Plugin npm catalog and a planned reactpress plugin create scaffold
• Desktop auto-update, tray icon, global shortcuts
• A planned reactpress theme create scaffold
• Theme and plugin marketplace — discovery, versions, compatibility hints (roadmap)

17.2 Medium term

• More official plugins (spam filtering, analytics, i18n helpers)
• Managed hosting partnerships — WordPress-style one-click for ReactPress
• Multi-site / multi-tenant for agencies
• Deeper AI writing integrations via plugin Hooks

17.3 Long-term vision

"React stack default for publishing" should be as easy to say as WordPress.

When someone asks "what do we use for the company blog?", answers should include:

npm i -g @fecommunity/reactpress@beta
reactpress init

17.4 How to contribute

• Publish themes to npm catalog
• Share migration scripts from WordPress or Strapi
• Contribute plugins as examples
• File Issues with reproduction steps

React's WordPress will not appear by accident — it will be built by developers tired of assembly.

---

18. FAQ

Is ReactPress free?

Yes. MIT license. Commercial use allowed. Self-host without vendor fees.

Is 4.0 production-ready?

4.0 is published on npm as @fecommunity/reactpress (currently @beta before @latest promotion). Core paths (init, Admin, API, theme, plugins) are used in production on blog.gaoredu.com. Validate on staging; read the migration guide.

Do I need Docker?

No for default CLI flow — SQLite embedded. Docker/MySQL when you configure embedded-docker or external database in .reactpress/config.json.

Can I use my own front end?

Yes. Headless REST + API Key + Toolkit SDK. Fork theme-starter or build from scratch against /api/article, etc.

How is this different from WordPress?

Same admin-driven publishing workflow, but default Next.js performance, cleaner Headless path, and no PHP theme/plugin entropy for JS teams.

WordPress alternative? Headless CMS? Next.js blog?

All three: self-hosted WordPress-style editing, Headless REST for custom apps, official Next theme with strong Lighthouse defaults.

How does ReactPress compare to Strapi or Payload?

They primarily ship content APIs. ReactPress ships API + Admin + theme + plugins + CLI + desktop — a React publishing platform, not only a backend.

Can I migrate from WordPress?

Content yes (scripts/REST). Theme requires Next.js rewrite. Plan engineering for presentation layer.

Where is documentation?

docs.gaoredu.com — installation, architecture, plugin/theme development, deployment, desktop client.

How do I report security issues?

Follow SECURITY.md. Do not post exploitable details in public Issues first.

What Node version is required?

Node.js 20+ for current CLI releases.

Does ReactPress support MySQL?

Yes — configure in .reactpress/config.json for production workloads beyond SQLite.

Can I run API-only?

Yes — Headless consumers use API + Admin; visitor theme optional if you bring your own Next app.

How do plugins differ from themes?

Themes change visitor UI. Plugins change server logic via Hooks — SEO rules, summaries, integrations.

Is the desktop app required?

No. It is optional for offline/local-first authors. Web Admin is complete.

How do updates work?

npm i -g @fecommunity/reactpress@latest for CLI; reactpress doctor after upgrade; review changelog at /blog.

---

19. Getting started

19.1 Install CLI

npm i -g @fecommunity/reactpress@beta

4.x may publish under @beta before @latest promotion — check npm.

19.2 Initialize site

mkdir my-blog && cd my-blog
reactpress init

19.3 Verify services

Check	Command / URL
Health	curl http://localhost:3002/api/health
Admin	http://localhost:3001/admin/
Public	http://localhost:3001

19.4 First article

1. Log in to Admin
2. Create article with title, Markdown body, category
3. Enable SEO plugin — fill meta description
4. Publish
5. View on public site — confirm SSR source in browser devtools

19.5 Install official theme (optional)

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

Enable in Appearance → Themes.

19.6 Enable plugins

Plugins → Install → Enable seo and hello-world. Edit an article — observe SEO slot and auto-summary on publish.

19.7 Try desktop (optional)

Download from GitHub Releases or pnpm build:desktop from monorepo.

19.8 Next steps in docs

• 5-minute first site
• Core concepts
• Architecture overview
• Plugin development
• Theme development
• Headless API

19.9 Feedback

If you try reactpress init and hit a wall, open a GitHub Issue with reactpress doctor output — include logs and your environment so maintainers can reproduce the failure.

---

20. Conclusion

React changed how we build interfaces. It did not equally change how we publish — not because developers lack skill, but because the industry shipped parts while WordPress shipped a platform.

WordPress taught us that publishing winners combine:

• One front door — low decision fatigue
• Clear boundaries — core, theme, plugin
• Author-first workflows — writing is the product
• Extension economies — markets around stable contracts
• Portable data — self-hosting stays credible

ReactPress 4.0 translates those lessons into the React era:

Capability	What you get
CLI	reactpress init in ~60 seconds
Admin	WordPress-familiar content operations
API	Headless REST + Swagger + API keys
Theme	Swappable Next.js SSR with SEO defaults
Plugins	Hook + plugin.json extensibility
Desktop	Offline SQLite writing, sync when ready
License	MIT open source

We are not claiming 60,000 plugins tomorrow. We are claiming the mechanism and integrated defaults so React teams stop rebuilding the same five-repo assembly for every blog, docs site, and marketing property.

If you searched for React CMS, Next.js CMS, WordPress alternative, open source CMS, or React publishing platform — start here:

npm i -g @fecommunity/reactpress@beta
mkdir my-blog && cd my-blog
reactpress init

Sixty seconds later, open http://localhost:3001/admin/ and write post number one.

Publish with React. Ship like WordPress.

Two years in, the lesson is straightforward: the ecosystem did not need another Headless API — it needed a complete publishing loop aligned with how React teams ship front ends. If you are still maintaining separate CMS, theme, and deploy repositories for a blog, this guide documents the problem, the architecture, and the defaults we chose in ReactPress 4.0.

For shorter onboarding, see 5-minute first site or ReactPress 4.0 overview. For comparison matrices, extended FAQ, and operational runbooks, see the canonical docs edition.

---

Related links

• GitHub — fecommunity/reactpress
• Live demo — blog.gaoredu.com
• Theme demo — reactpress-theme-starter.vercel.app
• Documentation — docs.gaoredu.com
• Chinese version
• ReactPress 4.0 guide
• ReactPress vs WordPress
• Architecture overview
• Desktop client
• Changelog
• Plugin development
• Theme development
• Headless API guide
• Installation
• Troubleshooting
• npm — @fecommunity/reactpress

---

ReactPress is developed by fecommunity and released under the MIT License.

Comments

[FECommunity]

Thanks for reading!

I'm especially interested in feedback from developers who build content-heavy React applications.

What do you usually use today for:

• Blogs?
• Documentation?
• Developer portals?
• Content platforms?

Do you build your own CMS layer, use a headless CMS, or something else?