Skip to content

Conversation

@kraenhansen
Copy link
Collaborator

@kraenhansen kraenhansen commented Nov 2, 2025

Shipping a prebuilt Xcframework on NPM is harder than it should be.

It may contain internal symbolic links when it wraps a versioned MacOS framework.
These are stripped from the archive uploaded to the registry, meaning it's broken when downloaded again 🫠

Merging this PR will:

  • Reconstruct internal symbolic links of Apple frameworks (using a single version directory as heuristic to guess the "correct" paths of the symlinks).
  • Update private packages files and .gitignore of the repo to enable a npm pack (although not actively being used though).
  • Restore weak-node-api symlinks as part of linking Node-API addons for Apple platforms.

There's some information about the "current" version which could be derived from the surrounding Xcframework to support Apple frameworks shipping multiple versions, but I'll leave that for now to keep things "simple".


Note

Reconstructs missing symlinks in Apple versioned frameworks (including weak-node-api) and updates package metadata/scripts for packaging.

  • Apple linking:
    • Add restoreFrameworkLinks(frameworkPath) to rebuild Versions/Current and binary symlinks for versioned frameworks.
    • Invoke restoreFrameworkLinks in linkVersionedFramework and from CLI after linking to fix weak-node-api.xcframework slices.
    • Extend tests in apple.test.ts to cover restoring symlinks and flat-framework error case.
  • CLI:
    • Update program.ts to restore weak-node-api framework symlinks when --apple is used.
  • Packages/metadata:
    • Add version and files fields and new scripts to packages/node-addon-examples and packages/node-tests; include prebuilt .apple.node/.android.node artifacts.
    • Update packages/ferric-example with version and files entries.
    • Adjust .gitignore to include build/ in node-addon-examples.
    • Reflect versions in lockfile for private packages.

Written by Cursor Bugbot for commit 178c7ea. This will update automatically on new commits. Configure here.

@kraenhansen kraenhansen self-assigned this Nov 2, 2025
@kraenhansen kraenhansen added Apple 🍎 Anything related to the Apple platform (iOS, macOS, Cocoapods, Xcode, XCFrameworks, etc.) Host 🏡 Our `react-native-node-api-modules` package Linking 🔗 Discovering and copying prebuilds from packages into the host labels Nov 2, 2025
Copy link

@cursor cursor bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the final PR Bugbot will review for you during this billing cycle

Your free Bugbot reviews will reset on December 2

Details

Your team is on the Bugbot Free tier. On this plan, Bugbot will review limited PRs each billing cycle for each member of your team.

To receive Bugbot reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

});
const versionDirectoryPaths = versionDirectoryEntries
.filter((dirent) => dirent.isDirectory())
.map((dirent) => path.join(dirent.parentPath, dirent.name));
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: Dirent Path Access Incompatibility Causes Runtime Errors

The code uses dirent.parentPath to construct a path. This property isn't reliably available on fs.Dirent objects returned by non-recursive fs.readdir, which can lead to runtime errors, especially on older Node.js versions. The versionsPath variable is already in scope for this purpose.

Fix in Cursor Fix in Web

@kraenhansen kraenhansen merged commit e9ca2aa into main Nov 2, 2025
8 checks passed
@kraenhansen kraenhansen deleted the kh/restore-apple-framework-symlinks branch November 2, 2025 15:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Apple 🍎 Anything related to the Apple platform (iOS, macOS, Cocoapods, Xcode, XCFrameworks, etc.) Host 🏡 Our `react-native-node-api-modules` package Linking 🔗 Discovering and copying prebuilds from packages into the host

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants