@xcodekit/xcode-wasm

@xcodekit/xcode

Super fast Xcode .pbxproj parser and serializer written in Rust.

Drop-in replacement for the low-level API of @bacons/xcode — same parse() and build() interface, 3-15x faster parsing, byte-identical output.

Install

# Recommended — auto-selects native or WASM
npm install @xcodekit/xcode

# Native only (Node.js, fastest)
npm install @xcodekit/xcode-node

# WASM only (universal — Bun, CF Workers, any bundler)
npm install @xcodekit/xcode-wasm

@xcodekit/xcode is a thin auto-selector — in Node.js/Bun it tries the native addon first, everywhere else it uses WASM. You get optimal performance without choosing.

Quick Start

import { parse, build } from "@xcodekit/xcode";
import { readFileSync, writeFileSync } from "fs";

// Parse a .pbxproj file
const text = readFileSync("project.pbxproj", "utf8");
const project = parse(text);

// Modify it
project.objects["YOUR_UUID"] = {
  isa: "PBXFileReference",
  path: "NewFile.swift",
  sourceTree: "<group>",
};

// Write it back
const output = build(project);
writeFileSync("project.pbxproj", output);

API

Low-Level (JSON)

parse(text: string): object

Parse a .pbxproj string into a JSON-compatible object. Matches the output of @bacons/xcode/json's parse().

const project = parse(readFileSync("project.pbxproj", "utf8"));

build(project: object): string

Serialize a JSON object back to .pbxproj format. Produces byte-identical output to @bacons/xcode/json's build().

writeFileSync("project.pbxproj", build(project));

parseAndBuild(text: string): string

Parse and immediately re-serialize. Stays entirely in Rust/WASM with zero JS marshalling — the fastest possible round-trip path.

const output = parseAndBuild(readFileSync("project.pbxproj", "utf8"));

High-Level (XcodeProject)

XcodeProject.open(filePath) / XcodeProject.fromString(content)

Open from disk or parse from a string.

import { XcodeProject } from "@xcodekit/xcode";

// From disk
const project = XcodeProject.open("ios/MyApp.xcodeproj/project.pbxproj");

// From string (no file on disk needed)
const project = XcodeProject.fromString(pbxprojContent);

// Properties
project.archiveVersion; // 1
project.objectVersion; // 46
project.filePath; // path if opened from disk, null if fromString
project.mainGroupUuid; // root group UUID

// Targets
const targets = project.getNativeTargets(); // UUID[]
const mainApp = project.findMainAppTarget("ios"); // UUID | null
project.getTargetName(mainApp); // "MyApp"
project.setTargetName(mainApp, "NewName");
project.renameTarget(mainApp, "OldName", "NewName"); // cascades to groups, product refs, proxies

// Build settings
project.getBuildSetting(targetUuid, "PRODUCT_BUNDLE_IDENTIFIER");
project.setBuildSetting(targetUuid, "SWIFT_VERSION", "5.0");
project.removeBuildSetting(targetUuid, "CODE_SIGN_IDENTITY");

// Files & groups
const fileUuid = project.addFile(project.mainGroupUuid, "Sources/App.swift");
const groupUuid = project.addGroup(project.mainGroupUuid, "Features");
const children = project.getGroupChildren(groupUuid);

// Build phases
const phase = project.ensureBuildPhase(targetUuid, "PBXSourcesBuildPhase");
project.addBuildFile(phase, fileUuid);

// Frameworks
project.addFramework(targetUuid, "SwiftUI");

// Create targets
const widgetTarget = project.createNativeTarget(
  "MyWidget",
  "com.apple.product-type.app-extension",
  "com.example.mywidget",
);

// Embed extension into host app
project.addDependency(mainApp, widgetTarget);
project.embedExtension(mainApp, widgetTarget);

// Xcode 16+ file system sync groups
project.addFileSystemSyncGroup(widgetTarget, "MyWidget");

// Generic object access
project.getObjectProperty(uuid, "path");
project.setObjectProperty(uuid, "path", "new/path");
const proxies = project.findObjectsByIsa("PBXContainerItemProxy");

// Validation
const orphans = project.findOrphanedReferences();
// [{ referrerUuid, referrerIsa, property, orphanUuid }]

// Serialize
const pbxproj = project.toBuild(); // string
const json = project.toJSON(); // object

// Write back to disk
project.save();

// Deterministic UUID generation
const uuid = project.getUniqueId("my-seed-string"); // 24-char hex

All XcodeProject methods operate in Rust/WASM — only primitive strings cross the boundary. This is the fastest path for project manipulation.

Packages

Package	What	Size	Runtime
@xcodekit/xcode	Auto-selector (tries native, falls back to WASM)	~4 KB	Node.js, Bun, CF Workers, browsers
@xcodekit/xcode-node	Native napi-rs addon	~600 KB	Node.js only
@xcodekit/xcode-wasm	WASM with inlined base64	~370 KB	Everywhere

@xcodekit/xcode uses exports conditions: the node condition loads native, default loads WASM. No try/catch at runtime for most environments.

When to use which

Environment	Recommended
Node.js / Bun	@xcodekit/xcode (auto-selects native)
Cloudflare Workers / edge	@xcodekit/xcode or @xcodekit/xcode-wasm
Bundled app (single file)	@xcodekit/xcode-wasm (inlined, no file resolution)
Need max performance	@xcodekit/xcode-node (direct, no facade overhead)

Performance

Benchmarked on Apple M4 Pro, Node.js v24. Median of 200 iterations.

• xcode-wasm — @xcodekit/xcode-wasm
• xcode-node — @xcodekit/xcode-node
• @bacons/xcode — @bacons/xcode/json

Parse

Fixture	xcode-wasm	xcode-node	@bacons/xcode	wasm speedup	node speedup
swift-protobuf (257 KB)	2.9 ms	3.7 ms	43.9 ms	15.2x	11.8x
Cocoa-Application (166 KB)	2.4 ms	3.2 ms	17.2 ms	7.3x	5.4x
AFNetworking (99 KB)	1.3 ms	1.7 ms	6.6 ms	5.1x	3.9x
watch (48 KB)	0.7 ms	0.9 ms	2.1 ms	3.0x	2.3x
project (19 KB)	0.3 ms	0.4 ms	0.8 ms	2.9x	2.2x

Build

Fixture	xcode-wasm	xcode-node	@bacons/xcode	wasm speedup	node speedup
swift-protobuf (257 KB)	4.1 ms	5.2 ms	12.0 ms	2.9x	2.3x
Cocoa-Application (166 KB)	3.3 ms	4.5 ms	2.7 ms	1.2x slower	1.7x slower
AFNetworking (99 KB)	1.6 ms	2.3 ms	1.8 ms	1.1x	1.3x slower
watch (48 KB)	0.8 ms	1.1 ms	0.4 ms	1.9x slower	2.7x slower
project (19 KB)	0.3 ms	0.4 ms	0.2 ms	1.9x slower	2.7x slower

TypeScript wins build() on smaller files because it operates directly on native JS objects with zero serialization cost. On large files (>100 KB) where actual serialization work dominates, Rust wins.

Round-Trip (parse + build)

Fixture	xcode-wasm	xcode-node	@bacons/xcode	wasm speedup	node speedup
swift-protobuf (257 KB)	7.0 ms	9.0 ms	55.9 ms	8.0x	6.2x
Cocoa-Application (166 KB)	5.7 ms	7.7 ms	19.9 ms	3.5x	2.6x
AFNetworking (99 KB)	2.9 ms	4.0 ms	8.4 ms	2.9x	2.1x
watch (48 KB)	1.5 ms	2.0 ms	2.5 ms	1.7x	1.3x
project (19 KB)	0.6 ms	0.8 ms	1.0 ms	1.7x	1.3x

Round-Trip (parseAndBuild — zero marshalling)

Fixture	xcode-wasm	xcode-node	@bacons/xcode	wasm speedup	node speedup
swift-protobuf (257 KB)	4.8 ms	4.4 ms	62.7 ms	13.1x	14.2x
Cocoa-Application (166 KB)	3.7 ms	3.7 ms	22.4 ms	6.0x	6.1x
AFNetworking (99 KB)	1.9 ms	1.8 ms	9.2 ms	4.7x	5.1x
watch (48 KB)	0.9 ms	0.9 ms	2.8 ms	3.0x	3.1x
project (19 KB)	0.4 ms	0.3 ms	1.0 ms	2.8x	2.9x

Package Size

	xcode-wasm	xcode-node	@bacons/xcode
Uncompressed	~370 KB	559 KB	1.1 MB
Gzipped	~96 KB	270 KB	~400 KB

Compatibility

• Full feature parity with @bacons/xcode/json (parse/build)
• 13/13 round-trip fixtures produce byte-identical output
• All escape sequences: standard (\n, \t, etc.), Unicode (\Uxxxx), octal, NeXTSTEP (128 entries)
• Xcode 16+ file system synchronized groups
• Swift Package Manager references

Supported Platforms

Native (@xcodekit/xcode-node)

Platform	Architecture
macOS	arm64 (Apple Silicon), x64 (Intel)
Linux	x64 (glibc), arm64 (glibc)
Windows	x64 (MSVC)

WASM (@xcodekit/xcode-wasm)

Any environment that supports WebAssembly — Node.js, Bun, Deno, Cloudflare Workers, browsers, etc. WASM binary is inlined as base64 — no file resolution needed, works in single-file bundles.

Development

# Prerequisites: Rust toolchain, Node.js >= 18, wasm-pack, binaryen

npm install

# Tests
make test           # all (Rust + native JS + WASM JS)
make test-rust      # Rust unit + integration tests
make test-js        # native napi tests (vitest)
make test-wasm      # WASM tests (vitest)

# Build
make build          # native napi release
make build-debug    # native napi debug (faster compilation)
make build-wasm     # WASM → pkg/xcode-wasm/
make build-node     # native → pkg/xcode-node/
make build-all      # all packages

# Other
make check          # type-check all targets
make fmt            # cargo fmt + prettier
make lint           # cargo clippy
make bench          # all benchmarks
make clean          # remove all artifacts

Project Structure

src/                          # Rust source (parser, writer, project API)
tests/
  integration_tests.rs        # Rust integration tests
  node.test.mjs               # Native napi JS tests (vitest)
  wasm.test.mjs               # WASM JS tests (vitest)
  fixtures/                   # 20 real-world .pbxproj files
npm/                          # Publishable package metadata
  xcode/                      # @xcodekit/xcode (auto-selector facade)
  xcode-node/                 # @xcodekit/xcode-node (native napi)
    platforms/                # Platform binary packages (darwin-arm64, etc.)
  xcode-wasm/                 # @xcodekit/xcode-wasm (WASM wrapper + types)
scripts/                      # Build scripts
  build-node-pkg.sh           # Assembles pkg/xcode-node/
  build-wasm-pkg.sh           # Assembles pkg/xcode-wasm/ (wasm-opt, base64 inline)
pkg/                          # Generated build output (gitignored)

License

MIT