refactor: split platform-specific code into platform-vercel and platform-cloudflare packages

.github/CODEOWNERS

@@ -27,8 +27,11 @@ turbo.json @nodejs/nodejs-website @nodejs/web-infra
 crowdin.yml @nodejs/web-infra
 apps/site/redirects.json @nodejs/web-infra
 apps/site/site.json @nodejs/web-infra
-apps/site/wrangler.jsonc @nodejs/web-infra
-apps/site/open-next.config.ts @nodejs/web-infra
+platforms/cloudflare/wrangler.jsonc @nodejs/web-infra
+platforms/cloudflare/open-next.config.ts @nodejs/web-infra
+platforms/cloudflare/next.platform.config.mjs @nodejs/web-infra
+platforms/vercel/vercel.json @nodejs/web-infra
+platforms/vercel/next.platform.config.mjs @nodejs/web-infra
 apps/site/redirects.json @nodejs/web-infra
 
 # Critical Documents

.github/workflows/playwright-cloudflare-open-next.yml

@@ -50,12 +50,19 @@ jobs:
         working-directory: apps/site
         run: node_modules/.bin/playwright install --with-deps
 
+      - name: Build open-next site
+        working-directory: platforms/cloudflare
+        run: node --run cloudflare:build:worker
+        env:
+          NEXT_PUBLIC_DEPLOY_TARGET: cloudflare
+          NODE_OPTIONS: --conditions=cloudflare
+
       - name: Run Playwright tests
         working-directory: apps/site
         run: node --run playwright
         env:
-          PLAYWRIGHT_RUN_CLOUDFLARE_PREVIEW: true
-          PLAYWRIGHT_BASE_URL: http://127.0.0.1:8787
+          NEXT_PUBLIC_DEPLOY_TARGET: cloudflare
+          NODE_OPTIONS: --conditions=cloudflare
 
       - name: Upload Playwright test results
         if: always()

.github/workflows/tmp-cloudflare-open-next-deploy.yml

@@ -50,20 +50,25 @@ jobs:
           cache: 'pnpm'
 
       - name: Install packages
-        run: pnpm install --frozen-lockfile
+        run: pnpm install --frozen-lockfile --filter=@node-core/website... --filter=@node-core/platform-cloudflare...
 
       - name: Build blog data
         working-directory: apps/site
         run: node --run build:blog-data
 
       - name: Build open-next site
-        working-directory: apps/site
+        working-directory: platforms/cloudflare
         run: node --run cloudflare:build:worker
+        env:
+          NEXT_PUBLIC_DEPLOY_TARGET: cloudflare
+          NODE_OPTIONS: --conditions=cloudflare
 
       - name: Deploy open-next site
-        working-directory: apps/site
+        working-directory: platforms/cloudflare
         run: node --run cloudflare:deploy
         env:
+          NEXT_PUBLIC_DEPLOY_TARGET: cloudflare
+          NODE_OPTIONS: --conditions=cloudflare
           CF_WORKERS_SCRIPTS_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           CLOUDFLARE_ACCOUNT_ID: fb4a2d0f103c6ff38854ac69eb709272

.gitignore

@@ -43,6 +43,7 @@ dist/
 # Cloudflare Build Output
 apps/site/.open-next
 apps/site/.wrangler
+platforms/cloudflare/.wrangler
 
 ## Playwright
 test-results

apps/site/app/[locale]/@analytics/default.tsx

@@ -0,0 +1 @@
+export { default } from '@platform/analytics';

apps/site/app/[locale]/layout.tsx

@@ -1,25 +1,27 @@
 import { availableLocales, defaultLocale } from '@node-core/website-i18n';
-import { Analytics } from '@vercel/analytics/react';
-import { SpeedInsights } from '@vercel/speed-insights/next';
 import classNames from 'classnames';
 import { NextIntlClientProvider } from 'next-intl';
 
 import BaseLayout from '#site/layouts/Base';
-import { VERCEL_ENV } from '#site/next.constants.mjs';
 import { IBM_PLEX_MONO, OPEN_SANS } from '#site/next.fonts';
 import { ThemeProvider } from '#site/providers/themeProvider';
 
