`isBrowserEnv()` stops tree shaking in bundlers and leaks node specific code to browser bundles

[joshuaellis]

Describe the bug

Description

#3704 introduced ENV_TARGET as a compile-time define so build tools can tree-shake environment-specific code. It wrapped createScriptNode/loadScriptNode in sdk/src/node.ts and the loadEntryDom/loadEntryNode branch in runtime-core/src/utils/load.ts with ENV_TARGET guards. However, there are ~7 remaining isBrowserEnv() call sites in runtime-core that were not updated. These were originally added in #2482 for SSR support. Because isBrowserEnv is a function call, bundlers cannot statically evaluate it and the dead branches survive tree-shaking – see module-federation/vite#274.

Proposal

Change isBrowserEnv from a function to a top-level const that respects ENV_TARGET:

declare const ENV_TARGET: 'web' | 'node';

export const isBrowserEnv = typeof ENV_TARGET !== 'undefined'
  ? ENV_TARGET === 'web'
  : typeof window !== 'undefined' && typeof window.document !== 'undefined';

When a build tool defines ENV_TARGET = 'web' (via webpack DefinePlugin, rspack, or Vite config.define), the bundler collapses this to:

export const isBrowserEnv = true;

Bundlers can propagate top-level constants. Every if(isBrowserEnv) becomes if(true), and the else branches are dead-code-eliminated across the entire runtime. When ENV_TARGET is not defined, behavior is unchanged — it falls back to the runtime typeof window check.

Notes

I imagine this is considered a breaking change so I didn't want to make the PR without checking first – open to discussion.

Reproduction

module-federation/vite#274

Used Package Manager

pnpm

System Info

System:
    OS: macOS 14.6.1
    CPU: (11) arm64 Apple M3 Pro
    Memory: 57.67 MB / 36.00 GB
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 24.12.0 - /Users/josh.ellis/.nvm/versions/node/v24.12.0/bin/node
    npm: 11.6.2 - /Users/josh.ellis/.nvm/versions/node/v24.12.0/bin/npm
    pnpm: 10.28.2 - /Users/josh.ellis/Library/pnpm/pnpm
    bun: 1.2.13 - /opt/homebrew/bin/bun
  Browsers:
    Chrome: 145.0.7632.68
    Firefox: 147.0.3
    Safari: 17.6

Validations

• Read the docs.
• Read the common issues list.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• Make sure this is a Module federation issue and not a framework-specific issue.
• The provided reproduction is a minimal reproducible example of the bug.

[ScriptedAlchemy]

@cursoragent ensure we covered all locations so tree shake works properly read over git issue

[cursor]

Summary:

• Updated isBrowserEnv to a top-level const honoring ENV_TARGET, with runtime fallback.
• Replaced all isBrowserEnv() call sites across runtime-core, sdk, and bridge with boolean usage so bundlers can tree-shake.
• Adjusted sdk tests and README to reflect the boolean API.

Tests:

• ✅ pnpm exec nx format:check (after install)
• ✅ pnpm exec nx run-many --targets=build --projects=tag:type:pkg --parallel=4 --skip-nx-cache
• ✅ pnpm exec nx run-many --targets=build --projects=tag:type:pkg --parallel=4
• ❌ CI=1 pnpm exec nx affected -t test --parallel=3 --exclude='*,!tag:type:pkg'
  • Failure: enhanced:test (Module status must be unlinked) in packages/enhanced/test/ConfigTestCases.basictest.rstest.ts

Notes:

• Initial pnpm exec nx affected -t test ... (non-CI) hung because packages/bridge/vue3-bridge uses vitest watch; I terminated it and reran in CI mode.
• sdk:test passed but logs a console.warn from getResourceUrl (existing behavior).

Commands run:

1. git status -sb
2. git diff --stat
3. git add .
4. git commit -m "fix(sdk): make isBrowserEnv tree-shakable"
5. git push -u origin cursor/tree-shaking-coverage-5fd5
6. git rev-parse --git-dir && git rev-parse --git-common-dir
7. pnpm exec nx format:check (failed: nx not found)
8. pnpm run setup:codex
9. pnpm exec nx format:check
10. pnpm exec nx run-many --targets=build --projects=tag:type:pkg --parallel=4 --skip-nx-cache
11. pnpm exec nx run-many --targets=build --projects=tag:type:pkg --parallel=4
12. pnpm exec nx affected -t test --parallel=3 --exclude='*,!tag:type:pkg' (hung)
13. ps -p 7781 (ran twice)
14. ps -ef | rg "nx|pnpm|vitest|jest"
15. ps -ef | rg "nx affected|vitest|jest" (ran four times)
16. ps -o pid,ppid,cmd -p 10443,10444
17. readlink -f /proc/10444/cwd
18. sleep 30 (ran twice)
19. sleep 60
20. kill 7781 7936 10443 10444
21. CI=1 pnpm exec nx affected -t test --parallel=3 --exclude='*,!tag:type:pkg'
22. git status -sb

Skipped checks:

• None. All required checks were attempted; enhanced:test failed as noted above.

 

[ScriptedAlchemy]

try the canary in pkg pr new. #4454

[joshuaellis]

Approved the PR (not that my approval is worth much lol)

EDIT: thanks for the quick turn around!