@bacons/xcode

You can add both remote and local Swift Package Manager (SPM) dependencies to an Xcode project. When using target.addSwiftPackageProduct(), the library automatically handles creating the XCSwiftPackageProductDependency, creating the PBXBuildFile, and adding it to the target's Frameworks build phase.

import { XcodeProject } from "@bacons/xcode";
import fs from "fs";

const project = XcodeProject.open("/path/to/project.pbxproj");
const rootProject = project.rootObject;

// Add a remote Swift package to the project
const packageRef = rootProject.addRemoteSwiftPackage({
  repositoryURL: "https://github.com/apple/swift-collections",
  requirement: {
    kind: "upToNextMajorVersion",
    minimumVersion: "1.0.0",
  },
});

// Add the package product to a target
const target = rootProject.getMainAppTarget("ios");
const productDep = target.addSwiftPackageProduct({
  productName: "Collections",
  package: packageRef,
});

// Save the project
fs.writeFileSync("/path/to/project.pbxproj", build(project.toJSON()));

The XCWorkspace class provides a high-level interface for managing .xcworkspace files, including adding/removing projects and managing groups.

import { XCWorkspace } from "@bacons/xcode";

// Open an existing workspace
const workspace = XCWorkspace.open("/path/to/MyApp.xcworkspace");

// Get all project paths
const projects = workspace.getProjectPaths();
console.log(projects); // ["group:App.xcodeproj", "group:Pods/Pods.xcodeproj"]

// Check if workspace contains a project
if (!workspace.hasProject("NewProject.xcodeproj")) {
  workspace.addProject("NewProject.xcodeproj");
}

// Remove a project
workspace.removeProject("OldProject.xcodeproj");

// Work with groups
const group = workspace.addGroup("Libraries", "group:Libraries");
group.fileRefs?.push({ location: "group:Libraries/MyLib.xcodeproj" });

// Save changes
workspace.save();

// Create a new workspace
const newWorkspace = XCWorkspace.create("MyWorkspace");
newWorkspace.addProject("App.xcodeproj");
newWorkspace.addProject("Pods/Pods.xcodeproj");
newWorkspace.save("/path/to/MyWorkspace.xcworkspace");

The high-level API allows you to load projects, retrieve existing schemes, create new schemes, and save them back to the project.

import { XcodeProject, XCScheme } from "@bacons/xcode";

// Load project and get schemes
const project = XcodeProject.open("/path/to/project.pbxproj");
const schemes = project.getSchemes();
const appScheme = project.getScheme("App");

// Create a new scheme
const newScheme = XCScheme.create("MyNewScheme");
newScheme.addBuildTarget({
  buildableIdentifier: "primary",
  blueprintIdentifier: "ABC123", // Target UUID
  buildableName: "App.app",
  blueprintName: "App",
  referencedContainer: "container:Project.xcodeproj",
});
newScheme.setLaunchEnvironmentVariable("API_URL", "https://api.example.com");
newScheme.addLaunchArgument("-verbose");

// Save to disk
project.saveScheme(newScheme);

// Create scheme for an existing target
const mainTarget = project.rootObject.props.targets[0];
const targetScheme = project.createSchemeForTarget(mainTarget);
project.saveScheme(targetScheme);

An XCScheme object represents an Xcode .xcscheme file, which is an XML document defining how targets are built, run, tested, profiled, analyzed, and archived. The root object contains configuration for various actions:

• buildAction: Configuration for building targets.
• testAction: Configuration for running tests.
• launchAction: Configuration for running/launching the app.
• profileAction: Configuration for Instruments profiling.
• analyzeAction: Configuration for static analysis.
• archiveAction: Configuration for archiving the app.

Each action can include preActions and postActions (of type ExecutionAction) to run shell scripts at specific lifecycle points.

export interface XCScheme {
  version?: string;
  lastUpgradeVersion?: string;
  buildAction?: BuildAction;
  testAction?: TestAction;
  launchAction?: LaunchAction;
  profileAction?: ProfileAction;
  analyzeAction?: AnalyzeAction;
  archiveAction?: ArchiveAction;
}

The XCUserData class provides a high-level API for accessing and modifying per-developer Xcode data stored in .xcuserdatad directories. This includes user-specific schemes, scheme management settings, and breakpoints. Unlike shared data (xcshareddata), this data is typically unique to a developer and is not intended to be checked into version control.

Key capabilities include:

• Scheme Management: Accessing and saving .xcscheme files and xcschememanagement.plist.
• Breakpoints: Reading and writing Breakpoints_v2.xcbkptlist files.
• Discovery: Finding all user data directories within an xcuserdata folder.

import { XCUserData } from '@bacons/xcode';

// Open an existing user data directory
const userData = XCUserData.open('path/to/Project.xcodeproj/xcuserdata/username.xcuserdatad');

// Or discover all users in a project's xcuserdata folder
const users = XCUserData.discoverUsers('path/to/Project.xcodeproj/xcuserdata');