fix(sdk): add isBrowserEnvValue for tree-shaking

.changeset/breezy-walls-burn.md

@@ -0,0 +1,8 @@
+---
+"@module-federation/sdk": minor
+"@module-federation/runtime-core": minor
+---
+
+Add `isBrowserEnvValue` as a tree-shakable ENV_TARGET-aware constant while
+preserving the `isBrowserEnv()` function. Internal callers use the constant to
+enable bundler dead-code elimination without breaking the public API.

packages/bridge/bridge-react/src/lazy/utils.ts

@@ -1,4 +1,7 @@
-import { isBrowserEnv, composeKeyWithSeparator } from '@module-federation/sdk';
+import {
+  isBrowserEnvValue,
+  composeKeyWithSeparator,
+} from '@module-federation/sdk';
 import logger from './logger';
 import {
   DOWNGRADE_KEY,
@@ -153,7 +156,7 @@ export async function fetchData(
       _id: id,
     });
   };
-  if (isBrowserEnv()) {
+  if (isBrowserEnvValue) {
     const dataFetchItem = getDataFetchItem(id);
     if (!dataFetchItem) {
       throw new Error(`dataFetchItem not found, id: ${id}`);

packages/runtime-core/src/core.ts

@@ -1,4 +1,4 @@
-import { isBrowserEnv } from '@module-federation/sdk';
+import { isBrowserEnvValue } from '@module-federation/sdk';
 import type {
   CreateScriptHookReturn,
   GlobalModuleInfo,
@@ -185,7 +185,7 @@ export class ModuleFederation {
       plugins,
       remotes: [],
       shared: {},
-      inBrowser: isBrowserEnv(),
+      inBrowser: isBrowserEnvValue,
     };
 
     this.name = userOptions.name;

packages/runtime-core/src/plugins/generate-preload-assets.ts

@@ -4,7 +4,7 @@ import {
   ProviderModuleInfo,
   isManifestProvider,
   getResourceUrl,
-  isBrowserEnv,
+  isBrowserEnvValue,
 } from '@module-federation/sdk';
 import {
   EntryAssets,
@@ -324,7 +324,7 @@ export const generatePreloadAssetsPlugin: () => ModuleFederationRuntimePlugin =
           globalSnapshot,
           remoteSnapshot,
         } = args;
-        if (!isBrowserEnv()) {
+        if (!isBrowserEnvValue) {
           return {
             cssAssets: [],
             jsAssetsWithoutEntry: [],

packages/runtime-core/src/plugins/snapshot/SnapshotHandler.ts

@@ -4,7 +4,7 @@ import {
   ModuleInfo,
   generateSnapshotFromManifest,
   isManifestProvider,
-  isBrowserEnv,
+  isBrowserEnvValue,
 } from '@module-federation/sdk';
 import {
   getShortErrorMsg,
@@ -187,7 +187,7 @@ export class SnapshotHandler {
     // global snapshot includes manifest or module info includes manifest
     if (globalRemoteSnapshot) {
       if (isManifestProvider(globalRemoteSnapshot)) {
-        const remoteEntry = isBrowserEnv()
+        const remoteEntry = isBrowserEnvValue
           ? globalRemoteSnapshot.remoteEntry
           : globalRemoteSnapshot.ssrRemoteEntry ||
             globalRemoteSnapshot.remoteEntry ||

packages/runtime-core/src/plugins/snapshot/index.ts

@@ -1,7 +1,7 @@
 import {
   ModuleInfo,
   getResourceUrl,
-  isBrowserEnv,
+  isBrowserEnvValue,
 } from '@module-federation/sdk';
 import { ModuleFederationRuntimePlugin } from '../../type/plugin';
 import {
@@ -26,7 +26,7 @@ export function assignRemoteInfo(
 
   let entryUrl = getResourceUrl(remoteSnapshot, remoteEntryInfo.url);
 
-  if (!isBrowserEnv() && !entryUrl.startsWith('http')) {
+  if (!isBrowserEnvValue && !entryUrl.startsWith('http')) {
     entryUrl = `https:${entryUrl}`;
   }
 

packages/runtime-core/src/remote/index.ts

@@ -1,5 +1,5 @@
 import {
-  isBrowserEnv,
+  isBrowserEnvValue,
   warn,
   composeKeyWithSeparator,
   ModuleInfo,
@@ -426,7 +426,7 @@ export class RemoteHandler {
       }
       // Set the remote entry to a complete path
       if ('entry' in remote) {
-        if (isBrowserEnv() && !remote.entry.startsWith('http')) {
+        if (isBrowserEnvValue && !remote.entry.startsWith('http')) {
           remote.entry = new URL(remote.entry, window.location.origin).href;
         }
       }

packages/runtime-core/src/utils/env.ts

@@ -1,4 +1,8 @@
-export { isBrowserEnv, isDebugMode } from '@module-federation/sdk';
+export {
+  isBrowserEnv,
+  isBrowserEnvValue,
+  isDebugMode,
+} from '@module-federation/sdk';
 
 export function isDevelopmentMode(): boolean {
   return true;

packages/runtime-core/src/utils/load.ts

@@ -2,7 +2,7 @@ import {
   loadScript,
   loadScriptNode,
   composeKeyWithSeparator,
-  isBrowserEnv,
+  isBrowserEnvValue,
 } from '@module-federation/sdk';
 import { DEFAULT_REMOTE_TYPE, DEFAULT_SCOPE } from '../constant';
 import { ModuleFederation } from '../core';
@@ -265,11 +265,11 @@ export async function getRemoteEntry(params: {
         if (res) {
           return res;
         }
-        // Use ENV_TARGET if defined, otherwise fallback to isBrowserEnv, must keep this
+        // Use ENV_TARGET if defined, otherwise fallback to isBrowserEnvValue
         const isWebEnvironment =
           typeof ENV_TARGET !== 'undefined'
             ? ENV_TARGET === 'web'
-            : isBrowserEnv();
+            : isBrowserEnvValue;
 
         return isWebEnvironment
           ? loadEntryDom({

packages/runtime-core/src/utils/tool.ts

@@ -2,7 +2,7 @@ import {
   RemoteWithEntry,
   ModuleInfo,
   RemoteEntryType,
-  isBrowserEnv,
+  isBrowserEnvValue,
   isReactNativeEnv,
 } from '@module-federation/sdk';
 import { Remote, RemoteInfoOptionalVersion } from '../type';
@@ -89,7 +89,11 @@ export function getRemoteEntryInfoFromSnapshot(snapshot: ModuleInfo): {
     type: 'global',
     globalName: '',
   };
-  if (isBrowserEnv() || isReactNativeEnv() || !('ssrRemoteEntry' in snapshot)) {
+  if (
+    isBrowserEnvValue ||
+    isReactNativeEnv() ||
+    !('ssrRemoteEntry' in snapshot)
+  ) {
     return 'remoteEntry' in snapshot
       ? {
           url: snapshot.remoteEntry,

packages/sdk/README.md

@@ -11,7 +11,7 @@
 // The SDK can be used to parse entry strings, encode and decode module names, and generate filenames for exposed modules and shared packages.
 // It also includes a logger for debugging and environment detection utilities.
 // Additionally, it provides a function to generate a snapshot from a manifest and environment detection utilities.
-import { parseEntry, encodeName, decodeName, generateExposeFilename, generateShareFilename, createLogger, isBrowserEnv, isDebugMode, getProcessEnv, generateSnapshotFromManifest } from '@module-federation/sdk';
+import { parseEntry, encodeName, decodeName, generateExposeFilename, generateShareFilename, createLogger, isBrowserEnv, isBrowserEnvValue, isDebugMode, getProcessEnv, generateSnapshotFromManifest } from '@module-federation/sdk';
 
 // Parse an entry string into a RemoteEntryInfo object
 parseEntry('entryString');
@@ -32,7 +32,8 @@ generateShareFilename('packageName', true);
 const logger = createLogger('identifier');
 
 // Check if the current environment is a browser
-isBrowserEnv();
+const inBrowser = isBrowserEnv();
+const inBrowserStatic = isBrowserEnvValue;
 
 // Check if the current environment is in debug mode
 isDebugMode();
@@ -76,9 +77,14 @@ generateSnapshotFromManifest(manifest, options);
 
 ### isBrowserEnv
 
-- Type: `isBrowserEnv()`
+- Type: `isBrowserEnv(): boolean`
 - Checks if the current environment is a browser.
 
+### isBrowserEnvValue
+
+- Type: `isBrowserEnvValue: boolean`
+- Static browser environment flag (tree-shakable when ENV_TARGET is defined).
+
 ### isDebugMode
 
 - Type: `isDebugMode()`

packages/sdk/__tests__/utils.spec.ts

@@ -1,20 +1,31 @@
 import { getResourceUrl } from '../src/utils';
 import { ModuleInfo } from '../src/types';
-import { isBrowserEnv, isReactNativeEnv } from '../src/env';
+import * as env from '../src/env';
 
-jest.mock('../src/env', () => ({
-  isBrowserEnv: jest.fn(),
-  isReactNativeEnv: jest.fn(),
-}));
+jest.mock('../src/env', () => {
+  const mock = {
+    isBrowserEnvValue: false,
+    isBrowserEnv: jest.fn(() => mock.isBrowserEnvValue),
+    isReactNativeEnv: jest.fn(),
+  };
+  return mock;
+});
+
+const mockedEnv = env as unknown as {
+  isBrowserEnvValue: boolean;
+  isBrowserEnv: jest.Mock;
+  isReactNativeEnv: jest.Mock;
+};
 
 describe('getResourceUrl', () => {
   let module: ModuleInfo;
   let sourceUrl: string;
 
   beforeEach(() => {
     sourceUrl = 'test.js';
-    (isBrowserEnv as jest.Mock).mockReset();
-    (isReactNativeEnv as jest.Mock).mockReset();
+    mockedEnv.isBrowserEnvValue = false;
+    mockedEnv.isBrowserEnv.mockClear();
+    mockedEnv.isReactNativeEnv.mockReset();
   });
 
   test('should return url with getPublicPath', () => {
@@ -34,7 +45,7 @@ describe('getResourceUrl', () => {
   test('should return url with publicPath in browser or RN env', () => {
     const publicPath = 'https://public.com/';
     module = { publicPath } as ModuleInfo;
-    (isBrowserEnv as jest.Mock).mockReturnValue(true);
+    mockedEnv.isBrowserEnvValue = true;
     const result = getResourceUrl(module, sourceUrl);
     expect(result).toBe('https://public.com/test.js');
   });
@@ -43,8 +54,8 @@ describe('getResourceUrl', () => {
     const publicPath = 'https://public.com/';
     const ssrPublicPath = 'https://ssr.com/';
     module = { publicPath, ssrPublicPath } as ModuleInfo;
-    (isBrowserEnv as jest.Mock).mockReturnValue(false);
-    (isReactNativeEnv as jest.Mock).mockReturnValue(false);
+    mockedEnv.isBrowserEnvValue = false;
+    mockedEnv.isReactNativeEnv.mockReturnValue(false);
     const result = getResourceUrl(module, sourceUrl);
     expect(result).toBe('https://ssr.com/test.js');
   });

packages/sdk/src/env.ts

@@ -5,10 +5,16 @@ declare global {
   var FEDERATION_DEBUG: string | undefined;
 }
 
+// Declare the ENV_TARGET constant that will be defined by DefinePlugin
+declare const ENV_TARGET: 'web' | 'node';
+
+const isBrowserEnvValue =
+  typeof ENV_TARGET !== 'undefined'
+    ? ENV_TARGET === 'web'
+    : typeof window !== 'undefined' && typeof window.document !== 'undefined';
+
 function isBrowserEnv(): boolean {
-  return (
-    typeof window !== 'undefined' && typeof window.document !== 'undefined'
-  );
+  return isBrowserEnvValue;
 }
 
 function isReactNativeEnv(): boolean {
@@ -19,7 +25,7 @@ function isReactNativeEnv(): boolean {
 
 function isBrowserDebug() {
   try {
-    if (isBrowserEnv() && window.localStorage) {
+    if (isBrowserEnvValue && window.localStorage) {
       return Boolean(localStorage.getItem(BROWSER_LOG_KEY));
     }
   } catch (error) {
@@ -48,4 +54,10 @@ const getProcessEnv = function (): Record<string, string | undefined> {
   return typeof process !== 'undefined' && process.env ? process.env : {};
 };
 
-export { isBrowserEnv, isReactNativeEnv, isDebugMode, getProcessEnv };
+export {
+  isBrowserEnv,
+  isBrowserEnvValue,
+  isReactNativeEnv,
+  isDebugMode,
+  getProcessEnv,
+};

packages/sdk/src/utils.ts

@@ -6,7 +6,7 @@ import {
   SEPARATOR,
   MANIFEST_EXT,
 } from './constant';
-import { getProcessEnv, isBrowserEnv, isReactNativeEnv } from './env';
+import { getProcessEnv, isBrowserEnvValue, isReactNativeEnv } from './env';
 
 const LOG_CATEGORY = '[ Federation Runtime ]';
 
@@ -189,7 +189,11 @@ const getResourceUrl = (module: ModuleInfo, sourceUrl: string): string => {
 
     return `${publicPath}${sourceUrl}`;
   } else if ('publicPath' in module) {
-    if (!isBrowserEnv() && !isReactNativeEnv() && 'ssrPublicPath' in module) {
+    if (
+      !isBrowserEnvValue &&
+      !isReactNativeEnv() &&
+      'ssrPublicPath' in module
+    ) {
       return `${module.ssrPublicPath}${sourceUrl}`;
     }
     return `${module.publicPath}${sourceUrl}`;