The `xcode` package, part of the Apache Cordova ecosystem, is a utility designed for programmatic parsing, editing, and writing of Xcode project files, specifically `project.pbxproj`. Currently stable at version 3.0.1, it plays a crucial role in build automation and plugin management for iOS projects within cross-platform development contexts like Cordova. While not updated frequently, its releases are typically tied to the broader Cordova platform updates, ensuring compatibility with evolving iOS development toolchains and Xcode versions. Its key differentiator is providing a Node.js-based API to manipulate these complex project files, offering a programmatic alternative to manual Xcode GUI interactions or lower-level plist editing. It is not an alternative to native dependency managers like Swift Package Manager or CocoaPods, but rather a tool for modifying the project structure itself from a JavaScript environment.
Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
The `xcode` package primarily exposes a default export (or `module.exports` in CommonJS) which is an object containing the `project` method. Direct named imports are not supported. It is predominantly used via CommonJS `require` given its history and primary use case.
import xcode from 'xcode';
// Or for CommonJS:
const xcode = require('xcode');
The `project` function is a method on the default `xcode` export. It is not directly importable as a named export.
const xcode = require('xcode');
const myProj = xcode.project(projectPath);
`writeSync` is an instance method of an `xcode.project` object, used after modifications have been made to write changes back to the file system.
myProj.writeSync();
This quickstart demonstrates how to use `xcode` to parse an Xcode project file, add a source file, a header file, and a framework, and then write the changes back to the project file. It also includes setup and cleanup for a dummy project.
const xcode = require('xcode');
const fs = require('fs');
const path = require('path');
// Create a dummy Xcode project directory and file for demonstration
const projectDir = path.join(__dirname, 'myproject.xcodeproj');
const projectPath = path.join(projectDir, 'project.pbxproj');
if (!fs.existsSync(projectDir)) {
fs.mkdirSync(projectDir);
}
fs.writeFileSync(projectPath, `
// !$* PROJECT FILE *!$
{
archiveVersion = 1;
classes = {
};
objectVersion = 46;
objects = {
1D6058900D05DD3D006BFB54 /* PBXProject */ = {
isa = PBXProject;
buildConfigurationList = 1D6058910D05DD3D006BFB54 /* Build configuration list for PBXProject */;
compatibilityVersion = 'Xcode 3.2';
has-SCM = 0;
mainGroup = 1D6058920D05DD3D006BFB54 /* CustomGroup */;
projectRoot = '';
targets = (
);
};
1D6058910D05DD3D006BFB54 /* Build configuration list for PBXProject */ = {
isa = XCConfigurationList;
buildConfigurations = (
);
defaultConfigurationIsVisible = 0;
defaultConfigurationName = Release;
};
1D6058920D05DD3D006BFB54 /* CustomGroup */ = {
isa = PBXGroup;
children = (
);
sourceTree = '<group>';
};
};
rootObject = 1D6058900D05DD3D006BFB54 /* PBXProject */;
}
`);
const myProj = xcode.project(projectPath);
// Parsing is asynchronous and runs in a different process
myProj.parse(function (err) {
if (err) {
console.error('Error parsing project:', err);
return;
}
console.log('Project parsed successfully. Current targets:', myProj.pbxProject.targets.map(t => t.comment));
// Add a new source file (e.g., 'main.m')
myProj.addSourceFile('main.m', { sourceType: 'PBXFileReference' });
console.log('Added main.m to project.');
// Add a new header file (e.g., 'AppConfig.h')
myProj.addHeaderFile('AppConfig.h');
console.log('Added AppConfig.h to project.');
// Add a framework (e.g., 'CoreData.framework')
myProj.addFramework('CoreData.framework', { weak: true });
console.log('Added CoreData.framework to project.');
// Write the modified project back to the file
fs.writeFileSync(projectPath, myProj.writeSync());
console.log('Modified project written successfully.');
// Clean up the dummy project
fs.unlinkSync(projectPath);
fs.rmdirSync(projectDir);
console.log('Cleaned up dummy project directory.');
});
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.
Agent activity
0 hits · last 30 days
No traffic data recorded yet.