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

@@ -35,3 +35,11 @@ cache
 tsconfig.tsbuildinfo
 
 dist/
+
+# Ignore the blog-data json that we generate during dev and build
+apps/site/public/blog-data.json
+
+# Cloudflare Build Output
+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)
+- [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)
@@ -165,6 +166,42 @@ This repository contains several scripts and commands for performing numerous ta
 
 </details>
 
+## Cloudflare Deployment
+
+The Node.js Website can be deployed to the [Cloudflare](https://www.cloudflare.com) network using [Cloudflare Workers](https://www.cloudflare.com/en-gb/developer-platform/products/workers/) and the [OpenNext Cloudflare adapter](https://opennext.js.org/cloudflare). This section provides the necessary details for testing and deploying the website on Cloudflare.
+
+### Scripts
+
+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 key configuration files related to Cloudflare deployment.
+
+#### Wrangler Configuration
+
+This file defines the settings for the Cloudflare Worker, which serves the website.
+
+For more details, refer to the [Wrangler documentation](https://developers.cloudflare.com/workers/wrangler/configuration/).
+
+Key configurations include:
+
+- `main`: Points to the worker generated by the OpenNext adapter.
+- `account_id`: Specifies the Cloudflare account ID. This is not required for local previews but is necessary for deployments. You can obtain an account ID for free by signing up at [dash.cloudflare.com](https://dash.cloudflare.com/login).
+- `build`: Defines the build command to generate Node.js filesystem polyfills required for the application to run on Cloudflare Workers. This uses the [`@flarelabs/wrangler-build-time-fs-assets-polyfilling`](https://www.npmjs.com/package/@flarelabs-net/wrangler-build-time-fs-assets-polyfilling) package.
+- `alias`: Maps aliases for the Node.js filesystem polyfills generated during the build process.
+- `kv_namespaces`: Contains a single KV binding definition for `NEXT_CACHE_WORKERS_KV`. This is used to implement the Next.js incremental cache. For deployments, you can create a new KV namespace in the Cloudflare dashboard and update the binding ID accordingly.
+
+#### 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/.stylelintignore

@@ -13,3 +13,7 @@ lcov.info
 
 # Old Styles
 styles/old
+
+# Cloudflare Build Output
+.open-next
+.wrangler

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,32 +1,16 @@
-import {
-  ENABLE_STATIC_EXPORT,
-  NEXT_DATA_URL,
-  IS_NOT_VERCEL_RUNTIME_ENV,
-} from '@/next.constants.mjs';
 import type { BlogCategory, BlogPostsRSC } from '@/types';
 
-const getBlogData = (
-  cat: BlogCategory,
-  page?: number
-): Promise<BlogPostsRSC> => {
-  // 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,14 @@
 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 } = blogData;
+const 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,4 @@
+import { defineCloudflareConfig } from '@opennextjs/cloudflare';
+import incrementalCache from '@opennextjs/cloudflare/overrides/incremental-cache/kv-incremental-cache';
+
+export default defineCloudflareConfig({ incrementalCache });

apps/site/open-next.config.ts

@@ -2,9 +2,11 @@
   "name": "@node-core/website",
   "type": "module",
   "scripts": {
-    "build": "cross-env NODE_NO_WARNINGS=1 next build --turbopack",
+    "prebuild": "pnpm build-blog-data",
+    "build": "cross-env NODE_NO_WARNINGS=1 next build",
     "check-types": "tsc --noEmit",
     "deploy": "cross-env NEXT_PUBLIC_STATIC_EXPORT=true NODE_NO_WARNINGS=1 next build",
+    "predev": "pnpm build-blog-data",
     "dev": "cross-env NODE_NO_WARNINGS=1 next dev",
     "lint": "turbo run lint:md lint:snippets lint:js lint:css",
     "lint:css": "stylelint \"**/*.css\" --allow-empty-input --cache --cache-strategy=content --cache-location=.stylelintcache",
@@ -18,7 +20,12 @@
     "sync-orama": "node ./scripts/orama-search/sync-orama-cloud.mjs",
     "test": "turbo test:unit",
     "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\" pnpm test:unit"
+    "test:unit:watch": "cross-env NODE_OPTIONS=\"--watch\" pnpm test:unit",
+    "build-blog-data": "node ./scripts/blog-data/generate.mjs",
+    "build-blog-data:watch": "node --watch --watch-path=pages/en/blog ./scripts/blog-data/generate.mjs",
+    "cloudflare:build:worker": "opennextjs-cloudflare build",
+    "cloudflare:preview": "pnpm run cloudflare:build:worker && wrangler dev",
+    "cloudflare:deploy": "pnpm run cloudflare:build:worker && wrangler deploy"
   },
   "dependencies": {
     "@heroicons/react": "~2.2.0",
@@ -107,6 +114,12 @@
     "typescript": "~5.8.2",
     "typescript-eslint": "~8.31.1",
     "unified": "^11.0.5",
-    "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"
+  },
+  "optionalDependencies": {
+    "@tailwindcss/oxide-linux-x64-gnu": "~4.1.4"
   }
 }