fix(gatsby): Ensure status returned by getServerData is respected (#33914)

* Fix documentation and starter for use of status in getServerData

* Use status from getServerData in develop and serve

* Add missing handling for HTML in serve

* chore: format

* Update server-side-rendering.md

* Update docs/docs/reference/rendering-options/server-side-rendering.md

Co-authored-by: Alex Moon <[email protected]>

Co-authored-by: gatsbybot <[email protected]>
Co-authored-by: Lennart <[email protected]>
Co-authored-by: Alex Moon <[email protected]>

Author: 4 people

docs/docs/how-to/rendering-options/using-server-side-rendering.md

@@ -65,9 +65,8 @@ export async function getServerData() {
     }
   } catch (error) {
     return {
-      headers: {
-        status: 500,
-      },
+      status: 500,
+      headers: {},
       props: {}
     }
   }
@@ -104,9 +103,8 @@ export async function getServerData() {
     }
   } catch (error) {
     return {
-      headers: {
-        status: 500,
-      },
+      status: 500,
+      headers: {},
       props: {}
     }
   }

docs/docs/reference/rendering-options/server-side-rendering.md

@@ -34,8 +34,9 @@ The `context` parameter is an object with the following keys:
 - `query`: An object representing the query string
 - `params`: If you use [File System Route API](/docs/reference/routing/file-system-route-api/) the URL path gets passed in as `params`. For example, if your page is at `src/pages/{Product.name}.js` the `params` will be an object like `{ name: 'value' }`.
 
-`getServerData` can return an object with two keys:
+`getServerData` can return an object with several possible keys:
 
+- `status` (optional): The HTTP status code that should be returned. Should be a [valid HTTP status](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) code.
 - `props` (optional): Object containing the data passed to `serverData` page prop. Should be a serializable object.
 - `headers` (optional): Object containing `headers` that are sent to the browser and caching proxies/CDNs (e.g., cache headers).
 

packages/gatsby/src/commands/serve.ts

@@ -267,7 +267,11 @@ module.exports = async (program: IServeProgram): Promise<void> => {
                 }
               }
 
-              return void res.send(results)
+              if (page.mode === `SSR` && data.serverDataStatus) {
+                return void res.status(data.serverDataStatus).send(results)
+              } else {
+                return void res.send(results)
+              }
             } catch (e) {
               report.error(
                 `Generating page-data for "${requestedPagePath}" / "${potentialPagePath}" failed.`,
@@ -313,7 +317,11 @@ module.exports = async (program: IServeProgram): Promise<void> => {
                 }
               }
 
-              return res.send(results)
+              if (page.mode === `SSR` && data.serverDataStatus) {
+                return void res.status(data.serverDataStatus).send(results)
+              } else {
+                return void res.send(results)
+              }
             } catch (e) {
               report.error(
                 `Rendering html for "${potentialPagePath}" failed.`,

packages/gatsby/src/utils/get-server-data.ts

@@ -6,6 +6,7 @@ import { match } from "@gatsbyjs/reach-router/lib/utils"
 export interface IServerData {
   headers?: Record<string, string>
   props?: Record<string, unknown>
+  status?: number
 }
 
 interface IModuleWithServerData {

packages/gatsby/src/utils/page-ssr-module/entry.ts

@@ -37,6 +37,7 @@ export interface ISSRData {
   templateDetails: ITemplateDetails
   potentialPagePath: string
   serverDataHeaders?: Record<string, string>
+  serverDataStatus?: number
   searchString: string
 }
 
@@ -222,6 +223,7 @@ export async function getData({
       templateDetails,
       potentialPagePath,
       serverDataHeaders: serverData?.headers,
+      serverDataStatus: serverData?.status,
       searchString,
     }
   } finally {

packages/gatsby/src/utils/start-server.ts

@@ -340,6 +340,7 @@ export async function startServer(
             )
           }
 
+          let statusCode = 200
           if (pageMode === `SSR`) {
             try {
               const result = await serverDataPromise
@@ -354,6 +355,10 @@ export async function startServer(
                 }
               }
 
+              if (result.status) {
+                statusCode = result.status
+              }
+
               pageData.result.serverData = result.props
               pageData.getServerDataError = null
             } catch (error) {
@@ -378,7 +383,7 @@ export async function startServer(
             pageData.result.serverData = null
           }
 
-          res.status(200).send(pageData)
+          res.status(statusCode).send(pageData)
           return
         } catch (e) {
           report.error(

starters/default/src/pages/using-ssr.js

@@ -40,9 +40,8 @@ export async function getServerData() {
     }
   } catch (error) {
     return {
-      headers: {
-        status: 500,
-      },
+      status: 500,
+      headers: {},
       props: {},
     }
   }