make site work with the Cloudflare OpenNext adapter

update the site application so that it can be build using the
Cloudflare OpenNext adapter (`@opennextjs/cloudflare`) and thus
deployed on Cloudflare Workers

Author: dario-piotrowicz

.gitignore

@@ -31,3 +31,11 @@ cache
 tsconfig.tsbuildinfo
 
 dist/
+
+# Ignore the blog-data json that we generate during dev and build
+apps/site/public/blog-data.json
+
+# Ignore worker artifacts
+apps/site/.open-next
+apps/site/.wrangler
+

CONTRIBUTING.md

@@ -7,6 +7,7 @@ Thank you for your interest in contributing to the Node.js Website. Before you p
   - [Becoming a collaborator](#becoming-a-collaborator)
 - [Getting started](#getting-started)
   - [CLI Commands](#cli-commands)
+- [Experimental Cloudflare Deployment](#cloudflare-deployment)
 - [Commit Guidelines](#commit-guidelines)
 - [Pull Request Policy](#pull-request-policy)
 - [Developer's Certificate of Origin 1.1](#developers-certificate-of-origin-11)
@@ -164,6 +165,48 @@ This repository contains several scripts and commands for performing numerous ta
 
 </details>
 
+## Experimental Cloudflare Deployment
+
+The website is in the process of being fully migrated and served from the [Cloudflare](https://www.cloudflare.com) network via [Cloudflare Workers](https://www.cloudflare.com/en-gb/developer-platform/products/workers/) using the [OpenNext Cloudflare adapter](https://opennext.js.org/cloudflare).
+
+Such migration is still in its experimental phase and is being gradually rolled out.
+
+### Scripts
+
+For the time being preview and deployment of the website targeting the Cloudflare network
+is implemented via the following two scripts:
+
+- `npx turbo cloudflare:preview` builds the website using the OpenNext Cloudflare adapter and runs the website locally in a server simulating the Cloudflare hosting (using the [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/))
+- `npx turbo cloudflare:deploy` builds the website using the OpenNext Cloudflare adapter and deploys the website to the Cloudflare network (using the [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/))
+
+### Configurations
+
+There are two types of configurations that relate to Cloudflare.
+
+#### Wrangler Configuration
+
+This is the configuration for the Cloudflare Worker that refers to the artifacts being
+built by the OpenNext adapter. For more details on such configuration please refer to
+the [official Cloudflare documentation](https://developers.cloudflare.com/workers/wrangler/configuration/).
+
+The the most important configurations to keep in mind are:
+
+- `main` points to the worker generated by the OpenNext adapter
+- `account_id` ID of the accounts to use to deploy the application
+  (this account ID doesn't matter for local development, for deployment external contributors can sign up for free at [dash.cloudflare.com](https://dash.cloudflare.com/login) and obtain an account id that they can use to deploy their own fork of the website)
+- `build` build command used to generate Node.js fs polyfills needed for the application to run in a Cloudflare Worker (using the [`@flarelabs/wrangler-build-time-fs-assets-polyfilling`](https://www.npmjs.com/package/@flarelabs-net/wrangler-build-time-fs-assets-polyfilling) package)
+- `alias` map of aliases for the Node.js fs polyfills generated by the `build` configuration
+- `kv_namespaces` array containing a single KV binding definition for `NEXT_CACHE_WORKERS_KV`
+  this is a [KV binding](https://developers.cloudflare.com/kv/concepts/kv-bindings/) used to implement the Next.js incremental cache (again, external contributors can replace the KV ID with their own
+  that they can set up for free at [dash.cloudflare.com/kv/namespaces](https://dash.cloudflare.com/?to=/:account/workers/kv/namespaces))
+
+#### OpenNext Configuration
+
+This is the configuration for the OpenNext Cloudflare adapter, for more details on such configuration please refer to the [official OpenNext documentation](https://opennext.js.org/cloudflare/get-started#4-add-an-open-nextconfigts-file).
+
+The configuration present here is very standard and simply sets up incremental cache via the KV binding
+defined in the wrangler configuration file.
+
 ## Commit Guidelines
 
 This project follows the [Conventional Commits][] specification.

apps/site/app/[locale]/next-data/blog-data/[category]/[page]/route.ts

@@ -11,15 +11,15 @@ import type { BlogCategory } from '@/types';
 
 import styles from './layouts.module.css';
 
-const getBlogCategory = async (pathname: string) => {
+const getBlogCategory = (pathname: string) => {
   // pathname format can either be: /en/blog/{category}
   // or /en/blog/{category}/page/{page}
   // hence we attempt to interpolate the full /en/blog/{category}/page/{page}
   // and in case of course no page argument is provided we define it to 1
   // note that malformed routes can't happen as they are all statically generated
   const [, , category = 'all', , page = 1] = pathname.split('/');
 
-  const { posts, pagination } = await getBlogData(
+  const { posts, pagination } = getBlogData(
     category as BlogCategory,
     Number(page)
   );
@@ -38,7 +38,7 @@ const BlogLayout: FC = async () => {
       link: `/blog/${category}`,
     }));
 
-  const blogData = await getBlogCategory(pathname);
+  const blogData = getBlogCategory(pathname);
 
   return (
     <>

apps/site/layouts/Blog.tsx

@@ -1,38 +1,16 @@
-import {
-  ENABLE_STATIC_EXPORT,
-  IS_DEV_ENV,
-  NEXT_DATA_URL,
-  VERCEL_ENV,
-  VERCEL_REGION,
-} from '@/next.constants.mjs';
 import type { BlogCategory, BlogPostsRSC } from '@/types';
 
-const getBlogData = (
-  cat: BlogCategory,
-  page?: number
-): Promise<BlogPostsRSC> => {
-  const IS_NOT_VERCEL_RUNTIME_ENV =
-    (!IS_DEV_ENV && VERCEL_ENV && !VERCEL_REGION) ||
-    (!IS_DEV_ENV && !VERCEL_ENV);
-
-  // When we're using Static Exports the Next.js Server is not running (during build-time)
-  // hence the self-ingestion APIs will not be available. In this case we want to load
-  // the data directly within the current thread, which will anyways be loaded only once
-  // We use lazy-imports to prevent `provideBlogData` from executing on import
-  if (ENABLE_STATIC_EXPORT || IS_NOT_VERCEL_RUNTIME_ENV) {
-    return import('@/next-data/providers/blogData').then(
-      ({ provideBlogPosts, providePaginatedBlogPosts }) =>
-        page ? providePaginatedBlogPosts(cat, page) : provideBlogPosts(cat)
-    );
-  }
-
-  const fetchURL = `${NEXT_DATA_URL}blog-data/${cat}/${page ?? 0}`;
+import {
+  provideBlogPosts,
+  providePaginatedBlogPosts,
+} from './providers/blogData';
 
-  // This data cannot be cached because it is continuously updated. Caching it would lead to
-  // outdated information being shown to the user.
-  return fetch(fetchURL)
-    .then(response => response.text())
-    .then(JSON.parse);
+const getBlogData = (cat: BlogCategory, page?: number): BlogPostsRSC => {
+  return page && page >= 1
+    ? // This allows us to blindly get all blog posts from a given category
+      // if the page number is 0 or something smaller than 1
+      providePaginatedBlogPosts(cat, page)
+    : provideBlogPosts(cat);
 };
 
 export default getBlogData;

apps/site/next-data/blogData.ts

@@ -1,10 +1,16 @@
 import { cache } from 'react';
 
-import generateBlogData from '@/next-data/generators/blogData.mjs';
 import { BLOG_POSTS_PER_PAGE } from '@/next.constants.mjs';
+import { blogData } from '@/next.json.mjs';
 import type { BlogCategory, BlogPostsRSC } from '@/types';
 
-const { categories, posts } = await generateBlogData();
+const { categories, posts } = {
+  ...blogData,
+  posts: blogData.posts.map(post => ({
+    ...post,
+    date: new Date(post.date),
+  })),
+};
 
 export const provideBlogCategories = cache(() => categories);
 

apps/site/next-data/providers/blogData.ts

@@ -2,6 +2,7 @@
 
 import _authors from './authors.json' with { type: 'json' };
 import _siteNavigation from './navigation.json' with { type: 'json' };
+import _blogData from './public/blog-data.json' with { type: 'json' };
 import _siteRedirects from './redirects.json' with { type: 'json' };
 import _siteConfig from './site.json' with { type: 'json' };
 
@@ -16,3 +17,6 @@ export const siteRedirects = _siteRedirects;
 
 /** @type {import('./types').SiteConfig} */
 export const siteConfig = _siteConfig;
+
+/** @type {import('./types').BlogData} */
+export const blogData = _blogData;

apps/site/next.json.mjs

@@ -0,0 +1,6 @@
+import { defineCloudflareConfig } from '@opennextjs/cloudflare';
+import kvIncrementalCache from '@opennextjs/cloudflare/overrides/incremental-cache/kv-incremental-cache';
+
+export default defineCloudflareConfig({
+  incrementalCache: kvIncrementalCache,
+});

apps/site/open-next.config.ts

@@ -3,9 +3,10 @@
   "type": "module",
   "scripts": {
     "scripts:release-post": "cross-env NODE_NO_WARNINGS=1 node scripts/release-post/index.mjs",
-    "dev": "cross-env NODE_NO_WARNINGS=1 next dev",
-    "serve": "npm run dev",
-    "build": "cross-env NODE_NO_WARNINGS=1 next build --turbopack",
+    "dev": "npm run build-blog-data:watch & sleep 1 && cross-env NODE_NO_WARNINGS=1 next dev",
+    "serve": "npm run build-blog-data:watch & sleep 1 && npm run dev",
+    "prebuild": "npm run build-blog-data",
+    "build": "cross-env NODE_NO_WARNINGS=1 next build",
     "start": "cross-env NODE_NO_WARNINGS=1 next start",
     "deploy": "cross-env NEXT_PUBLIC_STATIC_EXPORT=true NODE_NO_WARNINGS=1 next build",
     "check-types": "tsc --noEmit",
@@ -18,7 +19,12 @@
     "sync-orama": "node ./scripts/orama-search/sync-orama-cloud.mjs",
     "test:unit": "cross-env NODE_NO_WARNINGS=1 node --experimental-test-coverage --test-coverage-exclude=**/*.test.* --experimental-test-module-mocks --enable-source-maps --import=global-jsdom/register --import=tsx --import=tests/setup.jsx --test **/*.test.*",
     "test:unit:watch": "cross-env NODE_OPTIONS=\"--watch\" npm run test:unit",
-    "test": "turbo test:unit"
+    "test": "turbo test:unit",
+    "build-blog-data": "node ./scripts/blog-data/generate.mjs",
+    "build-blog-data:watch": "node --watch --watch-path=pages/en ./scripts/blog-data/generate.mjs",
+    "cloudflare:build:worker": "npx @opennextjs/cloudflare build",
+    "cloudflare:preview": "npm run cloudflare:build:worker && npx wrangler dev",
+    "cloudflare:deploy": "npm run cloudflare:build:worker && npx wrangler deploy"
   },
   "dependencies": {
     "@heroicons/react": "~2.2.0",
@@ -70,7 +76,7 @@
     "@types/semver": "~7.7.0",
     "eslint-config-next": "15.2.4",
     "eslint-import-resolver-typescript": "~4.3.1",
-    "eslint-plugin-mdx": "~3.3.1",
+    "eslint-plugin-mdx": "~3.4.0",
     "eslint-plugin-react": "~7.37.4",
     "eslint-plugin-react-hooks": "5.2.0",
     "global-jsdom": "^26.0.0",
@@ -85,6 +91,9 @@
     "tsx": "^4.19.3",
     "typescript": "~5.8.2",
     "typescript-eslint": "~8.29.0",
-    "user-agent-data-types": "0.4.2"
+    "user-agent-data-types": "0.4.2",
+    "@opennextjs/cloudflare": "^1.0.0-beta.3",
+    "wrangler": "^4.13.0",
+    "@flarelabs-net/wrangler-build-time-fs-assets-polyfilling": "^0.0.0"
   }
 }

apps/site/package.json

@@ -0,0 +1,14 @@
+import { writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import generateBlogData from '../../next-data/generators/blogData.mjs';
+
+const blogData = await generateBlogData();
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+writeFileSync(
+  `${__dirname}/../../public/blog-data.json`,
+  JSON.stringify(blogData),
+  'utf8'
+);