refactor: consolidate platform detection into NEXT_PUBLIC_DEPLOY_TARGET

ovflowd · ovflowd · commit d7b6e7e5ce2d · 2026-04-23T13:07:30.000-03:00
Platform detection in apps/site was spread across three different
mechanisms: `VERCEL_ENV`, `OPEN_NEXT_CLOUDFLARE`, and a runtime
`'Cloudflare' in global` check in the MDX plugin. Each one carried its
own caveats (the global check blocked tree-shaking; the two env vars
couldn't be compared to "is this build neutral / Vercel / Cloudflare?"
uniformly), and Vercel analytics were imported eagerly in the root
layout even on Cloudflare builds.

Replace all three with a single `NEXT_PUBLIC_DEPLOY_TARGET` env var set
by each deployment wrapper (`vercel.json` -&gt; `vercel`,
`open-next.config.ts` -&gt; `cloudflare`). The `NEXT_PUBLIC_` prefix lets
Next.js inline the value at build time so platform-specific branches are
dead-code-eliminated from non-matching bundles.

Extract the Vercel Analytics + SpeedInsights injection into a
`platform/body-end` slot. The core layout renders `&lt;BodyEnd /&gt;` and the
slot's dynamic import resolves only on Vercel builds, so the Vercel
modules no longer ship to Cloudflare.
diff --git a/apps/site/app/[locale]/layout.tsx b/apps/site/app/[locale]/layout.tsx
@@ -1,12 +1,10 @@
 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 BodyEnd from '#site/platform/body-end';
 import { ThemeProvider } from '#site/providers/themeProvider';
 
 import type { FC, PropsWithChildren } from 'react';
@@ -46,12 +44,7 @@ const RootLayout: FC<RootLayoutProps> = async ({ children, params }) => {
           href="https://social.lfx.dev/@nodejs"
         />
 
-        {VERCEL_ENV && (
-          <>
-            <Analytics />
-            <SpeedInsights />
-          </>
-        )}
+        <BodyEnd />
       </body>
     </html>
   );
diff --git a/apps/site/instrumentation.ts b/apps/site/instrumentation.ts
@@ -1,6 +1,5 @@
 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
+  if (process.env.NEXT_PUBLIC_DEPLOY_TARGET === 'vercel') {
     const { registerOTel } = await import('@vercel/otel');
     registerOTel({ serviceName: 'nodejs-org' });
   }
diff --git a/apps/site/mdx/plugins.mjs b/apps/site/mdx/plugins.mjs
@@ -9,12 +9,6 @@ import readingTime from 'remark-reading-time';
 
 import remarkTableTitles from '../util/table';
 
-// 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;
-
 // 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.
@@ -23,10 +17,10 @@ const singletonShiki = await rehypeShikiji({
   // 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,
+  wasm: process.env.NEXT_PUBLIC_DEPLOY_TARGET !== 'cloudflare',
 
   // TODO(@avivkeller): Find a way to enable Twoslash w/ a VFS on Cloudflare
-  twoslash: !OPEN_NEXT_CLOUDFLARE,
+  twoslash: process.env.NEXT_PUBLIC_DEPLOY_TARGET !== 'cloudflare',
 });
 
 /**
diff --git a/apps/site/next.config.mjs b/apps/site/next.config.mjs
@@ -1,21 +1,24 @@
 '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 {
+  BASE_PATH,
+  DEPLOY_TARGET,
+  ENABLE_STATIC_EXPORT,
+} 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();
+  if (DEPLOY_TARGET !== 'cloudflare') {
+    return undefined;
   }
 
-  return undefined;
+  // 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();
 };
 
 /** @type {import('next').NextConfig} */
