From fcb442a9d7ce8c9e30d170062bfed351a521c399 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Wed, 3 May 2023 23:22:19 -0400 Subject: [PATCH] add docs --- .../docs/20-core-concepts/40-page-options.md | 35 +++++++++++++++++-- .../src/lib/docs/server/index.js | 3 +- 2 files changed, 35 insertions(+), 3 deletions(-) diff --git a/documentation/docs/20-core-concepts/40-page-options.md b/documentation/docs/20-core-concepts/40-page-options.md index 91f72d662a70..5804fea5df44 100644 --- a/documentation/docs/20-core-concepts/40-page-options.md +++ b/documentation/docs/20-core-concepts/40-page-options.md @@ -33,7 +33,7 @@ export const prerender = 'auto'; > If your entire app is suitable for prerendering, you can use [`adapter-static`](https://github.com/sveltejs/kit/tree/master/packages/adapter-static), which will output files suitable for use with any static webserver. -The prerenderer will start at the root of your app and generate files for any prerenderable pages or `+server.js` routes it finds. Each page is scanned for `` elements that point to other pages that are candidates for prerendering — because of this, you generally don't need to specify which pages should be accessed. If you _do_ need to specify which pages should be accessed by the prerenderer, you can do so with the `entries` option in the [prerender configuration](configuration#prerender), or by exporting an entry generator from your dynamic route. +The prerenderer will start at the root of your app and generate files for any prerenderable pages or `+server.js` routes it finds. Each page is scanned for `` elements that point to other pages that are candidates for prerendering — because of this, you generally don't need to specify which pages should be accessed. If you _do_ need to specify which pages should be accessed by the prerenderer, you can do so with [`config.kit.prerender.entries`](configuration#prerender), or by exporting an [`entries`](#entries) function from your dynamic route. While prerendering, the value of `building` imported from [`$app/environment`](modules#$app-environment) will be `true`. @@ -84,9 +84,40 @@ If you encounter an error like 'The following routes were marked as prerenderabl Since these routes cannot be dynamically server-rendered, this will cause errors when people try to access the route in question. There are two ways to fix it: -* Ensure that SvelteKit can find the route by following links from [`config.kit.prerender.entries`](configuration#prerender). Add links to dynamic routes (i.e. pages with `[parameters]` ) to this option if they are not found through crawling the other entry points, else they are not prerendered because SvelteKit doesn't know what value the parameters should have. Pages not marked as prerenderable will be ignored and their links to other pages will not be crawled, even if some of them would be prerenderable. +* Ensure that SvelteKit can find the route by following links from [`config.kit.prerender.entries`](configuration#prerender) or the [`entries`](#entries) page option. Add links to dynamic routes (i.e. pages with `[parameters]` ) to this option if they are not found through crawling the other entry points, else they are not prerendered because SvelteKit doesn't know what value the parameters should have. Pages not marked as prerenderable will be ignored and their links to other pages will not be crawled, even if some of them would be prerenderable. * Change `export const prerender = true` to `export const prerender = 'auto'`. Routes with `'auto'` can be dynamically server rendered +## entries + +SvelteKit will discover pages to prerender automatically, by starting at _entry points_ and crawling them. By default, all your non-dynamic routes are considered entry points — for example, if you have these routes... + +```bash +/ # non-dynamic +/blog # non-dynamic +/blog/[slug] # dynamic, because of `[slug]` +``` + +...SvelteKit will prerender `/` and `/blog`, and in the process discover links like `` which give it new pages to prerender. + +Most of the time, that's enough. In some situations, links to pages like `/blog/hello-world` might not exist (or might not exist on prerendered pages), in which case we need to tell SvelteKit about their existence. + +This can be done with [`config.kit.prerender.entries`](configuration#prerender), or by exporting an `entries` function from a `+page.js` or `+page.server.js` belonging to a dynamic route: + +```js +/// file: src/routes/blog/[slug]/+page.server.js +/** @type {import('./$types').EntryGenerator} */ +export function entries() { + return [ + { slug: 'hello-world' }, + { slug: 'another-blog-post' } + ]; +} + +export const prerender = true; +``` + +`entries` can be an `async` function, allowing you to (for example) retrieve a list of posts from a CMS or database, in the example above. + ## ssr Normally, SvelteKit renders your page on the server first and sends that HTML to the client where it's [hydrated](glossary#hydration). If you set `ssr` to `false`, it renders an empty 'shell' page instead. This is useful if your page is unable to be rendered on the server (because you use browser-only globals like `document` for example), but in most situations it's not recommended ([see appendix](glossary#ssr)). diff --git a/sites/kit.svelte.dev/src/lib/docs/server/index.js b/sites/kit.svelte.dev/src/lib/docs/server/index.js index a3f69404a173..26d49e6671bc 100644 --- a/sites/kit.svelte.dev/src/lib/docs/server/index.js +++ b/sites/kit.svelte.dev/src/lib/docs/server/index.js @@ -179,7 +179,8 @@ export async function read_file(file) { `export type LayoutServerLoad = Kit.ServerLoad<{${params}}>;`, `export type RequestHandler = Kit.RequestHandler<{${params}}>;`, `export type Action = Kit.Action<{${params}}>;`, - `export type Actions = Kit.Actions<{${params}}>;` + `export type Actions = Kit.Actions<{${params}}>;`, + `export type EntryGenerator = () => Promise> | Array<{${params}}>;` ); }