🗺 Fix server error logging and add onUnhandledError support

.changeset/log-server-errors.md

@@ -0,0 +1,5 @@
+---
+"@remix-run/server-runtime": patch
+---
+
+Ensure un-sanitized server errors are logged on the server during document requests

.changeset/on-unhandled-error.md

@@ -0,0 +1,22 @@
+---
+"@remix-run/server-runtime": minor
+---
+
+Add optional `onUnhandledError` export for custom server-side error processing.  This is a new optional export from your `entry.server.tsx` that will be called with any encountered error on the Remix server (loader, action, or render error):
+
+```ts
+// entry.server.tsx
+export function onUnhandledError(
+  error: unknown,
+  { request, params, context }: DataFunctionArgs
+): void {
+  if (error instanceof Error) {
+    sendErrorToBugReportingService(error);
+    console.error(formatError(error));
+  } else {
+    let unknownError = new Error("Unknown Server Error");
+    sendErrorToBugReportingService(unknownError);
+    console.error(unknownError);
+  }
+}
+```

docs/file-conventions/entry.server.md

@@ -5,10 +5,53 @@ toc: false
 
 # entry.server
 
-By default, Remix will handle generating the HTTP Response for you. If you want to customize this behavior, you can run `npx remix reveal` to generate a `app/entry.server.tsx` (or `.jsx`) that will take precedence. The `default` export of this module is a function that lets you create the response, including HTTP status, headers, and HTML, giving you full control over the way the markup is generated and sent to the client.
+By default, Remix will handle generating the HTTP Response for you. If you want to customize this behavior, you can run `npx remix reveal` to generate an `app/entry.server.tsx` (or `.jsx`) that will take precedence. The `default` export of this module is a function that lets you create the response, including HTTP status, headers, and HTML, giving you full control over the way the markup is generated and sent to the client.
 
 This module should render the markup for the current page using a `<RemixServer>` element with the `context` and `url` for the current request. This markup will (optionally) be re-hydrated once JavaScript loads in the browser using the [browser entry module][browser-entry-module].
 
-You can also export an optional `handleDataRequest` function that will allow you to modify the response of a data request. These are the requests that do not render HTML, but rather return the loader and action data to the browser once client-side hydration has occurred.
+## `handleDataRequest`
+
+You can export an optional `handleDataRequest` function that will allow you to modify the response of a data request. These are the requests that do not render HTML, but rather return the loader and action data to the browser once client-side hydration has occurred.
+
+```tsx
+export function handleDataRequest(
+  response: Response,
+  { request, params, context }: DataFunctionArgs
+) {
+  response.headers.set("X-Custom-Header", "value");
+  return response;
+}
+```
+
+## `onUnhandledError`
+
+By default, Remix will log encountered server-side errors to the console. If you'd like more control over the logging, or would like to also report these errors to an external service, then you can export an optional `onUnhandledError` function which will give you control (and will disable the built-in error logging).
+
+```tsx
+export function onUnhandledError(
+  error: unknown,
+  { request, params, context }: DataFunctionArgs
+) {
+  sendErrorToErrorReportingService(error);
+  console.error(formatErrorForJsonLogging(error));
+}
+```
+
+### Streaming Rendering Errors
+
+When you are streaming your HTML responses via [`renderToPipeableStream`][rendertopipeablestream] or [`renderToReadableStream`][rendertoreadablestream], your own `onUnhandledError` implementation will only handle errors encountered uring the initial shell render. If you encounter a rendering error during subsequent streamed rendering you will need handle these errors manually since the Remix server has already sent the Response by that point.
+
+- For `renderToPipeableStream`, you can handle these errors in the `onError` callback function. You will need to toggle a boolean when the in `onShellReady` so you know if the error was a shell rendering error (and can be ignored) or an async rendering error (and must be handled).
+  - For an exmaple, please see the default [`entry.server.tsx`][node-streaming-entry-server] for Node.
+- For `renderToReadableStream`, you can handle these errors in the `onError` callback function
+  - For an example, please see the default [`entry.server.tsx`][cloudflare-streaming-entry-server] for Cloudflare
+
+### Thrown Responses
+
+Note that this does not handle thrown `Response` instances from your `loader`/`action` functions. The intention of this handler is to find bugs in your code which result in unexpected thrown errors. If you are detecting a scenario and throwing a 401/404/etc. `Response` in your `loader`/`action` then it's an expected flow that is handled by your code. If you also wish to log, or send those to an external service, that should be done at the time you throw the response.
 
 [browser-entry-module]: ./entry.client
+[rendertopipeablestream]: https://react.dev/reference/react-dom/server/renderToPipeableStream
+[rendertoreadablestream]: https://react.dev/reference/react-dom/server/renderToReadableStream
+[node-streaming-entry-server]: https://github.com/remix-run/remix/blob/main/packages/remix-dev/config/defaults/node/entry.server.react-stream.tsx
+[cloudflare-streaming-entry-server]: https://github.com/remix-run/remix/blob/main/packages/remix-dev/config/defaults/cloudflare/entry.server.react-stream.tsx