ReactPress Technical Architecture

ReactPress is a monolithic-yet-modular publishing platform: one CLI bootstraps a NestJS API, MySQL database, built-in admin console, and optional headless visitor themes. Content is authored once in the admin and consumed everywhere through a stable REST envelope { "success": true, "data": ... }.

One backend, many presentation layers. The same API powers the bundled admin UI, official themes, and your custom Next.js frontends.

Core layers

Learn more

• reactpress.surge.sh — product overview and documentation
• GitHub repository — CLI, server, client, toolkit, templates
• Theme Starter — official headless visitor theme (this repo)

Quick Start

The CLI orchestrates every service in the ReactPress architecture. After a global install, init writes project config and dev starts the API, admin, and default visitor site together.

Prerequisites

• Node.js 18+ — required for the CLI
• Docker — recommended; default bundled MySQL runs in a container
• MySQL — optional; use your own instance instead of Docker

Install and run

npm i -g @fecommunity/reactpress@3
mkdir reactpress-theme-starter && cd reactpress-theme-starter
reactpress init
reactpress dev

When dev is ready, open the URLs printed in the terminal:

Tips

• Run reactpress with no arguments for the interactive menu.
• Run reactpress doctor or reactpress status if something does not look right.

Architecture in Detail

ReactPress separates content management (NestJS + MySQL + admin) from presentation (visitor themes). The REST API is the contract between both sides.

Request flow (headless mode)

1. Editor publishes an article in the admin console.
2. NestJS persists content to MySQL and exposes it at GET /api/article/:id.
3. Theme Starter fetches via themeApi during SSR and renders App Router pages with ISR.
4. Browser receives HTML; subsequent navigations hydrate client components from the toolkit.

Monorepo packages

• CLI — project lifecycle and local orchestration
• Server — NestJS modules for articles, categories, tags, pages, comments, knowledge, media
• Client — bundled admin and default visitor UI
• Toolkit — @fecommunity/reactpress-toolkit for third-party themes
• Theme Starter — reference headless implementation (this repository)

Headless entry point

Run reactpress dev --api-only when you only need the API and connect a custom theme such as Theme Starter with pnpm dev.

Documentation: reactpress.surge.sh

CLI Reference

After a global install, every workflow starts from the terminal.

npm i -g @fecommunity/reactpress@3

The monorepo on GitHub contains the CLI, client, server, toolkit, and templates. Contributors use pnpm install and pnpm run dev to develop the platform itself.

Deploy ReactPress

Production deployment can be monolithic (CLI build + start) or split: NestJS API on your server, Theme Starter on Vercel.

Production commands

npm i -g @fecommunity/reactpress@3
reactpress build
reactpress start

Deploy with Vercel, PM2, Docker, or your preferred hosting. The public site, admin console, and API can run together or split across services in headless mode.

Theme Starter on Vercel

This repository deploys as a headless frontend. Point REACTPRESS_API_URL and CLIENT_SITE_URL at your ReactPress instance, or use build:mock for a demo without a backend. See reactpress.surge.sh for deployment guides.

Resources

• reactpress.surge.sh — official documentation
• README — deployment details for Docker and monorepos

ReactPress Theme Starter

This repository is the official headless visitor theme for ReactPress. It does not store content locally — every page is rendered from the ReactPress REST API (or built-in mock API during development).

Project structure

app/              # App Router pages (home, article, category, search…)
components/       # Layout, article, comment, search UI
lib/reactpress/   # bootstrap, metadata, SEO, providers
lib/mock-api/     # Offline mock data for pnpm dev:mock
theme.json        # Template map + appearance panel schema

Data integration

Server components call fetch*PageProps(themeApi, …) from @fecommunity/reactpress-toolkit/theme/server. Client islands use hooks and providers from @fecommunity/reactpress-toolkit/ui. All API responses follow { "success": true, "data": ... }.

Development modes

• pnpm dev:mock — built-in mock API, no backend required (used by Vercel demo)
• pnpm dev — connect to local or remote ReactPress API
• pnpm build:mock — CI / demo production build with mock data

Appearance

Light/dark mode and primary colors are driven by theme.json appearance settings (defaults: rose primary #e11d48, white / dark gray backgrounds) and applied at runtime via CSS variables.

Repository: github.com/fecommunity/reactpress-theme-starter · Docs: reactpress.surge.sh