From fc9d4d186668c6a9a7868864f5267865ba56014a Mon Sep 17 00:00:00 2001 From: Reginaldo Junior Date: Sat, 9 Aug 2025 18:37:43 -0300 Subject: [PATCH 1/5] docs(start): add example of how to handle errors using middlewares --- docs/start/framework/react/middleware.md | 34 ++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/start/framework/react/middleware.md b/docs/start/framework/react/middleware.md index ecae7a9a87..7735e0cfe2 100644 --- a/docs/start/framework/react/middleware.md +++ b/docs/start/framework/react/middleware.md @@ -426,3 +426,37 @@ Middleware functionality is tree-shaken based on the environment for each bundle - On the server, nothing is tree-shaken, so all code used in middleware will be included in the server bundle. - On the client, all server-specific code is removed from the client bundle. This means any code used in the `server` method is always removed from the client bundle. If `validateClient` is set to `true`, the client-side validation code will be included in the client bundle, otherwise `data` validation code will also be removed. + +## Handling Errors + +Middlewares can handle errors by using a try...catch block and throwing a `Response` object. +This will cause the middleware chain to short-circuit and return the response to the client. + +```tsx +const errorHandlingMiddleware = createMiddleware({ type: 'function' }).server( + async ({ next }) => { + try { + const result = await next() + // Optionally do something with the result here + return result + } catch (error) { + if (/* Custom logic here */) { + throw json({ + status: 400, + message: 'Bad Request', + }) + + // Or + throw new Response('Bad Request', { + status: 400, + headers: { + 'Content-Type': 'application/json', + }, + }) + } + + throw error // <-- This will be handled by the next middleware in the chain + } + }, +) +``` From 8cb817459cb49eb3ddab2ce70740b4cda1050e13 Mon Sep 17 00:00:00 2001 From: Reginaldo Junior Date: Sat, 9 Aug 2025 18:42:26 -0300 Subject: [PATCH 2/5] docs(start): add note about order --- docs/start/framework/react/middleware.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/start/framework/react/middleware.md b/docs/start/framework/react/middleware.md index 7735e0cfe2..6f7afecb44 100644 --- a/docs/start/framework/react/middleware.md +++ b/docs/start/framework/react/middleware.md @@ -432,6 +432,8 @@ Middleware functionality is tree-shaken based on the environment for each bundle Middlewares can handle errors by using a try...catch block and throwing a `Response` object. This will cause the middleware chain to short-circuit and return the response to the client. +Ideally, this middleware would be one of the first middlewares in the chain, to catch all subsequent errors. + ```tsx const errorHandlingMiddleware = createMiddleware({ type: 'function' }).server( async ({ next }) => { From 8084122e8050b1f1c6cf6046dfaff5e84ef931d5 Mon Sep 17 00:00:00 2001 From: Reginaldo Junior Date: Sat, 9 Aug 2025 18:46:54 -0300 Subject: [PATCH 3/5] docs(start): add more info about what happens when no middleware catches the error --- docs/start/framework/react/middleware.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/start/framework/react/middleware.md b/docs/start/framework/react/middleware.md index 6f7afecb44..735f39cf8f 100644 --- a/docs/start/framework/react/middleware.md +++ b/docs/start/framework/react/middleware.md @@ -429,7 +429,7 @@ Middleware functionality is tree-shaken based on the environment for each bundle ## Handling Errors -Middlewares can handle errors by using a try...catch block and throwing a `Response` object. +Middlewares can handle errors by using a try...catch block and throwing a `Response` object. This will cause the middleware chain to short-circuit and return the response to the client. Ideally, this middleware would be one of the first middlewares in the chain, to catch all subsequent errors. @@ -457,8 +457,12 @@ const errorHandlingMiddleware = createMiddleware({ type: 'function' }).server( }) } - throw error // <-- This will be handled by the next middleware in the chain + // If the error is not part of the custom logic, it should be handled by the next middleware in the chain + // If the error is not handled by any other middleware, it will be captured by the server-functions-handler, and the error will be serialized and returned to the client + throw error } }, ) ``` + +˜ From 7cc04beb9201d28ecaa7a45e17e4c27595e3f23d Mon Sep 17 00:00:00 2001 From: Reginaldo Junior Date: Sat, 9 Aug 2025 20:36:25 -0300 Subject: [PATCH 4/5] docs(start): tidy up --- docs/start/framework/react/middleware.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/start/framework/react/middleware.md b/docs/start/framework/react/middleware.md index 735f39cf8f..0676fe9218 100644 --- a/docs/start/framework/react/middleware.md +++ b/docs/start/framework/react/middleware.md @@ -429,7 +429,7 @@ Middleware functionality is tree-shaken based on the environment for each bundle ## Handling Errors -Middlewares can handle errors by using a try...catch block and throwing a `Response` object. +Middlewares can handle errors thrown by server functions or other middlewares by using a try...catch block and throwing a `Response` object. This will cause the middleware chain to short-circuit and return the response to the client. Ideally, this middleware would be one of the first middlewares in the chain, to catch all subsequent errors. @@ -443,6 +443,7 @@ const errorHandlingMiddleware = createMiddleware({ type: 'function' }).server( return result } catch (error) { if (/* Custom logic here */) { + // maybeReportError(error) throw json({ status: 400, message: 'Bad Request', @@ -464,5 +465,3 @@ const errorHandlingMiddleware = createMiddleware({ type: 'function' }).server( }, ) ``` - -˜ From fe5d1c2859ee1e1fa60e188874c1fe9d5e25b5ab Mon Sep 17 00:00:00 2001 From: Reginaldo Junior Date: Mon, 11 Aug 2025 11:51:36 -0300 Subject: [PATCH 5/5] docs(start): clarify --- docs/start/framework/react/middleware.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/start/framework/react/middleware.md b/docs/start/framework/react/middleware.md index 0676fe9218..9518b7ce8a 100644 --- a/docs/start/framework/react/middleware.md +++ b/docs/start/framework/react/middleware.md @@ -430,7 +430,7 @@ Middleware functionality is tree-shaken based on the environment for each bundle ## Handling Errors Middlewares can handle errors thrown by server functions or other middlewares by using a try...catch block and throwing a `Response` object. -This will cause the middleware chain to short-circuit and return the response to the client. +This will cause the error to bubble-up the middleware chain and ultimately return the response to the client. Ideally, this middleware would be one of the first middlewares in the chain, to catch all subsequent errors.