[Content]: Prerender recipe bakes `Loading` fallbacks into static HTML unless `renderMode: "async"` is set

Offen Anfängerfreundlich
#1,713 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
2/5
Geschätzter Aufwand
1-3 Stunden
Anfängerfreundlichkeit
78/100
Issue-Typ
Dokumentation
Klarheit
Klar beschrieben
Aktivitätsstatus
Aktiv
Tech-Stack
typescript
Bereich
documentation

Rechercherichtung

Lies den Abschnitt „Prerendered at build time“ im Rendering-Modus-Leitfaden und den Typ renderMode in der Referenz zum Vite-Plugin. Aktualisiere das Prerender-Rezept so, dass es renderMode: "async" verwendet, und erkläre, warum sich das auf statisches HTML auswirkt, wenn Daten noch geladen werden. Fertig ist es, wenn das Rezept und die Erklärung das im Issue beschriebene Verhalten widerspiegeln.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

📚 Subject area/topic

Guides (Choose a rendering mode)

📋 Page(s) affected (or suggested, for new content)

https://docs.solidjs.com/guides/choose-a-rendering-mode (section "Prerendered at build time")

Related: https://docs.solidjs.com/reference/vite-plugin-solid/start lists renderMode?: "stream" | "async" in its type but has no section for it.

📋 Description of content that is out-of-date or incorrect

The prerender recipe configures solid({ start: true, ssr: true, serverFunctions: true }), so pages are prerendered with the default renderMode: "stream". The guide then says "What the user sees first is the complete page, as with SSR."

That only holds when a page's data settles before the shell is ready. When the data is still loading at that point, the static file is written with the Loading fallback in place and the content in a <template> plus a swap script. A crawler or a browser with scripts disabled sees the fallback instead of the content. With start: { renderMode: "async" } the same file contains the content and no fallback.

The @solidjs/vite-plugin README describes this under renderMode ("a client that never runs JavaScript — a crawler, curl, a browser with scripts disabled — is left looking at the fallbacks forever", solidjs/solid#3280), but the docs site doesn't.

Measured on solid-js / @solidjs/web 2.0.3, @solidjs/vite-plugin 3.0.1, prerender-crawler 0.3.0, vite 8.3.8, Node 24.21.0:

start.renderMode visible text of dist/client/users/1/index.html without JS <template id="pl-…">
default ("stream") Home Users Loading… 1
"async" Home Users Users Ada Lovelace First programmer Next user 0

Proposed fix: set renderMode: "async" in the recipe and add a few lines explaining why. I have a PR ready.

A possible alternative in code: the crawl could ask for a complete document per call (start mode's handleRequest(request, { renderMode: 'async' }) already supports that), but the crawler calls the handler with the request only today.

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

Steps (local, not StackBlitz):

  1. pnpm create solid@latest -t basic --solid --ts --ssr --no-devtools, then pnpm add -D prerender-crawler. (With create-solid 0.13.0 you also need to rename the generated start: { node: true } to nodeServer: true.)
  2. In vite.config.ts, add prerender({ mode: 'static', pages: ['/users/1'], crawlLinks: false }) from prerender-crawler/vite.
  3. In src/routes/users/[id].tsx, add await new Promise((r) => setTimeout(r, 50)); at the top of getUser, standing in for a real fetch.
  4. pnpm build and open dist/client/users/1/index.html with JavaScript disabled: it shows "Loading…".
  5. Add renderMode: 'async' to start and build again: the user's name and title are in the HTML.
Vorherrschende Sprache
MDX
Sterne
291
Forks
369
Ø Merge
1 T. 1 Std.
Gemergte PRs (30 T.)
39

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus solidjs/solid-docs

Alle Issues in solidjs/solid-docs

Ähnliche Issues

Weitere Issues zu Documentation

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.