-import type { FC, PropsWithChildren } from 'react';
+import type { FC, PropsWithChildren, ReactNode } from 'react';
 
 import '#site/styles/index.css';
 
 const fontClasses = classNames(IBM_PLEX_MONO.variable, OPEN_SANS.variable);
 
 type RootLayoutProps = PropsWithChildren<{
   params: Promise<{ locale: string }>;
+  analytics: ReactNode;
 }>;
 
-const RootLayout: FC<RootLayoutProps> = async ({ children, params }) => {
+const RootLayout: FC<RootLayoutProps> = async ({
+  children,
+  analytics,
+  params,
+}) => {
   const { locale } = await params;
 
   const { langDir, hrefLang } =
@@ -46,12 +48,7 @@ const RootLayout: FC<RootLayoutProps> = async ({ children, params }) => {
           href="https://social.lfx.dev/@nodejs"
         />
 
-        {VERCEL_ENV && (
-          <>
-            <Analytics />
-            <SpeedInsights />
-          </>
-        )}
+        {analytics}
       </body>
     </html>
   );

apps/site/eslint.config.js

@@ -6,15 +6,7 @@ import baseConfig from '../../eslint.config.js';
 
 export default baseConfig.concat([
   {
-    ignores: [
-      'pages/en/blog/**/*.{md,mdx}/**',
-      'public',
-      'next-env.d.ts',
-      // The worker entrypoint is bundled by wrangler, not tsc. Its imports
-      // trigger a tsc crash (see tsconfig.json), so it is excluded from both
-      // type checking and ESLint's type-aware linting.
-      'cloudflare/worker-entrypoint.ts',
-    ],
+    ignores: ['pages/en/blog/**/*.{md,mdx}/**', 'public', 'next-env.d.ts'],
   },
 
   eslintReact.configs['recommended-typescript'],

apps/site/instrumentation.ts

@@ -1,7 +1 @@
-export async function register() {
-  if (!('Cloudflare' in globalThis)) {
-    // Note: we don't need to set up the Vercel OTEL if the application is running on Cloudflare
-    const { registerOTel } = await import('@vercel/otel');
-    registerOTel({ serviceName: 'nodejs-org' });
-  }
-}
+export { register } from '@platform/instrumentation';

apps/site/mdx/plugins.mjs

@@ -7,27 +7,16 @@ import rehypeSlug from 'rehype-slug';
 import remarkGfm from 'remark-gfm';
 import readingTime from 'remark-reading-time';
 
-import remarkTableTitles from '../util/table';
+// MDX overrides contributed by the active deployment target. Resolved via
+// the `#platform/next.platform.config` import map in `package.json`; each
+// platform owns its own `{ wasm, twoslash }` defaults and the in-repo
+// default file acts as the standalone fallback.
+import platform from '#platform/next.platform.config';
 
-// TODO(@avivkeller): When available, use `OPEN_NEXT_CLOUDFLARE` environment
-// variable for detection instead of current method, which will enable better
-// tree-shaking.
-// Reference: https://github.com/nodejs/nodejs.org/pull/7896#issuecomment-3009480615
-const OPEN_NEXT_CLOUDFLARE = 'Cloudflare' in global;
+import remarkTableTitles from '../util/table';
 
 // Shiki is created out here to avoid an async rehype plugin
-const singletonShiki = await rehypeShikiji({
-  // We use the faster WASM engine on the server instead of the web-optimized version.
-  //
-  // Currently we fall back to the JavaScript RegEx engine
-  // on Cloudflare workers because `shiki/wasm` requires loading via
-  // `WebAssembly.instantiate` with custom imports, which Cloudflare doesn't support
-  // for security reasons.
-  wasm: !OPEN_NEXT_CLOUDFLARE,
-
-  // TODO(@avivkeller): Find a way to enable Twoslash w/ a VFS on Cloudflare
-  twoslash: !OPEN_NEXT_CLOUDFLARE,
-});
+const singletonShiki = await rehypeShikiji(platform.mdx);
 
 /**
  * Provides all our Rehype Plugins that are used within MDX

apps/site/next.config.mjs

@@ -1,23 +1,17 @@
 'use strict';
+
 import createNextIntlPlugin from 'next-intl/plugin';
 
-import { OPEN_NEXT_CLOUDFLARE } from './next.constants.cloudflare.mjs';
-import { BASE_PATH, ENABLE_STATIC_EXPORT } from './next.constants.mjs';
+import platform from '#platform/next.platform.config';
+
+import {
+  BASE_PATH,
+  ENABLE_STATIC_EXPORT,
+  DEPLOY_TARGET,
+} from './next.constants.mjs';
 import { getImagesConfig } from './next.image.config.mjs';
 import { redirects, rewrites } from './next.rewrites.mjs';
 
-const getDeploymentId = async () => {
-  if (OPEN_NEXT_CLOUDFLARE) {
-    // If we're building for the Cloudflare deployment we want to set
-    // an appropriate deploymentId (needed for skew protection)
-    const openNextAdapter = await import('@opennextjs/cloudflare');
-
-    return openNextAdapter.getDeploymentId();
-  }
-
-  return undefined;
-};
-
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   // Full Support of React 18 SSR and Streaming
@@ -27,9 +21,14 @@ const nextConfig = {
   // We allow the BASE_PATH to be overridden in case that the Website
   // is being built on a subdirectory (e.g. /nodejs-website)
   basePath: BASE_PATH,
-  // Vercel/Next.js Image Optimization Settings
-  images: getImagesConfig(),
+  images: getImagesConfig(await platform.images?.()),
   serverExternalPackages: ['twoslash'],
+  // Transpile platform packages' TSX/TS sources when they're pulled in via
+  // the `@platform/*` aliases from the active `next.platform.config.mjs`.
+  transpilePackages: [
+    '@node-core/platform-vercel',
+    '@node-core/platform-cloudflare',
+  ],
   outputFileTracingIncludes: {
     // Twoslash needs TypeScript declarations to function, and, by default, Next.js
     // strips them for brevity. Therefore, they must be explicitly included.
@@ -81,8 +80,25 @@ const nextConfig = {
     // Faster Development Servers with Turbopack
     turbopackFileSystemCacheForDev: true,
   },
-  deploymentId: await getDeploymentId(),
+  // Provide Turbopack Aliases for Platform Resolution
+  turbopack: { resolveAlias: platform.aliases },
+  // Provide Webpack Aliases for Platform Resolution. The active deployment
+  // target is also surfaced to the resolver via `conditionNames` so that
+  // `#platform/*` subpath imports in `package.json` pick the matching
+  // branch when webpack bundles server code.
+  webpack: ({ resolve, ...config }) => ({
+    ...config,
+    resolve: {
+      ...resolve,
+      alias: { ...resolve.alias, ...platform.aliases },
+      conditionNames: resolve.conditionNames
+        .concat(DEPLOY_TARGET)
+        .filter(Boolean),
+    },
+  }),
+  ...(await platform.nextConfig?.()),
 };
 
 const withNextIntl = createNextIntlPlugin('./i18n.tsx');
+
 export default withNextIntl(nextConfig);

apps/site/next.constants.mjs

@@ -6,13 +6,18 @@
 export const IS_DEV_ENV = process.env.NODE_ENV === 'development';
 
 /**
- * This is used for telling Next.js if the Website is deployed on Vercel
+ * Identifies the deployment platform the site is being built for.
  *
- * Can be used for conditionally enabling features that we know are Vercel only
+ * Set by the deployment wrapper at build time: `vercel.json`'s `buildCommand`
+ * sets `vercel`, `open-next.config.ts`'s `buildCommand` sets `cloudflare`.
+ * Unset for standalone builds (local dev, static export).
  *
- * @see https://vercel.com/docs/projects/environment-variables/system-environment-variables#VERCEL_ENV
+ * The `NEXT_PUBLIC_` prefix makes Next.js inline the value at build time,
+ * enabling dead-code elimination of platform-specific branches.
+ *
+ * @type {'vercel' | 'cloudflare' | undefined}
  */
-export const VERCEL_ENV = process.env.VERCEL_ENV || undefined;
+export const DEPLOY_TARGET = process.env.NEXT_PUBLIC_DEPLOY_TARGET;
 
 /**
  * This is used for telling Next.js to do a Static Export Build of the Website
@@ -38,20 +43,14 @@ export const ENABLE_STATIC_EXPORT_LOCALE =
   process.env.NEXT_PUBLIC_STATIC_EXPORT_LOCALE === true;
 
 /**
- * This is used for any place that requires the full canonical URL path for the Node.js Website (and its deployment), such as for example, the Node.js RSS Feed.
- *
- * This variable can either come from the Vercel Deployment as `NEXT_PUBLIC_VERCEL_URL` or from the `NEXT_PUBLIC_BASE_URL` Environment Variable that is manually defined
- * by us if necessary. Otherwise it will fallback to the default Node.js Website URL.
- *
- * @TODO: We should get rid of needing to rely on `VERCEL_URL` for deployment URL.
+ * The full canonical URL of the deployed Website (used e.g. for the RSS feed).
  *
- * @see https://vercel.com/docs/concepts/projects/environment-variables/system-environment-variables#framework-environment-variables
+ * Platform-specific base URLs (such as Vercel's `VERCEL_URL`) are inlined into
+ * `NEXT_PUBLIC_BASE_URL` at build time by each platform's `next.platform.config.mjs`,
+ * keeping this module free of platform-specific branches.
  */
-export const BASE_URL = process.env.NEXT_PUBLIC_BASE_URL
-  ? process.env.NEXT_PUBLIC_BASE_URL
-  : process.env.VERCEL_URL
-    ? `https://${process.env.VERCEL_URL}`
-    : 'https://nodejs.org';
+export const BASE_URL =
+  process.env.NEXT_PUBLIC_BASE_URL || 'https://nodejs.org';
 
 /**
  * This is used for any place that requires the Node.js distribution URL (which by default is nodejs.org/dist)

apps/site/next.image.config.mjs

@@ -1,4 +1,3 @@
-import { OPEN_NEXT_CLOUDFLARE } from './next.constants.cloudflare.mjs';
 import { ENABLE_STATIC_EXPORT } from './next.constants.mjs';
 
 const remotePatterns = [
@@ -9,18 +8,16 @@ const remotePatterns = [
   'https://website-assets.oramasearch.com/**',
 ];
 
-export const getImagesConfig = () => {
-  if (OPEN_NEXT_CLOUDFLARE) {
-    // If we're building for the Cloudflare deployment we want to use the custom cloudflare image loader
-    //
-    // Important: The custom loader ignores `remotePatterns` as those are configured as allowed source origins
-    //            (https://developers.cloudflare.com/images/transform-images/sources/)
-    //            in the Cloudflare dashboard itself instead (to the exact same values present in `remotePatterns` above).
-    //
-    return {
-      loader: 'custom',
-      loaderFile: './cloudflare/image-loader.ts',
-    };
+/**
+ * Returns the Next.js `images` configuration, preferring any platform-provided
+ * override (e.g. Cloudflare's custom loader) over the default remotePatterns +
+ * static-export unoptimized defaults.
+ *
+ * @param {import('next').NextConfig['images']} [platformImagesOverride]
+ */
+export const getImagesConfig = platformImagesOverride => {
+  if (platformImagesOverride) {
+    return platformImagesOverride;
   }
 
   return {

apps/site/next.platform.config.d.ts

@@ -0,0 +1,27 @@
+import type { HighlighterOptions } from '@node-core/rehype-shiki';
+import type { NextConfig } from 'next';
+
+type PlatformMdxConfig = Pick<HighlighterOptions, 'wasm' | 'twoslash'>;
+type PlatformNextConfig = Pick<NextConfig, 'deploymentId' | 'env'>;
+
+/**
+ * Shared platform-config contract consumed by `apps/site/next.config.mjs`
+ * and implemented by each `@node-core/platform-<target>` package.
+ *
+ * `nextConfig` and `images` are async thunks so that platform modules
+ * that depend on Node-only tooling (e.g. `@opennextjs/cloudflare`,
+ * `require.resolve`) can keep those imports out of the module's
+ * top-level. Webpack bundles the top level of this module into the
+ * server output; deferring heavy work into function bodies keeps the
+ * worker runtime free of build-only code.
+ */
+export type PlatformConfig = {
+  aliases?: Record<string, string>;
+  images?: () => Promise<NextConfig['images']>;
+  mdx?: PlatformMdxConfig;
+  nextConfig?: () => Promise<PlatformNextConfig>;
+};
+
+declare const config: PlatformConfig;
+
+export default config;