docs: use per-hook headings on the hooks page by Nic-Polumeyv · Pull Request #16396 · sveltejs/kit

Nic-Polumeyv · 2026-07-17T18:59:37Z

Implements the docs half of #16337, per #16337 (comment). The 'Server hooks', 'Shared hooks' and 'Universal hooks' headings are gone. Each hook is now its own h2 with a note under it saying where it is declared, following the sketch in the issue body. Since the file rename was declined, the notes for reroute and transport say src/hooks.js rather than the sketched hooks.shared.ts.

A few decisions worth reviewing.

locals is not a hook but keeps its own heading. Links to hooks#Server-hooks-locals exist today, and folding the section into handle would bury it.
The paragraphs about sequence and the second parameter of resolve currently sit inside the locals section. They were part of the handle section until docs: auth guide #12810 inserted the ### locals heading above them for the auth guide to link to, so moving them back into handle restores the original placement. Cut and paste, no rewording.
Heading anchors change with the structure, hooks#Server-hooks-handle becomes hooks#handle and so on. All references in the docs tree and the JSDoc are updated, including two runtime error messages that embed docs URLs, the test asserting one of them, and the regenerated packages/kit/types/index.d.ts.
Three links pointed at the removed Server-hooks category heading itself. The hooks.server.js file link in server-only-modules now points at the top of the hooks page, and the two "server hooks" prose links in the auth and web-standards pages point at handle, which is the hook they describe.
External links to the old anchors will break, including a hardcoded hooks#Server-hooks-handle URL in the language-tools TypeScript plugin and some old blog posts on svelte.dev. Happy to send the language-tools follow-up once this merges, and to add redirects if the site has a mechanism for them.

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

It's really useful if your PR references an issue where it is discussed ahead of time. In many cases, features are absent for a reason. For large changes, please create an RFC: https://github.com/sveltejs/rfcs
This message body should clearly illustrate what problems it solves.
Ideally, include a test that fails without this PR but passes with it.

Tests

Run the tests with pnpm test and lint the project with pnpm lint and pnpm check

Changesets

If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running pnpm changeset and following the prompts. Changesets that add features should be minor and those that fix bugs should be patch. Please prefix changeset messages with feat:, fix:, or chore:.

Edits

Please ensure that 'Allow edits from maintainers' is checked. PRs without this option may be closed.

pkg-svelte-dev · 2026-07-17T18:59:40Z

Install the latest version of @sveltejs/kit from 201facc:

pnpm add https://pkg.svelte.dev/@sveltejs/kit/c/201faccdf3646f0def063e60a66338305ade8ebc

Open in pkg.svelte.dev: https://pkg.svelte.dev/repos/kit/pr/16396

Note

This PR is from a fork. A maintainer must approve approve each commit before it can be built and installed.

changeset-bot · 2026-07-17T18:59:44Z

⚠️ No Changeset found

Latest commit: 201facc

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

teemingc · 2026-07-18T09:47:42Z

-The following hooks can be added to `src/hooks.server.js`:
-
-### handle
+> [!NOTE] Declared in `src/hooks.server.js`


Suggested change

> [!NOTE] Declared in `src/hooks.server.js`

> [!NOTE] Can be added to `src/hooks.server.js`

teemingc · 2026-07-18T09:47:56Z

-Note that `resolve(...)` will never throw an error, it will always return a `Promise<Response>` with the appropriate status code. If an error is thrown elsewhere during `handle`, it is treated as fatal, and SvelteKit will respond with a JSON representation of the error or a fallback error page — which can be customised via `src/error.html` — depending on the `Accept` header. You can read more about error handling [here](errors).
-
-### handleFetch
+> [!NOTE] Declared in `src/hooks.server.js`


Suggested change

> [!NOTE] Declared in `src/hooks.server.js`

> [!NOTE] Can be added to `src/hooks.server.js`

teemingc · 2026-07-18T09:48:07Z

