[breaking] error handling rework

[dummdidumm]

How to migrate

Step 1: Rename hooks file

There's now also a hooks file for the client. kit.files.hooks is therefore now { server: string; client: string } instead of string. So if you have used that setting, you need to adjust your config:

// svelte.config.js
export default {
  kit: {
-    hooks: 'src/myhooks'
+   hooks: { server: 'src/myhooks' }

If you didn't use that setting, then by default the server hooks now live in src/hooks.server, so you need to rename the file:

|- src
-   |- hooks.js
+   |- hooks.server.js

Step 2: Adjust types

The interface HandleError has been renamed to HandleServerError, to disambiguate it from the new interface HandleClientError. The error type has been changed to unknown. Previously it was typed Error, but we can't know if this is always the case, so we align with TypeScript's type in catch here. This likely means you need to do a type cast, either by checking if it indeed is an Error, or just trusting your (third party) code to always throw Errors:

- import type { HandleError } from '@sveltejs/kit';
+ import type { HandleServerError } from '@sveltejs/kit';

- export const handleError: HandleError = ({ error }) => {
+ export const handleError: HandleServerError = ({ error }) => {
+    if (error instanceof Error) {
         SuperCoolErrorService.log(error);
+   }      
};

Step 3: Define the desired error shape

The shape of $page.error is now defined by the handleError hook, which exists on the server and the client. $page.error is of type App.PageError, which you can define yourself in app.d.ts:

declare namespace App {
  // ...
  interface PageError {
    message: string; // this property is always required, to provide a sensible fallback
    whateverYouWant: string;
  }

You then need to make sure that the handleError function in both hooks.server.js and hooks.client.js adhere to the type by returning that shape from the function:

export function handleError({ error }) {
   // ...
   return {
     message: error.message,
     whateverYouWant: 'something else'
   };
}

If handleError is not defined or the return value is undefined, then SvelteKit falls back to { message: 'Internal Error' }

PR description

Implements #6499

• handleError returns JSON
• App.PageData type
• handleError client hook
• docs
• migration docs

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]

⚠️ No Changeset found

Latest commit: 4687d14

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

[machak]

Defining:
hooks:{server: 'src/hooks/index.ts'},

is throwing error and forcing me to rename the file to:
hooks.server.ts

What is the point of server: setting?

[emmbm]

Defining: hooks:{server: 'src/hooks/index.ts'},

is throwing error and forcing me to rename the file to: hooks.server.ts

What is the point of server: setting?

Is there a reason why you would not want to name your files like so?:

const config = {
    // ...
    files: {
        hooks: {
            server: 'src/hooks/index.server',
            client: 'src/hooks/index.client',
        },
    }
}

I think the compiler needs the .server/ .client to know if your module belongs to the server-side or the client-side (but I might be mistaken).

[machak]

I only use server hooks and my configuration points to it. Either use configuration or convention, but here, we are mixing both.
Right now, I am given a choice to configure it and use my own file name,
but if I do, I get punished for it.

[machak]

if compiler depend on the naming, lets drop using "server:" and "client:" and use array only:
files: {
hooks: ['src/hooks/index.server','src/hooks/index.client'],
}

[dummdidumm]

This might just be a bug related to us trying to be helpful showing an error Message regarding the breaking change. I have to look more closely into it.

[malalecherocks]

If handle() is not implemented in hooks.client.js ... how can I prevent the user navigating between pages? I used to check there if the user had a cookie, if not then redirect to login.

How it's suppouse to do this now? or best practice?