Using Xcode 15 to Fix the "New Build System Required" Error in SwiftUI Preview

Troubleshooting Xcode Build System for Smooth SwiftUI Integration

Encountering errors while working in Xcode can be incredibly frustrating, especially when diving into SwiftUI in a UIKit project. One common issue many developers face, especially in Xcode 15, is the “New build system required” error when previewing SwiftUI files. 😣

This issue often appears unexpectedly, and tracking down the cause can be confusing. In most cases, it relates to workspace build settings not defaulting to the new build system, which Xcode now requires for using previews effectively.

In this article, I’ll guide you through understanding this error, along with practical steps to fix it. By the end, you’ll be able to adjust settings and continue using SwiftUI previews without hiccups.

Let’s dive into a step-by-step approach for enabling the new build system in Xcode, ensuring smooth SwiftUI previews and a better development experience overall. 🚀

Understanding and Fixing the SwiftUI Preview Error in Xcode

The first script solution addresses the core of the issue by manually enabling the new build system within Xcode’s workspace settings. For developers encountering the SwiftUI preview error, this method is essential, especially since previews require the new build system. In this approach, you’ll open the project in Xcode and navigate to Workspace Settings (File -> Workspace Settings). Here, you can explicitly select the “New Build System (Default)” option, ensuring compatibility with SwiftUI previews. This solution is simple yet effective, as manually setting the build system resolves configuration conflicts that might otherwise block preview rendering. Following this, a quick clean-up of the project with Product -> Clean Build Folder can remove lingering configuration files that may hold onto outdated settings. Such minor actions often resolve big issues and can save a lot of time in complex projects! 🚀

The second script is a Swift-based solution that uses file system commands to automate the check for the new build system setting. The script leverages FileManager to access the workspace configuration file, WorkspaceSettings.xcsettings, ensuring that the settings align with SwiftUI preview requirements. By checking this file programmatically, it’s possible to confirm if "UseNewBuildSystem = YES" is present. This approach is helpful for developers who frequently work across multiple projects, as it saves time by automating build system validation. Additionally, the script reads the contents of the configuration file with a data-to-string conversion, enabling a precise search within the file. This automated check streamlines the process, ideal for larger teams or CI environments where consistency is key. It’s a small but powerful step towards efficient project management. 🤖

In the third solution, we introduced a unit testing strategy to verify the build system setting across different configurations. Using XCTest, this script provides a structured way to ensure that the configuration is correct before running the preview. For instance, the XCTAssertTrue and XCTAssertFalse commands validate whether the setting aligns with SwiftUI’s requirements. In practice, these assertions can be critical in larger development teams or when building automation into CI/CD pipelines, as they offer an immediate red flag if the preview configuration isn’t up to standard. It also makes onboarding new developers simpler, as they can use these tests to ensure their environment meets the necessary requirements before working with SwiftUI previews.

Finally, the test suite’s defaultTestSuite.run() command automatically executes all tests in this solution, simulating various build environments to verify the presence of the correct build system. This provides developers with a proactive approach to avoid preview-related interruptions in their workflow. Each of these solutions brings a unique angle to handling the new build system requirement in Xcode, offering flexibility in resolving the issue based on project needs. By implementing one or more of these solutions, you can streamline your development and avoid unexpected SwiftUI preview errors.

// Step 1: Open Xcode and go to your project workspace settings.
// In Xcode, navigate to File -> Workspace Settings.
// Step 2: Set the Build System to "New Build System (Default)".
// This ensures that the workspace uses the new build system required by SwiftUI previews.
// Step 3: Clean the project build folder to remove old configurations.
Product -> Clean Build Folder
// Step 4: Run the SwiftUI preview to confirm the error is resolved.
// If the error persists, restart Xcode and check the settings again.

import Foundation
// Function to check if the build system is set to the new build system
func checkBuildSystem() -> Bool {
   // Path to the workspace settings file
   let workspaceSettingsPath = "path/to/WorkspaceSettings.xcsettings"
   let fileManager = FileManager.default
   if let data = fileManager.contents(atPath: workspaceSettingsPath),
      let content = String(data: data, encoding: .utf8) {
         // Check for the new build system setting
         return content.contains("UseNewBuildSystem = YES")
   }
   return false
}
// Run the function and print status
if checkBuildSystem() {
   print("New build system is enabled.")
} else {
   print("New build system is not enabled. Please update settings.")
}

import XCTest
class BuildSystemTests: XCTestCase {
   func testNewBuildSystemEnabled() {
      // Sample settings content for testing
      let settingsContent = "UseNewBuildSystem = YES"
      XCTAssertTrue(settingsContent.contains("UseNewBuildSystem = YES"),
                    "New Build System should be enabled for SwiftUI Previews.")
   }
   func testOldBuildSystemDisabled() {
      // Sample outdated settings content
      let settingsContent = "UseNewBuildSystem = NO"
      XCTAssertFalse(settingsContent.contains("UseNewBuildSystem = YES"),
                    "Old Build System detected. Update required.")
   }
}
// Execute tests for different configurations
BuildSystemTests.defaultTestSuite.run()

Getting to the Root of the Xcode “New Build System Required” Error

One of the lesser-discussed aspects of the SwiftUI preview error, “New build system required,” is the shift in Xcode 15 to rely exclusively on the new build system. While initially introduced in Xcode 10, this new build system has now become essential for SwiftUI previews. When attempting to view SwiftUI files in a UIKit-based project, older build settings can lead to this error, interrupting the preview functionality. Switching to the new build system is a way to streamline performance and reduce some common build errors, but for developers who aren’t aware of this requirement, it can lead to significant frustration when previews don’t work. 🎯

Beyond simply switching to the new build system, developers can also make sure their project settings are aligned with Xcode’s newer frameworks. This involves checking dependencies and configurations in Workspace Settings, ensuring that the correct SDK versions are set. Sometimes, settings for iOS versions as low as 13 can further complicate preview compatibility, especially when used in projects targeting more recent SDKs like iOS 17. This proactive settings check can prevent preview interruptions while allowing developers to enjoy the latest features SwiftUI offers.

Developers should also consider configuring automated scripts or testing suites to verify build settings before launching previews. By utilizing XCTest or FileManager-based scripts to review and adjust project settings, teams can save time and avoid preview-related issues across various environments. As Xcode continues to evolve, staying informed on new requirements like this build system switch is essential for a smooth development process. This ensures that both SwiftUI and UIKit-based elements in the project work harmoniously without preview errors.