DEV Community

Eniola Omotee
Eniola Omotee

Posted on

How We Rebuilt a WordPress LMS Front End with React and Cloudflare Pages, without leaving WordPress

The site in this write-up is an exam-prep platform for a professional certification. It runs on WordPress with Tutor LMS for courses, WooCommerce for the shop and a card payment gateway. The learning side worked. The marketing side did not: the homepage was a stock theme, slow to change and hard to make look like a real product.

We wanted a new front end, but we could not afford to break enrolments, logins or checkout while building it. This is how we did it, what went well and what hurt.

The decision: hybrid, not headless

We looked at three routes.

  1. A new WordPress theme. We tried a premium LMS theme first. Its bundled plugins were old and threw fatal errors on PHP 8, so we rolled back to the old theme.
  2. Full headless. React for everything, WordPress as an API. That means rebuilding login, the student dashboard, the lesson player and checkout. For a small team that is months of work and a lot of payment risk.
  3. Hybrid. React owns the marketing pages only. Everything that involves an account or money stays in WordPress, and React links to it.

We chose the hybrid. The rule was simple: if a page needs a session or a payment, WordPress serves it.

How it is wired

1. A React app that builds to two fixed files. The app is React, TypeScript and Vite. We turned off code splitting and hashed filenames so the output is always app.js and app.css:

// vite.config.ts
export default defineConfig({
  plugins: [react()],
  build: {
    cssCodeSplit: false,
    rollupOptions: {
      output: {
        entryFileNames: "app.js",
        assetFileNames: "app[extname]",
        manualChunks: undefined,
      },
    },
  },
});
Enter fullscreen mode Exit fullscreen mode

2. Cloudflare Pages hosts the bundle. We deploy the dist folder with Wrangler. The domain's DNS did not move. Pages is only a static file host here.

npm run build
npx wrangler pages deploy dist --project-name your-project --branch main
Enter fullscreen mode Exit fullscreen mode

3. WordPress pages load the bundle. Each marketing route (home, about, pricing, tutors, contact) is a blank WordPress page using the Elementor Canvas template, which prints no theme header or footer. The page body is three lines:

<link rel="stylesheet" href="https://your-project.pages.dev/app.css">
<div id="app-root"></div>
<script type="module" src="https://your-project.pages.dev/app.js"></script>
Enter fullscreen mode Exit fullscreen mode

React Router reads the URL and renders the matching page. Because every route is also a real WordPress page, a direct visit or a refresh never returns a 404.

4. React links out for everything else. Register, login, dashboard, course pages and checkout are plain links to the existing WordPress URLs. The "Buy now" buttons add the WooCommerce product to the cart in the background and fall back to the classic /?add-to-cart=ID link if that fails.

5. WordPress pages get the same look. A custom CSS block overrides Tutor LMS and WooCommerce colour variables and fonts. A small script, added through a snippets plugin, draws the same header and footer on WordPress pages. It checks for #app-root and skips pages where React is already running.

6. Launch was a one-setting change. We pointed "front page" in WordPress settings at the new page and left the old homepage untouched. Rolling back meant changing that setting back.

What worked well

  • No migration. Students, enrolments, orders and course content never moved. Nobody had to reset a password.
  • Fast design changes. A homepage change is a build and a deploy that takes under a minute. No theme editor, no page builder.
  • Cheap rollback. Old homepage kept, new one switched on by a setting. Cloudflare Pages also keeps every deployment, so a bad build can be reverted from the dashboard.
  • Payment risk stayed at zero. We did not touch checkout, so we had nothing to retest there.
  • Free hosting for the front end. The static bundle sits on the Pages free tier.

Bottlenecks we hit

Prices lived in two places. The marketing pages had course and bundle prices typed into a data file. Months later the team changed prices in WooCommerce. Checkout charged the new prices while the homepage still advertised the old ones, at half the real amount in some cases. We only noticed when someone asked for a price change that had already been made. Anything the shop owns should be fetched from the shop, or at least checked by a script on every build.

Caching hid our changes. The site uses a page cache plugin. Edits to the WordPress pages or the custom CSS did not show until we purged the cache, and we lost time more than once debugging a change that was already correct. The bundle itself is safer: Pages serves it with must-revalidate, so fixed filenames did not cause stale JavaScript.

We lost track of the deploy account. The Pages project had been created under a different Cloudflare login from the one on the developer's machine. Wrangler also caches an account ID locally, so even after logging in with the right account it kept calling the wrong one until we set CLOUDFLARE_ACCOUNT_ID. Write down which account owns the project on day one.

Two design systems. The React pages and the WordPress pages are styled separately. Every brand change has to be made twice, and plugin updates can undo CSS overrides. Course and checkout pages still look slightly different from the marketing pages.

SEO needs extra work. The marketing content is rendered in the browser. The WordPress page that carries it has an almost empty body, so titles and meta descriptions have to be set per page in WordPress, and we have not finished that. If organic search is your main channel, prerender the pages at build time.

The homepage now depends on a second host. If the Pages URL is unreachable, the homepage is blank. It has not happened to us, but it is a dependency that did not exist before.

It does not fix WordPress. The plugin count, the update backlog and the bot signups on the registration form are all still there. A new front end changes how the site looks, not how much there is to maintain behind it.

What we would tell another team

  1. Draw the line at sessions and money. Rebuild what is public and static. Leave the rest alone until you are ready to replace it properly.
  2. Use fixed output filenames and one mount element. It keeps the WordPress side to three lines of HTML that never change.
  3. Keep the old homepage and switch with a setting. Launch and rollback become the same small action.
  4. Give every fact one owner. Prices, course lists and tutor names should come from WordPress through its REST API, not from a file in the React repo.
  5. Document the deploy: which account, which project, which branch, which command.
  6. Plan the cache purge into every release checklist.
  7. Treat the hybrid as a stage, not the end state. It bought us a modern front end in weeks. It also made clear which parts of WordPress we still want to replace.

Would we do it again?

Yes, for the same situation: a working WordPress back end, a weak front end, a small team and no room for downtime. If we were starting again we would fetch prices from WooCommerce from the first day and prerender the pages for search engines. Those two changes would have removed our two most visible problems.

Top comments (0)