README.md

@@ -75,19 +75,31 @@ preact({
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `enabled` | `boolean` | `false` | Enables prerendering |
-| `prerenderScript` | `string` | `undefined` | Absolute path to script containing exported `prerender()` function. If not provided, will try to find the prerender script in the scripts listed in your HTML entrypoint |
 | `renderTarget` | `string` | `"body"` | Query selector for where to insert prerender result in your HTML template |
-| `additionalPrerenderRoutes` | `string` | `undefined` | Prerendering will automatically discover links to prerender, but if there are unliked pages that you want to prererender (such as a `/404` page), use this option to specify them |
+| `prerenderScript` | `string` | `undefined` | Absolute path to script containing exported `prerender()` function. If not provided, will try to find the prerender script in the scripts listed in your HTML entrypoint |
+| `additionalPrerenderRoutes` | `string[]` | `undefined` | Prerendering will crawl your site automatically, but you'd like to prerender some pages that may not be found (such as a `/404` page), use this option to specify them |
+
+To prerender your app, you'll need to do these things:
+1. Enable prerendering in the plugin options
+2. Specify your render target, if you want the HTML to be inserted anywhere other than the `document.body`. This location likely should match `render()`, i.e., `render(<App />, document.querySelector('#app'))` -> `'#app'`
+4. Create and export a `prerender()` function from a script. You could add this to your app entrypoint or create a completely separate file for it, either will work. See below for a usage example
+5. Specify where your `prerender()` function is by either a) adding a `prerender` attribute to the script tag that contains it in your entry HTML (`<script prerender src="./my-prerender-script.js">`) or b) use the `prerenderScript` plugin option to specify the location with an absolute path
 
-To prerender your app, you'll need to set `prerender.enabled` to `true` in the plugin options (`vite.config.js`), export a `prerender()` function one of the scripts listed in your HTML entry point (or the script specified through `prerender.prerenderScript`), and add a `prerender` attribute to that script tag in your HTML entry point (`<script prerender src="...">`). How precisely you generate an HTML string from your app is up to you, but you'll likely want to use [`preact-render-to-string`](https://github.com/preactjs/preact-render-to-string) or a wrapper around it such as [`preact-iso`'s `prerender`](https://github.com/preactjs/preact-iso). Whatever you choose, you simply need to return an object from your `prerender()` function containing an `html` property with your HTML string.
+The plugin simply calls the prerender function you provide so it's up to you to determine how your app should be prerendered. You'll likely want to use [`preact-render-to-string`](https://github.com/preactjs/preact-render-to-string), or a wrapper around it such as [`preact-iso`'s `prerender`](https://github.com/preactjs/preact-iso), but whatever you choose, the minimum you'll need to return is an object containing an `html` property with your HTML string which will then be inserted according to your `renderTarget`.
 
-[For an example implementation, see our demo](./demo/src/index.tsx)
+Your `prerender()` function can be asynchronous, so feel free to make HTTP requests to retrieve data (`fetch(...)`), read files from disk (`fs.readFile(...)`), or similar things to set up your app.
+
+[For a full example implementation, see our demo](./demo/src/index.tsx)
 
 ```js
-import { render } from 'preact-render-to-string';
+import { prerender as ssr } from 'preact-iso';
+
+function App() {
+    return <h1>Hello World!</h1>
+}
 
 export async function prerender(data) {
-    const html = render(`<h1>hello world</h1>`);
+    const html = ssr(<App />);
 
     return {
         html,

demo/package.json

@@ -0,0 +1,3 @@
+{
+	"type": "module"
+}

demo/src/components/LocalFetch.tsx

@@ -4,7 +4,8 @@ const cache = new Map();
 
 async function load(url: string) {
 	const res = await fetch(url);
-	return await res.text();
+	if (res.ok) return await res.text();
+	throw new Error(`Failed to fetch ${url}!`);
 }
 
 function useFetch(url: string) {

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@preact/preset-vite",
-	"version": "2.8.1",
+	"version": "2.8.2",
 	"description": "Preact preset for the vite bundler",
 	"main": "./dist/cjs/index.js",
 	"module": "./dist/esm/index.mjs",
@@ -42,19 +42,23 @@
 		"kolorist": "^1.8.0",
 		"magic-string": "0.30.5",
 		"node-html-parser": "^6.1.10",
-		"resolve": "^1.22.8"
+		"resolve": "^1.22.8",
+		"source-map": "^0.7.4",
+		"stack-trace": "^1.0.0-pre2"
 	},
 	"peerDependencies": {
 		"@babel/core": "7.x",
 		"vite": "2.x || 3.x || 4.x || 5.x"
 	},
 	"devDependencies": {
 		"@babel/core": "^7.15.8",
+		"@types/babel__code-frame": "^7.0.6",
 		"@types/babel__core": "^7.1.14",
 		"@types/debug": "^4.1.5",
 		"@types/estree": "^0.0.50",
 		"@types/node": "^14.14.33",
 		"@types/resolve": "^1.20.1",
+		"@types/stack-trace": "^0.0.33",
 		"lint-staged": "^10.5.4",
 		"preact": "^10.19.2",
 		"preact-iso": "^2.3.2",