Missing required module 'UIKitNavigationShim'

[TobiasRe]

Description

When integrating TCA 1.14.0 in a framework project, I'm facing issues regarding the UIKitNavigationShim target.

Building the framework fails after upgrading from TCA 1.12.1 to 1.13.0 or above, having the compiler outputting.
missing required module 'UIKitNavigationShim'

This is a new behavior since the introduction of swift-navigation inside of TCA.
This error occurs for framework targets that don't link TCA as a binary.

I've added a demo project to demonstrate the issue.
Build FrameworkWithoutTCA to replicate the issue.
TCA 1.140.zip

Checklist

• I have determined whether this bug is also reproducible in a vanilla SwiftUI project.
• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue or discussion.

Expected behavior

The framework target builds successfully.

Actual behavior

The project fails to compile with the error:
missing required module 'UIKitNavigationShim'

Steps to reproduce

1. Create a project with a framework target
2. Add TCA 1.14.0 as Package Dependency to the project
3. Don't add TCA to the target - for building a framework that doesn't bundle TCA as binary
4. Add TCA as Target Dependency of the framework
5. Build framework target

The Composable Architecture version information

0.14.0

Destination operating system

iOS 18

Xcode version information

Xcode 16.0.0 Beta 6

Swift Compiler version information

swift-driver version: 1.115 Apple Swift version 6.0 (swiftlang-6.0.0.9.10 clang-1600.0.26.2)

[stephencelis]

@TobiasRe Thanks for the report! It has us a little confused though, as integrating with TCA in a package seems to work just fine.

This is a new behavior since the introduction of swift-navigation inside of TCA. This error occurs for framework targets that don't link TCA as a binary.

This stood out to me. Is there a reason you're not linking to TCA? Couldn't that cause problems?

One thing that you may have to do if you're linking to TCA from a dynamic framework is manually specify the includes paths so that the UIKitNavigationShim module from the swift-navigation package is discoverable.

At the end of the day we'd love to support TCA/Swift Navigation usage from a dynamic framework, but we may need help from someone that is more familiar with those build systems to address the problem. Would you be able to help here?

As an alternative, are you able to use SPM or a static library instead of a dynamic framework? Those build systems seem to work OK in our experience.

[TobiasRe]

@stephencelis Thanks for your considerations.
Not linking TCA is due a requirement of our client/partner and the unavailability of SPM in this context. Otherwise we would face duplicate symbol issues. I'm aware this setup is quite unordinary in this day and age.

From what I've tried both static libraries and dynamic frameworks are affected from the same behavior.

My first guess was adding a missing @_exported statement: @_exported import UIKitNavigationShim as part of TCA. However, adding this didn't help.
I will dig a bit deeper.

[TobiasRe]

@stephencelis
Using @_implementationOnly import UIKitNavigationShim inside swift-navigation resolves this issue.
I've opened a pull request.
Could you please have a look?

PS.: Thank you for your amazing ongoing work around TCA!