replace externalFetch with handleFetch

[Rich-Harris]

Migration guide

externalFetch has been replaced with handleFetch. Whereas externalFetch only ran when your load function contained a fetch call for an external URL, handleFetch runs for all fetch calls in load that run on the server. Instead of receiving a request argument, it receives { event, request, fetch }, where event is the underlying RequestEvent and fetch is SvelteKit's internal fetch implementation.

-/** @type {import('@sveltejs/kit').ExternalFetch} */
-export function externalFetch(request) {
+/** @type {import('@sveltejs/kit').HandleFetch} */
+export function handleFetch({ event, request, fetch }) {
+  const internal = request.url.startsWith(event.url.origin + '/');
+  if (internal) return fetch(request);
  // handle external request
}

---

Original PR description

Supersedes part of #6541
Closes #5253
Closes #5195
Closes #4750

This replaces externalFetch with a new handleFetch hook, which gives developers the ability to forward whichever headers they need on a case-by-case basis — so for example if your load function looks like this...

export async function load({ fetch }) {
  const res = await fetch('/whatever');
  // ...
}

...the fetch will be made without any non-default headers, but you can add custom headers inside handleFetch:

// src/hooks.js
const forwarded = [
  'x-my-custom-auth-header'
];

export async function handleFetch({ event, request, fetch }) {
  assert.ok(request instanceof Request);
  assert.equal(request.url, event.url.origin + '/whatever');

  for (const header of forwarded) {
    const value = event.request.headers.has(header);
    if (value !== null && !request.headers.has(header)) {
      request.headers.set(header, value);
    }
  }

  return fetch(request);
}

If unimplemented, defaults to ({ request, fetch }) => fetch(request).

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. All changesets should be patch until SvelteKit 1.0

[changeset-bot]

🦋 Changeset detected

Latest commit: ecf3ecb

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@sveltejs/kit	Patch

Not sure what this means? Click here to learn what changesets are.

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

[netlify]

✅ Deploy Preview for kit-demo ready!

Name	Link
🔨 Latest commit	ecf3ecb
🔍 Latest deploy log	https://app.netlify.com/sites/kit-demo/deploys/631604f5b02a910009cbf1b1
😎 Deploy Preview	https://deploy-preview-6565--kit-demo.netlify.app/build
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[Conduitry]

Do you think it makes sense to call out the cookie sibling subdomain thing explicitly in the docs? Can we do that without it being too confusing? We've heard from a few people that it took then a while to even understand why their app wasn't working, so this might also be a good opportunity to tell people how the default conservative cookie passing works.

[Rich-Harris]

Excellent point. Does b96a5fd spark joy? (I will settle for 'it is coherent and correct')

[Conduitry]

Maybe write the code to check origin instead of substrings of the URL? Other than that, sounds good to me. 👍

Edit: Oh, we don't have a URL instance here necessarily. Should we normalize it so that we do?

[Rich-Harris]

in the code or in the docs?

[Conduitry]

Uh. I had meant in the code, but in the docs might suffice, as long as they are careful not to instantiate URLs from relative request.urls. What you have here now might be perfectly fine, actually, because it's not going to be ambiguous anyway. I'm good with it if you don't want to make it more complicated.

[Rich-Harris]

as long as they are careful not to instantiate URLs from relative request.urls

There's no such thing — if you create a Request on the server, the URL must be fully resolved or Undici will throw — that's what this line is for

[nhunzaker]

Reading over the documentation changes and code, I think this'll work great for my use case. Thank you for considering it and making changes to the API.