xcparse

0.0.3 verified Sat Apr 25 auth: no javascript

A pbxproj parser and builder for Xcode project files, currently at version 0.0.3. Uses Chevrotain for fast, spec-compliant parsing, including support for the Data type (<xx xx xx>) missing in alternatives like the Cordova xcode package. Implements a port of the Apple CFOldStylePlist parser for accurate string handling. API is experimental and subject to breaking changes. Active development, release cadence irregular. Best for TypeScript projects needing typed pbxproj manipulation without PEG.js performance overhead.

Common errors

error TypeError: fs.readFileSync is not a function ↓

cause Using browser environment or import without node:fs prefix.

fix

Ensure you're running in Node.js and use 'import fs from 'node:fs';' for modern Node versions.

error SyntaxError: Unexpected token in JSON at position ... ↓

cause Trying to JSON.parse the output of parse() that is already an object.

fix

parse returns an object directly, not a JSON string. Do not call JSON.parse on it.

error Error: Cannot find module 'xcparse' ↓

cause Package not installed or import path typo.

fix

Run 'yarn add xcparse' or 'npm install xcparse' and double-check the import name.

Warnings

breaking API is experimental and subject to breaking changes in future releases. ↓

fix Pin to exact version and watch for changelog before upgrading.

gotcha Import path is 'xcparse' not 'xctrace' (the example in the README shows 'xctrace' which is incorrect). ↓

fix Use 'xcparse' in import statements.

gotcha Chevrotain fork may cause increased bundle size; the package is not tree-shakeable. ↓

fix Consider using xcparse only in build tools, not in browser bundles.

deprecated UUID generation and unist-based API are planned but not yet implemented. ↓

fix Currently no built-in UUID generation; you must supply your own for new objects.

Install

npm install xcparse

yarn add xcparse

pnpm add xcparse

Imports

parse

wrong

const { parse } = require('xcparse')

correct

import { parse } from 'xcparse'

Typescript types included. Named export only.

build
wrong
```
import build from 'xcparse'
```
correct
```
import { build } from 'xcparse'
```
Default export is not available. Must use named import.
type ParsedPbxproj
wrong
```
import { ParsedPbxproj } from 'xcparse'
```
correct
```
import type { ParsedPbxproj } from 'xcparse'
```
Use type import for TypeScript compilation to avoid runtime overhead.

Quickstart

Parses a .pbxproj file into a JSON representation, then rebuilds it back to a string after modification.

import { parse, build } from 'xcparse';
import fs from 'fs';

const pbxprojContent = fs.readFileSync('project.pbxproj', 'utf-8');
const parsed = parse(pbxprojContent);
console.log(parsed.objects); // Access parsed objects

// Modify a build setting, then rebuild
if (parsed.objects && parsed.objects['PBXBuildFile']) {
  // Example: add a file
}
const rebuilt = build(parsed);
fs.writeFileSync('project.pbxproj', rebuilt);