fix: Windows compatibility - bun as optional dep, cross-env for examples #145

ochafik · 2025-12-12T16:23:20Z

Summary

Fixes #142 - Windows PowerShell install failure.

This PR supersedes #144, taking a more comprehensive approach:

Bun as optional dependency - No global Bun installation required
Cross-platform example builds - Examples now build on Windows using cross-env

Changes

Bun setup (no global install needed):

Add @oven/bun-* platform-specific packages as optionalDependencies
Create scripts/setup-bun.mjs to set up bun binary from optional deps
Handle Windows ARM64 by downloading x64-baseline (runs via emulation)
Remove setup-bun action from all CI workflows

Cross-platform fixes:

Use cross-env for environment variables in example build scripts
Fix Windows-incompatible INPUT=... and NODE_ENV=... syntax
Enable examples:build on all platforms including Windows

CI improvements:

Full cross-platform CI matrix: Linux x64/ARM64, Windows x64/ARM64, macOS ARM64, Windows WSL
All platforms now build examples
test-git-install verifies package works when installed from git

How Bun setup works

npm install automatically installs the platform-appropriate @oven/bun-* package
The prepare script runs setup-bun.mjs which finds the binary and links it to node_modules/.bin/bun
On Windows ARM64 (no native package), the script downloads x64-baseline which runs via emulation

Developer experience

Before	After
Install Bun globally first	Just `npm install`
Examples fail on Windows	Examples build on all platforms
CI needs `setup-bun` action	CI just runs `npm install`

Test plan

All CI jobs pass (Linux x64/ARM64, Windows x64/ARM64, macOS ARM64, WSL)
npm install works in fresh environment
npm run build and npm run examples:build work on all platforms
npm test passes

Closes #144

🤖 Generated with Claude Code

scripts/setup-bun.mjs

pkg-pr-new · 2025-12-12T16:45:46Z

Open in StackBlitz

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/ext-apps@145

commit: db41042

ochafik · 2025-12-12T18:06:14Z

@claude review this PR throroughly, highlight any potential native compatibility issue, security considerations, etc.

jonathanhefner · 2025-12-12T22:21:53Z

examples/basic-host/package.json

    "@types/react": "^19.2.2",
    "@types/react-dom": "^19.2.2",
    "@vitejs/plugin-react": "^4.3.4",
-    "bun": "^1.3.2",


Is this dependency causing a problem on Windows?

In 9f8d00e, I explicitly added bun as a dependency to the examples in order to improve on-ramping (users only have to run npm install).

