provide revalidateReason to getStaticProps

packages/next/src/server/render.tsx

@@ -845,7 +845,7 @@ export async function renderToHTMLImpl(
           },
         },
         () =>
-          getStaticProps!({
+          getStaticProps({
             ...(pageIsDynamic
               ? { params: query as ParsedUrlQuery }
               : undefined),
@@ -855,6 +855,11 @@ export async function renderToHTMLImpl(
             locales: renderOpts.locales,
             locale: renderOpts.locale,
             defaultLocale: renderOpts.defaultLocale,
+            revalidateReason: renderOpts.isOnDemandRevalidate
+              ? 'on-demand'
+              : isBuildTimeSSG
+              ? 'build'
+              : 'stale',
           })
       )
     } catch (staticPropsError: any) {

packages/next/types/index.d.ts

@@ -185,6 +185,7 @@ export type GetStaticPropsContext<
   locale?: string
   locales?: string[]
   defaultLocale?: string
+  revalidateReason?: 'on-demand' | 'build' | 'stale'
 }
 
 /**

test/e2e/revalidate-reason/pages/api/revalidate.ts

@@ -0,0 +1,15 @@
+import { NextApiRequest, NextApiResponse } from 'next'
+
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse<{ revalidated: boolean }>
+) {
+  try {
+    await res.revalidate('/')
+    return res.json({ revalidated: true })
+  } catch (err) {
+    console.error('Failed to revalidate:', err)
+  }
+
+  res.json({ revalidated: false })
+}

test/e2e/revalidate-reason/pages/index.tsx

@@ -0,0 +1,17 @@
+import React from 'react'
+
+export async function getStaticProps({ params, revalidateReason }) {
+  console.log(
+    'revalidate-reason/pages/index.tsx revalidateReason:',
+    revalidateReason
+  )
+  return {
+    props: {
+      hello: 'world',
+    },
+  }
+}
+
+export default ({ hello }) => {
+  return <p>hello: {hello}</p>
+}

test/e2e/revalidate-reason/pages/stale.tsx

@@ -0,0 +1,18 @@
+import React from 'react'
+
+export async function getStaticProps({ params, revalidateReason }) {
+  console.log(
+    'revalidate-reason/pages/stale.tsx revalidateReason:',
+    revalidateReason
+  )
+  return {
+    props: {
+      hello: 'world',
+    },
+    revalidate: 5,
+  }
+}
+
+export default ({ hello }) => {
+  return <p>hello: {hello}</p>
+}

test/e2e/revalidate-reason/revalidate-reason.test.ts

@@ -0,0 +1,61 @@
+import { nextTestSetup } from 'e2e-utils'
+import { retry, waitFor } from 'next-test-utils'
+
+describe('revalidate-reason', () => {
+  const { next, isNextDev } = nextTestSetup({
+    files: __dirname,
+  })
+
+  if (isNextDev) {
+    describe('development mode', () => {
+      // in dev mode, the revalidateReason is called on every request, and will always be considered stale
+      it('should support revalidateReason: "stale"', async () => {
+        const res = await next.fetch('/')
+
+        expect(res.status).toBe(200)
+
+        expect(next.cliOutput).toContain(
+          'revalidate-reason/pages/index.tsx revalidateReason: stale'
+        )
+      })
+    })
+
+    // skip the remaining tests as they do not apply in dev
+    return
+  }
+
+  it('should support revalidateReason: "build"', async () => {
+    expect(next.cliOutput).toContain(
+      'revalidate-reason/pages/index.tsx revalidateReason: build'
+    )
+    expect(next.cliOutput).toContain(
+      'revalidate-reason/pages/stale.tsx revalidateReason: build'
+    )
+  })
+
+  it('should support revalidateReason: "on-demand"', async () => {
+    const res = await next.fetch('/api/revalidate')
+
+    expect(res.status).toBe(200)
+
+    expect(next.cliOutput).toContain(
+      'revalidate-reason/pages/index.tsx revalidateReason: on-demand'
+    )
+  })
+
+  it('should support revalidateReason: "stale"', async () => {
+    const res = await next.fetch('/stale')
+    expect(res.status).toBe(200)
+
+    // wait for the revalidation period
+    await waitFor(5000)
+
+    await retry(async () => {
+      await next.fetch('/stale')
+
+      expect(next.cliOutput).toContain(
+        'revalidate-reason/pages/stale.tsx revalidateReason: stale'
+      )
+    })
+  })
+})