Build Lynx iOS Apps on Windows: Host App to .ipa

Build pages with rspeedy, add Lynx to the host app with CocoaPods, then build and install on Windows.

Last updated 2026-11-12

Show steps for

To build iOS apps with Lynx on Windows, write your ReactLynx pages with rspeedy as usual and run npm run build to get main.lynx.bundle. The iOS host app pulls in Lynx with CocoaPods. KXBuild builds the host app, installs it on your iPhone over USB for debugging, and a Release build produces an .ipa. When you only change pages, you rebuild the bundle and the app builds again in seconds.

How do I create a Lynx project and add it to an iOS host app on Windows?

1. Create the page project and build it

For an existing Lynx page project, run npm run build. Otherwise, create a ReactLynx project with rspeedy. The build writes main.lynx.bundle to dist.

> npm create rspeedy@latest my-lynx -- --template rspeedy-react-ts

> cd my-lynx

> npm install

> npm run build

2. Prepare the iOS host app

For an existing native iOS project, add Lynx, PrimJS, LynxService and the other dependencies to its Podfile as described in "Integrate with Existing Apps" on the Lynx website. Otherwise, start from ios/HelloLynxSwift in Lynx's official integrating-lynx-demo-projects repository. Copy main.lynx.bundle from the previous step into the host project folder, replacing the sample's file of the same name; in a new project, add it to the app's resources.

Then open the host project folder in VS Code with File > Open Folder….

3. Install dependencies

Lynx publishes its pods in its own Specs repository. Add that repository once, run pod install in the host project folder, and build the .xcworkspace it creates. See CocoaPods.

> pod repo add lynx-family https://github.com/lynx-family/Specs.git

> pod install

4. Run doctor

It checks the build environment and prepares the iOS project.

In the title bar of the KXBuild view, open the ··· menu and run Doctor (fix environment).

> kxbuild doctor .\Hello-Lynx.xcworkspace

How do I run and debug Lynx pages on an iPhone?

5. Code

Write your pages in src/ as usual. After a change, run npm run build and copy dist/main.lynx.bundle into the host project, replacing the old file. The host app's Swift / Objective-C code gets completion and go to definition in VS Code.

6. Debug

Connect your iPhone over USB. The first build compiles the Lynx engine and takes a while; after that, swapping in a new bundle builds in seconds.

Select it in the KXBuild view and press F5. Set breakpoints in the host app's native code in VS Code.

Run the command below to build the app, install it on your iPhone and launch it.

> kxbuild run .\Hello-Lynx.xcworkspace

Before you connect a phone for the first time, install and open Apple Devices from the Microsoft Store to get the USB driver on Windows. On iOS 16 and later, turn on Developer Mode in Settings > Privacy & Security and let the phone restart. See connect an iPhone to Windows for the full steps.

How do I build a Lynx iOS .ipa on Windows for the App Store?

7. Release

Build the latest main.lynx.bundle and copy it into the host project first, then build with the Release configuration. The .ipa is written to the host project's build folder. To upload it to App Store Connect, see publish to the App Store from Windows.

Run KXBuild: Build for App Store (.ipa) from the Command Palette or the project's context menu.

> kxbuild build .\Hello-Lynx.xcworkspace -c Release --export app-store

An App Store .ipa must be signed with an Apple Distribution certificate. Put your own .p12 certificate and .mobileprovision profile in a keychain/ folder and every build signs automatically; see sign iOS apps on Windows. Upload with kxstore (kxstore build upload, on Windows, Linux or macOS), then handle TestFlight and review on App Store Connect. That way you build iOS apps with Lynx on Windows, debug them on a real iPhone and submit them from one computer.

Frequently asked questions

Building Lynx fails with "The selected platform is no longer supported by libc++". What do I do?

Recent iOS SDKs require a deployment target of 15.0 or later, and Lynx's pods treat warnings as errors. Add the following to the end of the host project's Podfile. It raises pods below 15.0 to 15.0 and keeps the warnings that come with the new SDK from stopping the build. Then run pod install again. If your Podfile already has a post_install block, merge the inner lines into it.

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      if config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'].to_f < 15.0
        config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.0'
      end
      flags = ' -Wno-error=deprecated-declarations -Wno-error=deprecated-implementations -Wno-error=#warnings -Wno-error=unused-result'
      config.build_settings['OTHER_CFLAGS'] = '$(inherited)' + flags
      config.build_settings['OTHER_CPLUSPLUSFLAGS'] = '$(inherited)' + flags
    end
  end
end

Next steps

CocoaPods

Keep your Podfile as it is. Run pod install on Windows and build the generated workspace.

Release and App Store submission

Build Release with a Distribution certificate to get an .ipa, upload it to App Store Connect with kxstore (or Transporter on a Mac), then go through TestFlight and App Review. Ad Hoc and enterprise distribution work the same way.

Don't see your framework?

kxbuild is a general-purpose build toolchain, so if your framework produces an Xcode project, KXBuild can build it. The list above covers common cases only. Tell us about your setup.

admin@kxbuild.net All stacks