From f6655aed612843be328c4233b4519e3b8da6fa3f Mon Sep 17 00:00:00 2001 From: Nic Polumeyv <162764842+Nic-Polumeyv@users.noreply.github.com> Date: Fri, 10 Jul 2026 06:00:17 -0400 Subject: [PATCH 1/4] docs: clarify that preloads are sent as a `Link` header on dynamically rendered pages --- documentation/docs/30-advanced/20-hooks.md | 2 +- packages/kit/src/exports/public.d.ts | 3 ++- packages/kit/types/index.d.ts | 3 ++- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/documentation/docs/30-advanced/20-hooks.md b/documentation/docs/30-advanced/20-hooks.md index 177569c4d8f8..e682b8ae5d9b 100644 --- a/documentation/docs/30-advanced/20-hooks.md +++ b/documentation/docs/30-advanced/20-hooks.md @@ -86,7 +86,7 @@ You can define multiple `handle` functions and execute them with [the `sequence` - `transformPageChunk(opts: { html: string, done: boolean }): MaybePromise` — applies custom transforms to HTML. If `done` is true, it's the final chunk. Chunks are not guaranteed to be well-formed HTML (they could include an element's opening tag but not its closing tag, for example) but they will always be split at sensible boundaries such as `%sveltekit.head%` or layout/page components. - `filterSerializedResponseHeaders(name: string, value: string): boolean` — determines which headers should be included in serialized responses when a `load` function loads a resource with `fetch`. By default, none will be included. -- `preload(input: { type: 'js' | 'css' | 'font' | 'asset', path: string }): boolean` — determines what files should be added to the `` tag to preload it. The method is called with each file that was found at build time while constructing the code chunks — so if you for example have `import './styles.css` in your `+page.svelte`, `preload` will be called with the resolved path to that CSS file when visiting that page. Note that in dev mode `preload` is _not_ called, since it depends on analysis that happens at build time. Preloading can improve performance by downloading assets sooner, but it can also hurt if too much is downloaded unnecessarily. By default, `js` and `css` files will be preloaded. `asset` files are not preloaded at all currently, but we may add this later after evaluating feedback. +- `preload(input: { type: 'js' | 'css' | 'font' | 'asset', path: string }): boolean` — determines which files should be preloaded. When a page is rendered dynamically, files are preloaded via the [`Link` response header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Link); prerendered pages get `` tags in their `` instead. The method is called with each file that was found at build time while constructing the code chunks — so if you for example have `import './styles.css` in your `+page.svelte`, `preload` will be called with the resolved path to that CSS file when visiting that page. Note that in dev mode `preload` is _not_ called, since it depends on analysis that happens at build time. Preloading can improve performance by downloading assets sooner, but it can also hurt if too much is downloaded unnecessarily. By default, `js` and `css` files will be preloaded. `asset` files are not preloaded at all currently, but we may add this later after evaluating feedback. ```js /// file: src/hooks.server.js diff --git a/packages/kit/src/exports/public.d.ts b/packages/kit/src/exports/public.d.ts index 450da13f7674..38ab405530e7 100644 --- a/packages/kit/src/exports/public.d.ts +++ b/packages/kit/src/exports/public.d.ts @@ -1734,7 +1734,8 @@ export interface ResolveOptions { */ filterSerializedResponseHeaders?: (name: string, value: string) => boolean; /** - * Determines what should be added to the `` tag to preload it. + * Determines which files should be preloaded, via the `Link` response header for dynamically rendered pages + * or `` tags in the `` for prerendered pages. * By default, `js` and `css` files will be preloaded. * @param input the type of the file and its path */ diff --git a/packages/kit/types/index.d.ts b/packages/kit/types/index.d.ts index af5f78f382f3..27380f882ba6 100644 --- a/packages/kit/types/index.d.ts +++ b/packages/kit/types/index.d.ts @@ -1704,7 +1704,8 @@ declare module '@sveltejs/kit' { */ filterSerializedResponseHeaders?: (name: string, value: string) => boolean; /** - * Determines what should be added to the `` tag to preload it. + * Determines which files should be preloaded, via the `Link` response header for dynamically rendered pages + * or `` tags in the `` for prerendered pages. * By default, `js` and `css` files will be preloaded. * @param input the type of the file and its path */ From ddf1d7a6e154614f5bf2fc874b2d6f918d057e37 Mon Sep 17 00:00:00 2001 From: Nic Polumeyv Date: Fri, 10 Jul 2026 15:07:48 -0400 Subject: [PATCH 2/4] Apply suggestion from @teemingc Co-authored-by: Tee Ming --- documentation/docs/30-advanced/20-hooks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/docs/30-advanced/20-hooks.md b/documentation/docs/30-advanced/20-hooks.md index e682b8ae5d9b..ef630124c93f 100644 --- a/documentation/docs/30-advanced/20-hooks.md +++ b/documentation/docs/30-advanced/20-hooks.md @@ -86,7 +86,7 @@ You can define multiple `handle` functions and execute them with [the `sequence` - `transformPageChunk(opts: { html: string, done: boolean }): MaybePromise` — applies custom transforms to HTML. If `done` is true, it's the final chunk. Chunks are not guaranteed to be well-formed HTML (they could include an element's opening tag but not its closing tag, for example) but they will always be split at sensible boundaries such as `%sveltekit.head%` or layout/page components. - `filterSerializedResponseHeaders(name: string, value: string): boolean` — determines which headers should be included in serialized responses when a `load` function loads a resource with `fetch`. By default, none will be included. -- `preload(input: { type: 'js' | 'css' | 'font' | 'asset', path: string }): boolean` — determines which files should be preloaded. When a page is rendered dynamically, files are preloaded via the [`Link` response header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Link); prerendered pages get `` tags in their `` instead. The method is called with each file that was found at build time while constructing the code chunks — so if you for example have `import './styles.css` in your `+page.svelte`, `preload` will be called with the resolved path to that CSS file when visiting that page. Note that in dev mode `preload` is _not_ called, since it depends on analysis that happens at build time. Preloading can improve performance by downloading assets sooner, but it can also hurt if too much is downloaded unnecessarily. By default, `js` and `css` files will be preloaded. `asset` files are not preloaded at all currently, but we may add this later after evaluating feedback. +- `preload(input: { type: 'js' | 'css' | 'font' | 'asset', path: string }): boolean` — determines which files should be preloaded. When a page is rendered dynamically, files are preloaded via the [`Link` response header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Link); prerendered pages have `` tags added to the `` tag instead. The method is called with each file that was found at build time while constructing the code chunks — so if you for example have `import './styles.css` in your `+page.svelte`, `preload` will be called with the resolved path to that CSS file when visiting that page. Note that in dev mode `preload` is _not_ called, since it depends on analysis that happens at build time. Preloading can improve performance by downloading assets sooner, but it can also hurt if too much is downloaded unnecessarily. By default, `js` and `css` files will be preloaded. `asset` files are not preloaded at all currently, but we may add this later after evaluating feedback. ```js /// file: src/hooks.server.js From 0d3a6c4dcccbf28cb40a0851cfdc1a7eccf3900e Mon Sep 17 00:00:00 2001 From: Nic Polumeyv <162764842+Nic-Polumeyv@users.noreply.github.com> Date: Fri, 10 Jul 2026 15:10:25 -0400 Subject: [PATCH 3/4] docs: match the preload wording in the type declarations --- packages/kit/src/exports/public.d.ts | 5 +++-- packages/kit/types/index.d.ts | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/packages/kit/src/exports/public.d.ts b/packages/kit/src/exports/public.d.ts index 38ab405530e7..0609ad49e77e 100644 --- a/packages/kit/src/exports/public.d.ts +++ b/packages/kit/src/exports/public.d.ts @@ -1734,8 +1734,9 @@ export interface ResolveOptions { */ filterSerializedResponseHeaders?: (name: string, value: string) => boolean; /** - * Determines which files should be preloaded, via the `Link` response header for dynamically rendered pages - * or `` tags in the `` for prerendered pages. + * Determines which files should be preloaded. When a page is rendered dynamically, files are preloaded + * via the [`Link` response header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Link); + * prerendered pages have `` tags added to the `` tag instead. * By default, `js` and `css` files will be preloaded. * @param input the type of the file and its path */ diff --git a/packages/kit/types/index.d.ts b/packages/kit/types/index.d.ts index 27380f882ba6..ed57f54a6248 100644 --- a/packages/kit/types/index.d.ts +++ b/packages/kit/types/index.d.ts @@ -1704,8 +1704,9 @@ declare module '@sveltejs/kit' { */ filterSerializedResponseHeaders?: (name: string, value: string) => boolean; /** - * Determines which files should be preloaded, via the `Link` response header for dynamically rendered pages - * or `` tags in the `` for prerendered pages. + * Determines which files should be preloaded. When a page is rendered dynamically, files are preloaded + * via the [`Link` response header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Link); + * prerendered pages have `` tags added to the `` tag instead. * By default, `js` and `css` files will be preloaded. * @param input the type of the file and its path */ From b54c7165e7692b619376cb6069776cfb44d83043 Mon Sep 17 00:00:00 2001 From: Nic Polumeyv <162764842+Nic-Polumeyv@users.noreply.github.com> Date: Mon, 13 Jul 2026 15:49:18 -0400 Subject: [PATCH 4/4] docs: describe the Link header as opt-in via output.linkHeaderPreload --- documentation/docs/30-advanced/20-hooks.md | 2 +- packages/kit/src/exports/public.d.ts | 6 +++--- packages/kit/types/index.d.ts | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/documentation/docs/30-advanced/20-hooks.md b/documentation/docs/30-advanced/20-hooks.md index ef630124c93f..176cd06a1ddd 100644 --- a/documentation/docs/30-advanced/20-hooks.md +++ b/documentation/docs/30-advanced/20-hooks.md @@ -86,7 +86,7 @@ You can define multiple `handle` functions and execute them with [the `sequence` - `transformPageChunk(opts: { html: string, done: boolean }): MaybePromise` — applies custom transforms to HTML. If `done` is true, it's the final chunk. Chunks are not guaranteed to be well-formed HTML (they could include an element's opening tag but not its closing tag, for example) but they will always be split at sensible boundaries such as `%sveltekit.head%` or layout/page components. - `filterSerializedResponseHeaders(name: string, value: string): boolean` — determines which headers should be included in serialized responses when a `load` function loads a resource with `fetch`. By default, none will be included. -- `preload(input: { type: 'js' | 'css' | 'font' | 'asset', path: string }): boolean` — determines which files should be preloaded. When a page is rendered dynamically, files are preloaded via the [`Link` response header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Link); prerendered pages have `` tags added to the `` tag instead. The method is called with each file that was found at build time while constructing the code chunks — so if you for example have `import './styles.css` in your `+page.svelte`, `preload` will be called with the resolved path to that CSS file when visiting that page. Note that in dev mode `preload` is _not_ called, since it depends on analysis that happens at build time. Preloading can improve performance by downloading assets sooner, but it can also hurt if too much is downloaded unnecessarily. By default, `js` and `css` files will be preloaded. `asset` files are not preloaded at all currently, but we may add this later after evaluating feedback. +- `preload(input: { type: 'js' | 'css' | 'font' | 'asset', path: string }): boolean` — determines which files should be preloaded. Files are preloaded via `` tags added to the `` tag; if [`output.linkHeaderPreload`](configuration#output) is enabled, dynamically rendered pages use the [`Link` response header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Link) instead. The method is called with each file that was found at build time while constructing the code chunks — so if you for example have `import './styles.css` in your `+page.svelte`, `preload` will be called with the resolved path to that CSS file when visiting that page. Note that in dev mode `preload` is _not_ called, since it depends on analysis that happens at build time. Preloading can improve performance by downloading assets sooner, but it can also hurt if too much is downloaded unnecessarily. By default, `js` and `css` files will be preloaded. `asset` files are not preloaded at all currently, but we may add this later after evaluating feedback. ```js /// file: src/hooks.server.js diff --git a/packages/kit/src/exports/public.d.ts b/packages/kit/src/exports/public.d.ts index 0609ad49e77e..cab6332bac14 100644 --- a/packages/kit/src/exports/public.d.ts +++ b/packages/kit/src/exports/public.d.ts @@ -1734,9 +1734,9 @@ export interface ResolveOptions { */ filterSerializedResponseHeaders?: (name: string, value: string) => boolean; /** - * Determines which files should be preloaded. When a page is rendered dynamically, files are preloaded - * via the [`Link` response header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Link); - * prerendered pages have `` tags added to the `` tag instead. + * Determines which files should be preloaded. Files are preloaded via `` tags added to the + * `` tag; if `output.linkHeaderPreload` is enabled, dynamically rendered pages use the + * [`Link` response header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Link) instead. * By default, `js` and `css` files will be preloaded. * @param input the type of the file and its path */ diff --git a/packages/kit/types/index.d.ts b/packages/kit/types/index.d.ts index ed57f54a6248..162e57f45b07 100644 --- a/packages/kit/types/index.d.ts +++ b/packages/kit/types/index.d.ts @@ -1704,9 +1704,9 @@ declare module '@sveltejs/kit' { */ filterSerializedResponseHeaders?: (name: string, value: string) => boolean; /** - * Determines which files should be preloaded. When a page is rendered dynamically, files are preloaded - * via the [`Link` response header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Link); - * prerendered pages have `` tags added to the `` tag instead. + * Determines which files should be preloaded. Files are preloaded via `` tags added to the + * `` tag; if `output.linkHeaderPreload` is enabled, dynamically rendered pages use the + * [`Link` response header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Link) instead. * By default, `js` and `css` files will be preloaded. * @param input the type of the file and its path */