On-Demand ISR example with Build Output API (vercel#306)

Co-authored-by: JJ Kasper <[email protected]>

Author: EndangeredMassa

build-output-api/README.md

@@ -16,6 +16,7 @@ that are listed below.
 - [Edge Functions](./edge-functions)
 - [Edge Middleware](./edge-middleware)
 - [Image Optimization](./image-optimization)
+- [On-Demand Incremental Static Regeneration (ISR)](./on-demand-isr)
 - [Overrides](./overrides)
 - [Prerender Functions](./prerender-functions)
 - [Preview Mode](./preview-mode)

build-output-api/on-demand-isr/.vercel/output/config.json

@@ -0,0 +1,3 @@
+{
+  "version": 3
+}

build-output-api/on-demand-isr/.vercel/output/functions/index.func/.vc-config.json

@@ -0,0 +1,5 @@
+{
+  "runtime": "nodejs16.x",
+  "handler": "index.js",
+  "launcherType": "Nodejs"
+}

build-output-api/on-demand-isr/.vercel/output/functions/index.func/index.js

@@ -0,0 +1,12 @@
+module.exports = (req, res) => {
+  res.setHeader('Content-Type', 'text/html; charset=utf-8')
+
+  // NOTE: the below revalidate link is meant for demo purposes only
+  // actual authentication should be used in actual projects
+  res.end(`
+<h1>On-Demand Incremental Static Regeneration (ISR) Example</h1>
+<p>The "server time" below will only get updated after you click the Revalidate link.</p>
+<p>Server time: ${new Date().toISOString()}</p>
+<p><a href="/revalidate?authToken=a13f94f6-a441-47ca-95fc-9f44f3450295">Revalidate</a></p>
+`)
+}

build-output-api/on-demand-isr/.vercel/output/functions/index.prerender-config.json

@@ -0,0 +1,6 @@
+{
+  "expiration": 180,
+  "group": 1,
+  "bypassToken": "87734ad8259d67c3c11747d3e4e112d0",
+  "allowQuery": []
+}

build-output-api/on-demand-isr/.vercel/output/functions/revalidate.func/.vc-config.json

@@ -0,0 +1,6 @@
+{
+  "runtime": "nodejs16.x",
+  "handler": "index.js",
+  "launcherType": "Nodejs",
+  "shouldAddHelpers": true
+}

build-output-api/on-demand-isr/.vercel/output/functions/revalidate.func/index.js

@@ -0,0 +1,57 @@
+const https = require('https')
+
+// The bypass token should be a build-time randomly generated string of at least 32 characters.
+// This value should only be exposed in the function config and inside of the function itself.
+// DO NOT expose this value on the client-side: a malicious user could trigger boundless revalidations.
+const bypassToken = '87734ad8259d67c3c11747d3e4e112d0'
+
+// This authToken is a trivial example of authentication, but any strong authentication method will work.
+// DO NOT allow unauthenticated users to trigger revalidation: a malicious user could trigger boundless revalidations.
+const authToken = 'a13f94f6-a441-47ca-95fc-9f44f3450295';
+
+module.exports = (req, res) => {
+  const params = new URLSearchParams(req.query);
+  // Validate the request is allowed to trigger revalidation
+  if (authToken !== params.get('authToken')) {
+    res.statusCode = 403
+    res.end('Not Authorized')
+  }
+
+  const host = req.headers.host
+  const deployedUrl = `https://${host}`
+
+  const options = {
+    hostname: host,
+    port: 443,
+    path: '/',
+    method: 'GET', // MUST be "GET"; a "HEAD" or "POST" request will not work
+    headers: {
+      'x-prerender-revalidate': bypassToken
+    }
+  }
+  const revalidateRequest = https.request(options, revalidateResponse => {
+    res.setHeader('Content-Type', 'text/html charset=utf-8')
+
+    if (revalidateResponse.headers['x-vercel-cache'] !== 'REVALIDATED') {
+      res.statusCode = 500
+      res.end(`
+        <h1>Cache NOT Revalidated!</h1>
+        <p>Failed to revalidate. The \`x-vercel-cache\` header was not set to \`REVALIDATED\`.</p>
+      `)
+    }
+
+    res.end(`
+      <h1>Cache Revalidated!</h1>
+      <p>Redirecting you back.</p>
+      <meta http-equiv="refresh" content="2 url=${deployedUrl}">
+    `)
+  })
+
+  revalidateRequest.on('error', error => {
+    console.error(error.stack)
+    res.statusCode = 500
+    res.end()
+  })
+
+  revalidateRequest.end()
+}

build-output-api/on-demand-isr/README.md

@@ -0,0 +1,17 @@
+# On-Demand Incremental Static Regeneration (ISR)
+
+## Build Output API
+
+This Prebuilt Deployment example demonstrates how to implement "On-Demand Incremental Static Regeneration (ISR)" when using the [Build Output API](https://vercel.com/docs/build-output-api/v3).
+
+### Demo
+
+https://build-output-api-isr.vercel.sh
+
+### How it Works
+
+When using Prerender Functions, you may want to revalidate the cache for a specific path.
+
+To implement this, the `bypassToken` of the [`<name>.prerender-config.json`](./.vercel/output/config/index.prerender-config.json) file should be set to a randomized string that you generate at build-time. This string should not be exposed to users / the client-side, except under authenticated circumstances.
+
+To revalidate a path to a Prerender Function, make a `GET` request to that path with a header of `x-prerender-revalidate: <bypassToken>`. A `HEAD` request will not work. When that Prerender Function endpoint is accessed with this header set, the cache will be revalidated, bypassing any caching that Vercel would normally provide.