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 |

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

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.

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.

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

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