Getting Started

Set up ReviJs in your existing project in under 30 seconds.

Requirements

• Node.js v18.0.0 or higher
• npm v9+ (or yarn / pnpm)
• A React, Vite, Vue, or Svelte SPA with a dist/ build output
• macOS, Linux, or Windows

Step 1 — Install

Install ReviJs. Playwright Chromium installs automatically — nothing extra needed.

npm install @revijs/core

Step 2 — Create config

Auto-generate a config file:

npx revijs init

Or create revi.config.js manually:

export default {
  routes: ['/', '/about', '/blog/post-1'],
  engine: 'browser',
  outputDir: 'dist-prerendered',
  distDir: 'dist',
  waitFor: 1200,
  headless: true,
};

Step 3 — Build your app

npm run build

Step 4 — Prerender

npx revijs

Expected output:

  ⚡ ReviJs — SPA Prerenderer

  Rendering / ... ✔
  Rendering /about ... ✔
  Rendering /blog/post-1 ... ✔

  3 rendered → dist-prerendered/

Output structure

Each route maps to a nested index.html:

/             → dist-prerendered/index.html
/about        → dist-prerendered/about/index.html
/blog/post-1  → dist-prerendered/blog/post-1/index.html

Configuration

All options for revi.config.js. Run npx revijs init to generate one automatically.

Full example

export default {
  routes: ['/', '/about', '/blog/post-1'],
  engine: 'browser',
  outputDir: 'dist-prerendered',
  distDir: 'dist',
  waitFor: 1200,
  headless: true,
  port: 4173,
  debug: false,
};

Options

Rendering engines

browser (default)

Standard headless Chromium. Works for 99% of React/Vite apps. Navigates to each route, waits for network idle, captures the DOM. Use this unless you have a specific reason not to.

advanced

Like browser, but also simulates page scroll to trigger lazy-loaded components. Also injects a <meta name="x-prerendered-by" content="revijs"> tag. Use this if your components only load when scrolled into view.

ssr

Minimal-wait mode for apps that already do server-side rendering. Skips the waitFor delay since content is already in the initial HTML.

CLI flags

Programmatic API

Use ReviJs in your own Node.js scripts instead of the CLI. Useful for custom build pipelines and CI workflows.

prerender()

The main entry point. Renders all routes and writes static HTML to disk. Equivalent of running npx revijs.

import { prerender } from '@revijs/core';

await prerender({
  routes: ['/', '/about', '/contact'],
  outputDir: 'dist-prerendered',
  distDir: 'dist',
  engine: 'browser',
  waitFor: 1500,
});

renderAllPages()

Lower-level function. Accepts a fully resolved config, starts the server, boots the engine, renders all routes, tears down.

import { renderAllPages, loadConfig } from '@revijs/core';

const config = await loadConfig('revi.config.js');
await renderAllPages(config);

loadConfig()

Loads and validates revi.config.js, merges with defaults. Returns a fully resolved config object.

import { loadConfig } from '@revijs/core';

const config = await loadConfig('revi.config.js', {
  debug: true,
});

isBot() / detectBot()

Check if a user-agent string belongs to a known bot. Used internally by the middleware.

import { isBot, detectBot } from '@revijs/core';

isBot('Googlebot/2.1');     // true
isBot('Mozilla/5.0 ...');  // false
detectBot('GPTBot/1.0');    // 'gptbot'

saveHTML()

Maps a route path to a file and writes the HTML string to disk.

import { saveHTML } from '@revijs/core';

// /about → dist-prerendered/about/index.html
await saveHTML('/about', htmlString, 'dist-prerendered');

Middleware

Optional middleware that serves prerendered HTML to bots while passing all other requests through normally. Works with Express, Polka, and any Connect-compatible framework.

How it works

1. A request comes in
2. Middleware checks the User-Agent header against 30+ known bot patterns
3. If it's a bot → reads the matching file from dist-prerendered/ and returns it
4. If it's a human → calls next() and your app handles it normally

Express

import express from 'express';
import { createMiddleware } from '@revijs/core';

const app = express();

// register BEFORE your static/SPA handler
app.use(createMiddleware({
  prerenderedDir: 'dist-prerendered',
  debug: false,
}));

app.use(express.static('dist'));
app.listen(3000);

Polka

import polka from 'polka';
import sirv from 'sirv';
import { createMiddleware } from '@revijs/core';

polka()
  .use(createMiddleware({ prerenderedDir: 'dist-prerendered' }))
  .use(sirv('dist', { single: true }))
  .listen(3000);

Options

Supported bots

Examples

Real-world configs for common use cases. Copy and adjust for your project.

Blog / Content site

export default {
  routes: ['/', '/blog', '/blog/hello-world', '/blog/react-tips', '/about'],
  engine: 'browser',
  waitFor: 2000, // extra time for content to load
};

E-Commerce

export default {
  routes: ['/', '/products', '/products/sneaker-x1', '/categories/shoes'],
  // skip /cart /checkout /account — auth-protected routes
  engine: 'browser',
  waitFor: 1500,
};

SaaS landing page

export default {
  routes: ['/', '/pricing', '/features', '/changelog'],
  // /app/* and /dashboard/* intentionally skipped
  waitFor: 1200,
};

Automate with npm scripts

// package.json
{
  "scripts": {
    "build": "vite build",
    "prerender": "npm run build && npx revijs",
    "deploy": "npm run prerender && netlify deploy --dir=dist-prerendered"
  }
}

Adjusting waitFor

If content isn't appearing in the prerendered HTML, your app needs more time. Increase waitFor:

waitFor: 1200,  // fast APIs
waitFor: 3000,  // slow APIs or heavy data
waitFor: 5000,  // very slow — use sparingly

Debugging a route

Set headless: false to watch the browser open and --debug for verbose logs:

export default {
  headless: false,  // opens a visible browser window
  routes: ['/problem-route'],
  waitFor: 3000,
};

npx revijs --debug