diff --git a/apps/site/next.constants.cloudflare.mjs b/apps/site/next.constants.cloudflare.mjs
diff --git a/apps/site/next.constants.mjs b/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
diff --git a/apps/site/next.image.config.mjs b/apps/site/next.image.config.mjs
@@ -1,5 +1,4 @@
-import { OPEN_NEXT_CLOUDFLARE } from './next.constants.cloudflare.mjs';
-import { ENABLE_STATIC_EXPORT } from './next.constants.mjs';
+import { DEPLOY_TARGET, ENABLE_STATIC_EXPORT } from './next.constants.mjs';
 
 const remotePatterns = [
   'https://avatars.githubusercontent.com/**',
@@ -10,7 +9,7 @@ const remotePatterns = [
 ];
 
 export const getImagesConfig = () => {
-  if (OPEN_NEXT_CLOUDFLARE) {
+  if (DEPLOY_TARGET === '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
diff --git a/apps/site/open-next.config.ts b/apps/site/open-next.config.ts
@@ -20,7 +20,8 @@ const cloudflareConfig = defineCloudflareConfig({
 
 const openNextConfig: OpenNextConfig = {
   ...cloudflareConfig,
-  buildCommand: 'pnpm build --webpack',
+  buildCommand:
+    'cross-env NEXT_PUBLIC_DEPLOY_TARGET=cloudflare pnpm build --webpack',
   cloudflare: {
     skewProtection: { enabled: true },
   },
diff --git a/apps/site/package.json b/apps/site/package.json
@@ -6,7 +6,7 @@
     "build": "cross-env NODE_NO_WARNINGS=1 next build",
     "build:blog-data": "cross-env NODE_NO_WARNINGS=1 node ./scripts/blog-data/index.mjs",
     "build:blog-data:watch": "node --watch --watch-path=pages/en/blog ./scripts/blog-data/index.mjs",
-    "cloudflare:build:worker": "OPEN_NEXT_CLOUDFLARE=true opennextjs-cloudflare build",
+    "cloudflare:build:worker": "opennextjs-cloudflare build",
     "cloudflare:deploy": "opennextjs-cloudflare deploy",
     "cloudflare:preview": "wrangler dev",
     "predeploy": "node --run build:blog-data",
diff --git a/apps/site/platform/body-end.tsx b/apps/site/platform/body-end.tsx
@@ -0,0 +1,17 @@
+/**
+ * Per-platform "body end" slot. Deployment targets can inject DOM at the
+ * end of the document body (analytics, tracking scripts, etc.) without
+ * adding platform-specific imports to the core layout.
+ *
+ * `NEXT_PUBLIC_DEPLOY_TARGET` is inlined by Next.js at build time, so on
+ * non-matching platforms the dynamic import is unreachable and tree-shaken
+ * out of the bundle — the Vercel modules never ship to Cloudflare builds.
+ */
+export default async function BodyEnd() {
+  if (process.env.NEXT_PUBLIC_DEPLOY_TARGET === 'vercel') {
+    const { default: VercelBodyEnd } = await import('./body-end.vercel');
+    return <VercelBodyEnd />;
+  }
+
+  return null;
+}
diff --git a/apps/site/platform/body-end.vercel.tsx b/apps/site/platform/body-end.vercel.tsx
@@ -0,0 +1,11 @@
+import { Analytics } from '@vercel/analytics/react';
+import { SpeedInsights } from '@vercel/speed-insights/next';
+
+const VercelBodyEnd = () => (
+  <>
+    <Analytics />
+    <SpeedInsights />
+  </>
+);
+
+export default VercelBodyEnd;
diff --git a/apps/site/turbo.json b/apps/site/turbo.json
@@ -9,6 +9,7 @@
       "env": [
         "VERCEL_ENV",
         "VERCEL_URL",
+        "NEXT_PUBLIC_DEPLOY_TARGET",
         "NEXT_PUBLIC_STATIC_EXPORT",
         "NEXT_PUBLIC_STATIC_EXPORT_LOCALE",
         "NEXT_PUBLIC_BASE_URL",
@@ -36,6 +37,7 @@
       "env": [
         "VERCEL_ENV",
         "VERCEL_URL",
+        "NEXT_PUBLIC_DEPLOY_TARGET",
         "NEXT_PUBLIC_STATIC_EXPORT",
         "NEXT_PUBLIC_STATIC_EXPORT_LOCALE",
         "NEXT_PUBLIC_BASE_URL",
@@ -57,6 +59,7 @@
       "env": [
         "VERCEL_ENV",
         "VERCEL_URL",
+        "NEXT_PUBLIC_DEPLOY_TARGET",
         "NEXT_PUBLIC_STATIC_EXPORT",
         "NEXT_PUBLIC_STATIC_EXPORT_LOCALE",
         "NEXT_PUBLIC_BASE_URL",
@@ -83,6 +86,7 @@
       "env": [
         "VERCEL_ENV",
         "VERCEL_URL",
+        "NEXT_PUBLIC_DEPLOY_TARGET",
         "NEXT_PUBLIC_STATIC_EXPORT",
         "NEXT_PUBLIC_STATIC_EXPORT_LOCALE",
         "NEXT_PUBLIC_BASE_URL",
diff --git a/apps/site/vercel.json b/apps/site/vercel.json
@@ -1,5 +1,6 @@
 {
   "$schema": "https://openapi.vercel.sh/vercel.json",
   "installCommand": "pnpm install --prod --frozen-lockfile",
+  "buildCommand": "cross-env NEXT_PUBLIC_DEPLOY_TARGET=vercel pnpm build",
   "ignoreCommand": "[[ \"$VERCEL_GIT_COMMIT_REF\" =~ \"^dependabot/.*\" || \"$VERCEL_GIT_COMMIT_REF\" =~ \"^gh-readonly-queue/.*\" ]]"
 }
diff --git a/docs/cloudflare-build-and-deployment.md b/docs/cloudflare-build-and-deployment.md
@@ -49,7 +49,7 @@ Additionally, when deploying, an extra `CF_WORKERS_SCRIPTS_API_TOKEN` environmen
 
 ### Image loader
 
-When deployed on the Cloudflare network a custom image loader is required. We set such loader in the Next.js config file when the `OPEN_NEXT_CLOUDFLARE` environment variable is set (which indicates that we're building the application for the Cloudflare deployment).
+When deployed on the Cloudflare network a custom image loader is required. We set such loader in the Next.js config file when `NEXT_PUBLIC_DEPLOY_TARGET=cloudflare` (which indicates that we're building the application for the Cloudflare deployment; the variable is set by the OpenNext `buildCommand` in [`open-next.config.ts`](../apps/site/open-next.config.ts)).
 
 The custom loader can be found at [`site/cloudflare/image-loader.ts`](../apps/site/cloudflare/image-loader.ts).
 

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,5 @@`
`1`	`1`	`export async function register() {`
`2`		`- if (!('Cloudflare' in globalThis)) {`
`3`		`- // Note: we don't need to set up the Vercel OTEL if the application is running on Cloudflare`
	`2`	`+ if (process.env.NEXT_PUBLIC_DEPLOY_TARGET === 'vercel') {`
`4`	`3`	`const { registerOTel } = await import('@vercel/otel');`
`5`	`4`	`registerOTel({ serviceName: 'nodejs-org' });`
`6`	`5`	`}`