@mate-academy/lovable-build-tools

SSR pre-rendering and WebP conversion CLI for Lovable (Vite + React) landing pages.

Part of the Generated Landings Infrastructure.

What it does

1. SSR pre-render — builds an SSR bundle of your app with Vite, calls ReactDOMServer.renderToString for each route, and writes a static index.html per route. React effects (useEffect, useLayoutEffect) don't run during SSR, so the HTML matches React's initial client render exactly — no hydration mismatches.
2. WebP conversion — converts raster assets in dist/ to WebP via Sharp and rewrites references in HTML and JS bundles.

Usage

1. Split App.tsx and add the SSR entry

Refactor src/App.tsx so the providers tree and the routes tree are separable, then create src/entry-server.tsx that calls renderToString against <StaticRouter>. The consumer src/main.tsx must also switch to hydrateRoot when pre-rendered HTML is present.

See docs/LovableProjectSetupGuide.md (sections 1.3–1.5) for the canonical code.

2. Declare routes

prerender.config.mjs:

export default {
  routes: ["/", "/apply", "/privacy-policy"],
  // Optional:
  // generate404: true,                         // default true — writes dist/404.html
  // entryServerPath: "src/entry-server.tsx",   // default
};

3. Wire up the build script

package.json:

{
  "scripts": {
    "build:prerender": "vite build && mate-prerender"
  },
  "devDependencies": {
    "@mate-academy/lovable-build-tools": "^2.0.0"
  }
}

Pre-requisites in the consumer project

• All <img> tags need explicit sizing (e.g. width/height attrs, fixed dimensions, or Tailwind aspect-[W/H]). SSR cannot measure natural dimensions; CLS relies on CSS.
• Components must be SSR-safe: no window / document / localStorage at render time — always wrapped in useEffect or guarded with typeof window !== "undefined".
• Above-the-fold components must not use React.lazy + <Suspense>. SSR emits the fallback and the client re-renders the subtree (React error #419). Import eagerly instead.

Migration from 1.x

Breaking changes in 2.0.0:

• prerender() now uses renderToString instead of Puppeteer. The package no longer depends on puppeteer (install size roughly halves).
• The consumer project must provide src/entry-server.tsx (see above).
• vite is now a peer dependency — ensure the consumer has it installed (every Lovable project does).
• waitForSelector option is removed from prerender.config.mjs (meaningless without a browser).
• The CLI now runs prerender() before convertToWebP() (reversed from 1.x). The combined behavior is unchanged end-to-end.

Rollback: pin @mate-academy/[email protected] — that version keeps the Puppeteer path. No dual path is maintained going forward.