(I see the postinstall script added to package.json, but I'm still unclear on the problem that this dependency is causing.)

The bun npm package was removed from examples' devDependencies (in the parent branch #144) because it was causing npm install to fail on Windows ARM64 - there's no native ARM64 binary for Bun on Windows yet, so the package's postinstall script throws "Unsupported platform: win32 arm64".

This PR takes a different approach: instead of relying on the bun npm package in each workspace, we add Bun's platform-specific packages (@oven/bun-darwin-aarch64, @oven/bun-linux-x64, etc.) as optionalDependencies in the root package.json. This has several benefits:

Windows ARM64 support: Our setup-bun.mjs script handles this by downloading the x64-baseline binary, which runs via emulation

Single source of truth: Bun version is managed in one place (root package.json)

Works with npm install: Users still just run npm install - the prepare script sets up bun automatically

The user experience is the same (or better) - npm install just works on all platforms including Windows ARM64.

jonathanhefner

It's unfortunate that the setup-bun.mjs and run-bun.mjs scripts are necessary, but if it works, it works.

Fixes #142 - Windows PowerShell install bug Changes: - Replace single quotes with escaped double quotes in generate:schemas (cmd.exe passes single quotes literally, breaking prettier glob matching) - Simplify prettier scripts: remove redundant --ignore-path flags (prettier auto-loads .gitignore and .prettierignore by default) - Remove $(pwd) from prettier scripts (bash-only syntax) - Add cross-platform CI matrix: Linux x64, Windows x64, macOS ARM64, macOS x64 - Use shell: bash for grep commands in CI (not available in Windows cmd.exe) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

The bun npm package tries to install platform-specific binaries which fails on Windows CI. Since bun is installed via oven-sh/setup-bun action in CI (and developers install it globally), we don't need the npm package. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

The examples use `INPUT=mcp-app.html vite build` which is bash syntax for setting environment variables. This doesn't work on Windows cmd.exe. Since examples aren't published to npm, we can skip building them on Windows. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Git on Windows auto-converts line endings to CRLF, causing prettier to report formatting issues. Force LF for all text files. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

This verifies that `npm install git+https://...` works on all platforms, which triggers the prepare script and requires bun to be available. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

- Added ubuntu-24.04-arm (Linux ARM64) - Added windows-11-arm (Windows ARM64) Note: WSL is not available on GitHub-hosted runners (requires nested virtualization which isn't supported). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

The oven-sh/setup-bun action fails with 404 when trying to download Bun for Windows ARM64. Re-enable when Bun adds proper support. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Uses Vampire/setup-wsl action to install Ubuntu-24.04 in WSL and run the full build/test cycle. This tests the Linux-in-Windows scenario that was reported in issue #142. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

The pkg-pr-new publish workflow was missing bun setup, causing "bun: not found" errors during npm ci (which triggers prepare script). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Windows ARM64 can run x64 binaries via emulation. Use bun-download-url to force x64-baseline build since native ARM64 Bun isn't available yet. Reference: oven-sh/bun#9824 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

The macos-13 based runner images are now retired. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Documents that Bun is required for development, with platform-specific install commands in collapsible sections. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

- Add @oven/bun-* platform packages as optionalDependencies - Create postinstall script to set up bun binary from optional deps - Handle Windows ARM64 by downloading x64-baseline for emulation - Remove setup-bun from CI workflows (npm install handles it now) - Remove manual Bun install instructions from docs This alternative approach eliminates the need for global Bun installation or setup-bun action in CI. npm install automatically installs the platform-appropriate bun binary. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

- Add cross-env to devDependencies - Update all example package.json scripts to use cross-env for INPUT and NODE_ENV - Enable examples:build on Windows in CI (no longer Unix-only) - Add examples:build to WSL CI job 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Address github-code-quality bot comments. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

During npm install's prepare hook, node_modules/.bin is not in PATH, so calling 'bun' directly fails. The new run-bun.mjs wrapper finds bun at node_modules/.bin/bun and runs it with the correct path. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

- Add setup-bun action to build and test-git-install jobs - Disable Windows ARM64 (Bun doesn't support this platform) - Add bun installation to WSL build 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

- Remove 'bun' from devDependencies (its postinstall fails on Windows ARM64) - Add libc detection (glibc vs musl) to setup-bun.mjs - Only try compatible binaries based on detected libc - Re-enable Windows ARM64 in CI (now uses x64 emulation fallback) - Remove setup-bun action from CI (no longer needed) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

github-code-quality bot found potential problems Dec 12, 2025

View reviewed changes

scripts/setup-bun.mjs Fixed Show fixed Hide fixed

scripts/setup-bun.mjs Fixed Show fixed Hide fixed

github-code-quality bot found potential problems Dec 12, 2025

View reviewed changes

scripts/setup-bun.mjs Fixed Show fixed Hide fixed

scripts/setup-bun.mjs Fixed Show fixed Hide fixed

ochafik changed the title ~~feat: add bun as optional dependency (alternative to #144)~~ fix: Windows compatibility - bun as optional dep, cross-env for examples Dec 12, 2025

ochafik marked this pull request as ready for review December 12, 2025 17:20

ochafik mentioned this pull request Dec 12, 2025

fix: Windows compatibility for npm scripts and cross-platform CI #144

Closed

4 tasks

ochafik requested a review from jonathanhefner December 12, 2025 19:41

ochafik added the bugfix label Dec 12, 2025

jonathanhefner reviewed Dec 12, 2025

View reviewed changes

ochafik requested a review from jonathanhefner December 15, 2025 12:05

jonathanhefner previously approved these changes Dec 15, 2025

View reviewed changes

ochafik and others added 18 commits December 16, 2025 13:43

ci: fix WSL build - install unzip for Bun installer

b7b8f75

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

ci: add setup-bun to publish.yml workflow

765736f

The pkg-pr-new publish workflow was missing bun setup, causing "bun: not found" errors during npm ci (which triggers prepare script). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

ci: remove macOS x64 (macos-13 runner retired)

9cbb4dc

The macos-13 based runner images are now retired. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

docs: add Bun installation instructions per platform

f80b167

Documents that Bun is required for development, with platform-specific install commands in collapsible sections. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

docs: note Bun requirement in README examples section

93f7d98

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

chore: add debug logging to setup-bun script

c10ed54

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

chore: force stdout flush in setup-bun for CI debugging

e81518d

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

chore: add more debugging to setup-bun

a539ae4

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

ochafik and others added 5 commits December 16, 2025 13:44

chore: remove accidental test artifacts

4535606

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

chore: run setup-bun in prepare script (before build)

ea668b3

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

chore: remove unused imports in setup-bun.mjs

e60adf6

Address github-code-quality bot comments. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

ochafik dismissed jonathanhefner’s stale review via 69b8eba December 16, 2025 13:44

ochafik force-pushed the ochafik/fix-issue-142-bun-optional-deps branch from 395bdeb to 69b8eba Compare December 16, 2025 13:44

ochafik and others added 3 commits December 16, 2025 13:47

ci: simplify WSL build - let setup-bun.mjs handle bun installation

db41042

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

ochafik merged commit 9748622 into main Dec 16, 2025
19 checks passed

ochafik mentioned this pull request Dec 16, 2025

feat: merge main + server helpers with _meta.ui support #166

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: Windows compatibility - bun as optional dep, cross-env for examples #145

fix: Windows compatibility - bun as optional dep, cross-env for examples #145

ochafik commented Dec 12, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pkg-pr-new bot commented Dec 12, 2025 •

edited

Loading

Uh oh!

ochafik commented Dec 12, 2025

Uh oh!

jonathanhefner Dec 12, 2025

Uh oh!

jonathanhefner Dec 12, 2025

Uh oh!

ochafik Dec 13, 2025

Uh oh!

jonathanhefner left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fix: Windows compatibility - bun as optional dep, cross-env for examples #145

fix: Windows compatibility - bun as optional dep, cross-env for examples #145

Conversation

ochafik commented Dec 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

How Bun setup works

Developer experience

Test plan

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pkg-pr-new bot commented Dec 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ochafik commented Dec 12, 2025

Uh oh!

jonathanhefner Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

jonathanhefner Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

ochafik Dec 13, 2025

Choose a reason for hiding this comment

Uh oh!

jonathanhefner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ochafik commented Dec 12, 2025 •

edited

Loading

pkg-pr-new bot commented Dec 12, 2025 •

edited

Loading