-### handleValidationError
+## handleValidationError
+
+> [!NOTE] Declared in `src/hooks.server.js`


Suggested change

> [!NOTE] Declared in `src/hooks.server.js`

> [!NOTE] Can be added to `src/hooks.server.js`

teemingc · 2026-07-18T09:48:17Z

+## handleError

-### handleError
+> [!NOTE] Declared in `src/hooks.server.js` and `src/hooks.client.js`


Suggested change

> [!NOTE] Declared in `src/hooks.server.js` and `src/hooks.client.js`

> [!NOTE] Can be added to `src/hooks.server.js` and `src/hooks.client.js`

teemingc · 2026-07-18T09:48:26Z

-### init
+## init
+
+> [!NOTE] Declared in `src/hooks.server.js` and `src/hooks.client.js`


Suggested change

> [!NOTE] Declared in `src/hooks.server.js` and `src/hooks.client.js`

> [!NOTE] Can be add to `src/hooks.server.js` and `src/hooks.client.js`

teemingc · 2026-07-18T09:48:58Z

+## reroute

-### reroute
+> [!NOTE] Declared in `src/hooks.js`, and runs on both server and client


Suggested change

> [!NOTE] Declared in `src/hooks.js`, and runs on both server and client

> [!NOTE] Can be added to `src/hooks.js`; it runs on both server and client

teemingc · 2026-07-18T09:49:13Z

-### transport
+## transport
+
+> [!NOTE] Declared in `src/hooks.js`, and runs on both server and client


Suggested change

> [!NOTE] Declared in `src/hooks.js`, and runs on both server and client

> [!NOTE] Can be added to `src/hooks.js`; it runs on both server and client

Co-authored-by: Tee Ming <chewteeming01@gmail.com>

closes #14896 The `router.resolution` docs say the server "has an opportunity to intercept each navigation (for example through a middleware)". #14896 read that as "the `handle` hook runs", which it does not. Route resolution requests are answered as soon as the route has been looked up ([respond.js#L323-L324](https://github.com/sveltejs/kit/blob/1406668dbc9c18928dabeff9d15ec756d6d455b3/packages/kit/src/runtime/server/respond.js#L323-L324)), before `handle` is invoked and after `reroute` has run ([respond.js#L249](https://github.com/sveltejs/kit/blob/1406668dbc9c18928dabeff9d15ec756d6d455b3/packages/kit/src/runtime/server/respond.js#L249)). Verified empirically in dev and in preview after a production build, details in #14896 (comment). The wording dates to #13379, which introduced server-side route resolution. The new sentence is scoped to the route lookup rather than stating a blanket "handle never runs", because there is one path where it does. A pathname that fails to decode falls through to normal request handling ([respond.js#L272-L277](https://github.com/sveltejs/kit/blob/1406668dbc9c18928dabeff9d15ec756d6d455b3/packages/kit/src/runtime/server/respond.js#L272-L277)), deliberate behavior from #15744 so that malformed URLs render the default error page. In production `GET /%c0/__route.js` therefore reaches `handle` with pathname `/%c0` before being rejected with a 400. Dev masks this because the dev middleware rejects malformed URIs earlier, which #15744 also notes. Two changes to the option's JSDoc. "Middleware" now says what it refers to, and a sentence states which hooks run for resolution requests. `types/index.d.ts` regenerated. Note on sequencing, #16396 also touches `public.d.ts` (different lines) and regenerates `types/index.d.ts`; whichever merges second needs a trivial rebase and regeneration. --- ### Please don't delete this checklist! Before submitting the PR, please make sure you do the following: - [x] It's really useful if your PR references an issue where it is discussed ahead of time. In many cases, features are absent for a reason. For large changes, please create an RFC: https://github.com/sveltejs/rfcs - [x] This message body should clearly illustrate what problems it solves. - [x] Ideally, include a test that fails without this PR but passes with it. ### Tests - [x] Run the tests with `pnpm test` and lint the project with `pnpm lint` and `pnpm check` ### Changesets - [x] If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running `pnpm changeset` and following the prompts. Changesets that add features should be `minor` and those that fix bugs should be `patch`. Please prefix changeset messages with `feat:`, `fix:`, or `chore:`. ### Edits - [x] Please ensure that 'Allow edits from maintainers' is checked. PRs without this option may be closed. --------- Co-authored-by: Nic Polumeyv <nicolas.polum@gmail.com>

