Skip to content

Commit 2f78dc2

Browse files
fezcodefezcode
committed
build(ssg): add build:retry + deploy:fast/retry scripts, update docs
Introduce build:retry (enables --retry flag on the crawler) and matching deploy:fast / deploy:retry shortcuts. Update README to replace stale CRA/react-snap references with the Vite + Vike + crawler pipeline and document the three build variants. Accept --retry as a CLI flag in addition to PRERENDER_RETRY=1.
1 parent 703c097 commit 2f78dc2

3 files changed

Lines changed: 22 additions & 5 deletions

File tree

‎README.md‎

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ Imagine you have a giant digital toy box. Inside, you keep the cool things you'v
2121
- **Frontend**: React 19, Tailwind CSS, and Framer Motion for smooth animations.
2222
- **3D & Graphics**: Three.js and react-force-graph-3d for the knowledge graph.
2323
- **Content**: Markdown and **PIML** (Plain Old Markup Language) for structured content.
24-
- **Build Tools**: Craco (CRA Configuration Override) for custom build pipelines.
24+
- **Build Tools**: Vite + Vike for the SPA build and shell generation; a Puppeteer-based crawler hydrates dynamic routes into static HTML for GitHub Pages.
2525
- **Persistence**: Local Storage for settings, achievements, and persistent state.
2626
- **AI Tooling**: **Model Context Protocol (MCP)** server for automated content management.
2727

@@ -76,13 +76,27 @@ This will open the site at http://localhost:3000.
7676
---
7777

7878
## Routing and SEO
79-
This project uses `BrowserRouter` for clean URLs. To support this on static hosts like GitHub Pages, we use `react-snap` to pre-render routes into static HTML files during the build process.
79+
This project uses `BrowserRouter` for clean URLs. To support this on static hosts like GitHub Pages, the build runs in two passes:
80+
81+
1. **Vite + Vike** produces the JS bundles and writes one empty-shell `index.html` per route listed in `pages/routes.js` plus every dynamic route discovered by `pages/discoverRoutes.js` (blog posts, series episodes, log entries, story book pages — ~460 routes total).
82+
2. **`scripts/prerender-crawl.mjs`** spins up a Vite preview server, loads each shell in headless Chromium, and replaces the empty `#react-root` with the hydrated HTML. Skipped routes fall back to SPA rendering at runtime — not a build failure.
83+
84+
### Build variants
85+
| Command | What it does | When to use |
86+
| --- | --- | --- |
87+
| `npm run build` | Vite build + post-build + full prerender crawl | Default. Produces a fully SSG'd `dist/client/`. |
88+
| `npm run build:fast` | Vite build + post-build only (no crawl) | Fast iteration on components; skip the ~2–5 min crawler. |
89+
| `npm run build:retry` | Full crawl, then re-attempts any routes that missed the render gate | Use when the default build reports many skipped routes (flaky JS/fetch under load). |
90+
91+
Tune the crawler via env vars: `PRERENDER_CONCURRENCY=6` (default `6`), `PRERENDER_RETRY=1` (same as `--retry`).
8092

8193
### Deployment
82-
The standard `npm run deploy` command handles the build, pre-rendering, and deployment to GitHub Pages automatically.
8394
```bash
84-
npm run deploy
95+
npm run deploy # build (full crawl) + push dist/client to gh-pages
96+
npm run deploy:fast # shell-only build + push (skipped routes become SPA-only)
97+
npm run deploy:retry # full crawl with retry pass + push
8598
```
99+
`gh-pages` publishes the contents of `dist/client/` to the `gh-pages` branch of the repo.
86100

87101
### Content Syncing
88102
Stories are managed via git subtrees. Because subtree remotes are not tracked by git, you must initialize the remote once after cloning:

‎package.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,9 @@
5050
"prebuild": "npm run pregenerate",
5151
"build": "vite build && node scripts/post-build.mjs && node scripts/prerender-crawl.mjs",
5252
"build:fast": "vite build && node scripts/post-build.mjs",
53+
"build:retry": "vite build && node scripts/post-build.mjs && node scripts/prerender-crawl.mjs --retry",
54+
"deploy:fast": "npm run build:fast && gh-pages -d dist/client -b gh-pages --no-history",
55+
"deploy:retry": "npm run build:retry && gh-pages -d dist/client -b gh-pages --no-history",
5356
"preview": "vite preview",
5457
"test": "vitest",
5558
"lint": "eslint \"src/**/*.{js,jsx}\" \"scripts/**/*.{js,mjs}\" --fix",

‎scripts/prerender-crawl.mjs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ const CONCURRENCY = Number(process.env.PRERENDER_CONCURRENCY) || 6;
1212
const PAGE_TIMEOUT = 30000;
1313
const RENDER_SETTLE_MS = 300;
1414
const SELECTOR_TIMEOUT = 8000;
15-
const RETRY = process.env.PRERENDER_RETRY === '1';
15+
const RETRY = process.env.PRERENDER_RETRY === '1' || process.argv.includes('--retry');
1616

1717
function routeToFile(route) {
1818
if (route === '/') return join(DIST, 'index.html');

0 commit comments

Comments
 (0)