Merge pull request #108 from preactjs/docs/prerender-instructions

docs: Rewrite prerendering instructions

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,