svelte-docs-bot · 2026-07-18T22:39:02Z

Preview: https://svelte-dev-git-preview-kit-16396-svelte.vercel.app/

Rich-Harris

thank you

follow-up to #16396, which unfortunately broke the docs as a result of how they're being built during the 2-3 transition. We need to apply the same changes to `main`, and then merge sveltejs/svelte.dev#2102 --------- Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com> Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>

docs: use per-hook headings on the hooks page

8319df6

Nic-Polumeyv mentioned this pull request Jul 17, 2026

docs: clarify which hooks run during server route resolution #16397

Merged

6 tasks

teemingc added the documentation Improvements or additions to documentation label Jul 18, 2026

Delete .changeset/violet-pans-brush.md

9ed3367

teemingc reviewed Jul 18, 2026

View reviewed changes

Apply suggestions from code review

6a3a04f

Co-authored-by: Tee Ming <chewteeming01@gmail.com>

Rich-Harris mentioned this pull request Jul 18, 2026

chore: update hooks links sveltejs/svelte.dev#2102

Merged

Rich-Harris reviewed Jul 18, 2026

View reviewed changes

Comment thread documentation/docs/30-advanced/20-hooks.md Outdated

Rich-Harris reviewed Jul 18, 2026

View reviewed changes

Comment thread documentation/docs/30-advanced/20-hooks.md Outdated

Apply suggestions from code review

201facc

Rich-Harris approved these changes Jul 18, 2026

View reviewed changes

Rich-Harris merged commit 501bfec into sveltejs:version-3 Jul 18, 2026
17 of 18 checks passed

Rich-Harris mentioned this pull request Jul 19, 2026

docs: update hooks page #16417

Merged

	> [!NOTE] Declared in `src/hooks.server.js`
	> [!NOTE] Can be added to `src/hooks.server.js`

	> [!NOTE] Declared in `src/hooks.server.js` and `src/hooks.client.js`
	> [!NOTE] Can be add to `src/hooks.server.js` and `src/hooks.client.js`

	> [!NOTE] Declared in `src/hooks.js`, and runs on both server and client
	> [!NOTE] Can be added to `src/hooks.js`; it runs on both server and client

Uh oh!

Uh oh!

Conversation

Nic-Polumeyv commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

Tests

Changesets

Edits

Uh oh!

pkg-svelte-dev Bot commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

teemingc Jul 18, 2026

Choose a reason for hiding this comment

Uh oh!

teemingc Jul 18, 2026

Choose a reason for hiding this comment

Uh oh!

teemingc Jul 18, 2026

Choose a reason for hiding this comment

Uh oh!

teemingc Jul 18, 2026

Choose a reason for hiding this comment

Uh oh!

teemingc Jul 18, 2026

Choose a reason for hiding this comment

Uh oh!

teemingc Jul 18, 2026

Choose a reason for hiding this comment

Uh oh!

teemingc Jul 18, 2026

Choose a reason for hiding this comment

Uh oh!

svelte-docs-bot Bot commented Jul 18, 2026

Uh oh!

Uh oh!

Uh oh!

Rich-Harris left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Nic-Polumeyv commented Jul 17, 2026 •

edited

Loading

pkg-svelte-dev Bot commented Jul 17, 2026 •

edited

Loading

changeset-bot Bot commented Jul 17, 2026 •

edited

Loading