feat: types for prerender options and result; better result checks

Author: crutch12

src/plugins/prerender-plugin.js

@@ -134,7 +134,7 @@ export function prerenderPlugin({ prerenderScript, renderTarget, additionalPrere
             // Only required for Vite 5 and older. In 6+, this is handled by the
             // Environment API (`applyToEnvironment`)
             if (config.build?.ssr) {
-                ssrBuild = true
+                ssrBuild = true;
                 return;
             }
 
@@ -319,10 +319,7 @@ export function prerenderPlugin({ prerenderScript, renderTarget, additionalPrere
 
                 const assetPath = path.join(tmpDir, output);
                 await fs.mkdir(path.dirname(assetPath), { recursive: true });
-                await fs.writeFile(
-                    assetPath,
-                    /** @type {OutputChunk} */ (bundle[output]).code,
-                );
+                await fs.writeFile(assetPath, /** @type {OutputChunk} */ (bundle[output]).code);
 
                 if (/** @type {OutputChunk} */ (bundle[output]).exports?.includes('prerender')) {
                     prerenderEntry = /** @type {OutputChunk} */ (bundle[output]);
@@ -348,9 +345,7 @@ export function prerenderPlugin({ prerenderScript, renderTarget, additionalPrere
                         // do something in browsers only
                     }`.replace(/^ {20}/gm, '');
 
-                const stack = StackTraceParse(e).find((s) =>
-                    s.getFileName()?.includes(tmpDirId),
-                );
+                const stack = StackTraceParse(e).find((s) => s.getFileName()?.includes(tmpDirId));
 
                 const sourceMapContent = prerenderEntry.map;
                 if (stack && sourceMapContent) {
@@ -382,14 +377,12 @@ export function prerenderPlugin({ prerenderScript, renderTarget, additionalPrere
                 return message;
             };
 
-            /** @type {import('./types.d.ts').Head} */
+            /** @type {Partial<import('./types.d.ts').Head>} */
             let head = { lang: '', title: '', elements: new Set() };
 
             let prerender;
             try {
-                const m = await import(
-                    `file://${path.join(tmpDir, prerenderEntry.fileName)}`
-                );
+                const m = await import(`file://${path.join(tmpDir, prerenderEntry.fileName)}`);
                 prerender = m.prerender;
             } catch (e) {
                 const message = await handlePrerenderError(e);
@@ -420,9 +413,12 @@ export function prerenderPlugin({ prerenderScript, renderTarget, additionalPrere
                     } catch {}
                 }
 
+                /** @type {import('./types.d.ts').PrerenderResult | string} */
                 let result;
                 try {
-                    result = await prerender({ ssr: true, url: route.url, route });
+                    /** @type {import('./types.d.ts').PrerenderOptions} */
+                    const options = { ssr: true, url: route.url, route };
+                    result = await prerender(options);
                 } catch (e) {
                     const message = await handlePrerenderError(e);
                     this.error(message);
@@ -438,7 +434,7 @@ export function prerenderPlugin({ prerenderScript, renderTarget, additionalPrere
                 head = { lang: '', title: '', elements: new Set() };
 
                 // Add any discovered links to the list of routes to pre-render:
-                if (result.links) {
+                if (typeof result === 'object' && result.links) {
                     for (let url of result.links) {
                         const parsed = new URL(url, 'http://localhost');
                         url = parsed.pathname.replace(/\/$/, '') || '/';
@@ -494,16 +490,16 @@ export function prerenderPlugin({ prerenderScript, renderTarget, additionalPrere
                 const target = htmlDoc.querySelector(renderTarget);
                 if (!target)
                     this.error(
-                        result.renderTarget == 'body'
+                        renderTarget == 'body'
                             ? '`renderTarget` was not specified in plugin options and <body> does not exist in input HTML template'
-                            : `Unable to detect prerender renderTarget "${result.selector}" in input HTML template`,
+                            : `Unable to detect prerender renderTarget "${renderTarget}" in input HTML template`,
                     );
                 target.insertAdjacentHTML('afterbegin', body);
 
+                const index = /** @type {OutputAsset} */ (bundle['index.html']);
                 // Add generated HTML to compilation:
                 route.url == '/'
-                    ? (/** @type {OutputAsset} */ (bundle['index.html']).source =
-                          htmlDoc.toString())
+                    ? (index.source = htmlDoc.toString())
                     : this.emitFile({
                           type: 'asset',
                           fileName: assetName,
@@ -531,6 +527,6 @@ export function prerenderPlugin({ prerenderScript, renderTarget, additionalPrere
                     }
                 }
             }
-        }
+        },
     };
 }

src/plugins/types.d.ts

@@ -14,3 +14,19 @@ export interface PrerenderedRoute {
     url: string;
     _discoveredBy?: PrerenderedRoute;
 }
+
+export interface PrerenderOptions {
+    ssr: true;
+    url: string;
+    route: PrerenderedRoute;
+}
+
+export interface PrerenderResult {
+    html?: string;
+    head?: Partial<Head>;
+    links?: Set<string>;
+    /**
+     * @description Caution: this value is stringified via JSON.stringify
+     */
+    data?: any;
+}