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 commands:
+
+- `pnpm 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/))
+- `pnpm 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://github.com/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 '#site/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 '#site/next.constants.mjs';
 import type { BlogCategory, BlogPostsRSC } from '#site/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('#site/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,16 +1,19 @@
 import { cache } from 'react';
 
-import generateBlogData from '#site/next-data/generators/blogData.mjs';
 import { BLOG_POSTS_PER_PAGE } from '#site/next.constants.mjs';
+import { blogData } from '#site/next.json.mjs';
 import type { BlogCategory, BlogPostsRSC } from '#site/types';
 
-const { categories, posts } = await generateBlogData();
-
-export const provideBlogCategories = cache(() => categories);
+const blogPosts = cache(() =>
+  blogData.posts.map(post => ({
+    ...post,
+    date: new Date(post.date),
+  }))
+);
 
 export const provideBlogPosts = cache(
   (category: BlogCategory): BlogPostsRSC => {
-    const categoryPosts = posts
+    const categoryPosts = blogPosts()
       .filter(post => post.categories.includes(category))
       .sort((a, b) => b.date.getTime() - a.date.getTime());
 

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

@@ -1,9 +1,8 @@
 'use strict';
 
-import {
-  provideBlogCategories,
-  provideBlogPosts,
-} from './next-data/providers/blogData';
+import { blogData } from '#site/next.json.mjs';
+
+import { provideBlogPosts } from './next-data/providers/blogData';
 import { BASE_PATH, BASE_URL } from './next.constants.mjs';
 import { siteConfig } from './next.json.mjs';
 import { defaultLocale } from './next.locales.mjs';
@@ -31,9 +30,9 @@ export const IGNORED_ROUTES = [
  */
 export const DYNAMIC_ROUTES = new Map([
   // Provides Routes for all Blog Categories
-  ...provideBlogCategories().map(c => [`blog/${c}`, 'blog-category']),
+  ...blogData.categories.map(c => [`blog/${c}`, 'blog-category']),
   // Provides Routes for all Blog Categories w/ Pagination
-  ...provideBlogCategories()
+  ...blogData.categories
     // retrieves the amount of pages for each blog category
     .map(c => [c, provideBlogPosts(c).pagination.pages])
     // creates a numeric array for each page and define a pathname for

apps/site/next.dynamic.constants.mjs

@@ -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 });