NFI Tool - Swift Framework Binding

The NFI (Native Framework Interface) Tool generates JavaScript bindings for Swift .xcframework bundles. It reads the framework's .swiftinterface to understand the public API and produces a ready-to-link NFI<Name>.xcframework that exposes all Swift classes, methods, and properties directly to JavaScript at runtime.

Prerequisites

  • macOS with Xcode installed
  • Python 3.9.6+
  • GYP installed (bash NFITool/scripts/install.sh)
  • A compiled .xcframework built from your Swift Xcode project (with BUILD_LIBRARY_FOR_DISTRIBUTION = YES)

Step 1 — Build Your Swift xcframework

In Xcode, set the following build setting on your framework target:


BUILD_LIBRARY_FOR_DISTRIBUTION = YES

Build the framework for both iOS devices and the iOS Simulator, and then use the xcodebuild -create-xcframework command to generate a .xcframework. The .swiftinterface file generated during this process is required to create the .xcframework.

Step 2 — Configure `config.plist`

Open NFITool/scripts/config.plist and add an entry for your framework:



<key>MyFramework</key>
<dict>
    <!-- Required: tells the tool to use the Swift pipeline -->
    <key>BindingLanguage</key>
    <string>SWIFT</string>

    <!-- Required: the Swift module name (usually matches the framework name) -->
    <key>SwiftModuleName</key>
    <string>MyFramework</string>

    <!-- Required: folder containing your input .xcframework -->
    <key>ThirdPartyRootDir</key>
    <string>/path/to/folder/containing/xcframework</string>

    <!-- Use this if your framework imports other xcframeworks -->
    <key>SwiftDependencies</key>
    <string>/path/to/deps/folder</string>

    <!-- Required: use XCFWKS for full architecture support -->
    <key>Mode</key>
    <string>XCFWKS</string>

    <!-- Required: set to true to include in the build -->
    <key>enabled</key>
    <true/>

    <!-- Required: architectures to build for -->
    <key>SupportedArchs</key>
    <dict>
        <key>Device</key>
        <array>
            <string>arm64</string>
        </array>
        <key>Simulator</key>
        <array>
            <string>x86_64</string>
            <string>arm64</string>
        </array>
    </dict>
</dict>

ThirdPartyRootDir must point to the directory that contains the .xcframework, not to the .xcframework itself.

SwiftDependencies must point to a directory containing one or more .xcframework bundles that your framework depends on (for example, a third-party logging SDK). Omit this key if your framework has no external dependencies.

Step 3 — Run the Tool


python3 build_tp.pyc

The generated output is available in the NFITool/products/ directory.