{"id":17957591,"url":"https://github.com/evanbacon/xcode","last_synced_at":"2025-10-14T16:06:24.064Z","repository":{"id":40668153,"uuid":"485207758","full_name":"EvanBacon/xcode","owner":"EvanBacon","description":"super fast pbxproj parser written in TypeScript","archived":false,"fork":false,"pushed_at":"2025-10-02T00:20:07.000Z","size":751,"stargazers_count":163,"open_issues_count":3,"forks_count":8,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-10-14T16:06:03.499Z","etag":null,"topics":["chevrotain","lexer","pbxproj","xcode"],"latest_commit_sha":null,"homepage":"https://xcode-seven.vercel.app/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EvanBacon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-04-25T03:17:30.000Z","updated_at":"2025-10-09T07:09:44.000Z","dependencies_parsed_at":"2024-05-28T09:49:38.806Z","dependency_job_id":"7307375c-3ae8-4eb1-8419-4ec2087e7429","html_url":"https://github.com/EvanBacon/xcode","commit_stats":null,"previous_names":["evanbacon/xcode"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/EvanBacon/xcode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvanBacon%2Fxcode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvanBacon%2Fxcode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvanBacon%2Fxcode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvanBacon%2Fxcode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EvanBacon","download_url":"https://codeload.github.com/EvanBacon/xcode/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvanBacon%2Fxcode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279019558,"owners_count":26086750,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chevrotain","lexer","pbxproj","xcode"],"created_at":"2024-10-29T10:55:45.902Z","updated_at":"2025-10-14T16:06:24.059Z","avatar_url":"https://github.com/EvanBacon.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `@bacons/xcode`\n\n\u003e This project is a ~~_work in progress_ / _proof of concept_~~ seemingly spec compliant `pbxproj` parser. The API is subject to breaking changes.\n\n```\nyarn add @bacons/xcode\n```\n\nHere is a diagram of the grammar used for parsing:\n\n\u003cimg width=\"1211\" alt=\"Screen Shot 2022-04-25 at 12 39 27 PM\" src=\"https://user-images.githubusercontent.com/9664363/165143651-a75e354c-e131-4ae9-bde8-876be7d430f5.png\"\u003e\n\n# Why\n\nThe most popular solution for parsing pbxproj files is a very old package by Cordova called [xcode](https://www.npmjs.com/package/xcode).\n\n**But `xcode` has some major issues:**\n\n- Inaccurate parsing: strings can be quoted incorrectly very often, lists often don't work.\n- Outdated: values for App Clips, iMessage Sticker packs, etc are missing.\n- Untyped: TypeScript is a crutch I proudly support.\n- Slow: PEG.js is not very fast ([benchmark](https://chevrotain.io/performance/)).\n- Feature Incomplete: Missing the `Data` type (`\u003cxx xx xx\u003e`).\n\n## Format Comparison\n\nConsider the following format comparison.\n\n**Input `.pbxproj`**\n\n```diff\n307D28A1123043350040C0FA /* app-icon.png */ = {\n  isa = PBXFileReference;\n  lastKnownFileType = image.png;\n  path = \"app-icon.png\";\n  sourceTree = \"\u003cgroup\u003e\";\n};\n```\n\n**`xcode` output (old)**\n\n```json\n{\n  \"307D28A1123043350040C0FA_comment\": \"app-icon.png\",\n  \"308D052E1370CCF300D202BF\": {\n    \"isa\": \"PBXFileReference\",\n    \"lastKnownFileType\": \"image.png\",\n    \"path\": \"\\\"app-icon.png\\\"\",\n    \"sourceTree\": \"\\\"\u003cgroup\u003e\\\"\"\n  }\n}\n```\n\nThat same object would look like this in `@bacons/xcode`:\n\n**`@bacons/xcode` output (NEW)**\n\n```json\n{\n  \"308D052E1370CCF300D202BF\": {\n    \"isa\": \"PBXFileReference\",\n    \"lastKnownFileType\": \"image.png\",\n    \"path\": \"app-icon.png\",\n    \"sourceTree\": \"\u003cgroup\u003e\"\n  }\n}\n```\n\nNotice how you don't need to strip or reapply quotes, you also don't need to filter out comments because the default visitor ignores comments in favor of regenerating them dynamically like Xcode does.\n\n## API\n\nThere's an experimental mutable-graph layer which makes it much easier to work with pbxproj.\n\n```ts\nimport {\n  PBXAggregateTarget,\n  PBXFrameworksBuildPhase,\n  PBXLegacyTarget,\n  PBXNativeTarget,\n  XcodeProject,\n} from \"@bacons/xcode\";\n\nconst project = XcodeProject.open(\"/path/to/project.pbxproj\");\n\n// Get all targets:\nproject.rootObject.props.targets;\n```\n\nCreate a Swift file:\n\n```ts\nimport { PBXBuildFile, PBXFileReference } from \"@bacons/xcode\";\nimport path from \"path\";\n\n// Get `project` from XcodeProject.\n\nconst file = PBXBuildFile.create(project, {\n  fileRef: PBXFileReference.create(project, {\n    path: \"MyFile.swift\",\n    sourceTree: \"\u003cgroup\u003e\",\n  }),\n});\n\n// The file and fileRef will now be injected in the pbxproj `objects` dict.\n```\n\n## Solution\n\n- Unlike the [xcode](https://www.npmjs.com/package/xcode) package which uses PEG.js, this implementation uses [Chevrotain](https://chevrotain.io/).\n- This project support the Data type `\u003cxx xx xx\u003e`.\n- Unopinionated: this could change in the future :] but if it does we'll use modern graph API patterns that are typed.\n- This implementation also _appears_ to be more stable since we follow the [best guess pbxproj spec][spec].\n- String parsing is the trickiest part. This package uses a port of the actual [CFOldStylePlist parser](http://www.opensource.apple.com/source/CF/CF-744.19/CFOldStylePList.c) which is an approach first used at scale by the [CocoaPods team](https://github.com/CocoaPods/Nanaimo/blob/master/lib/nanaimo/unicode/next_step_mapping.rb) (originally credited to [Samantha Marshall](https://github.com/samdmarshall/pbPlist/blob/346c29f91f913d35d0e24f6722ec19edb24e5707/pbPlist/StrParse.py#L197)).\n\n# How\n\nThe parsing is very simple (simplicity is the key).\n\n`pbxproj` is an \"old-style plist\" (or ASCII Plist), this means it should be possible to represent it as any other static configuration file type like JSON or XML.\n\nWe support the following types: `Object`, `Array`, `Data`, `String`. Notably, we avoid dealing with `Integer`, `Double`, Boolean since they appear to not exist in the format.\n\n# TODO\n\n- [x] Reading.\n- [x] Writing.\n- [x] Escaping scripts and header search paths.\n- [x] Use a fork of chevrotain -- it's [way too large](https://packagephobia.com/result?p=chevrotain@10.1.2) for what it offers.\n- [x] Generating UUIDs.\n- [x] Reference-type API.\n- [x] Build setting parsing.\n- [ ] xcworkspace support.\n- [ ] Docs.\n\n# Docs\n\nDocs are in the works. For now, you can refer to the [types](./src/types.ts) and the estimated [`pbxproj` spec][spec].\n\nThe API will change in the future, for now we have two methods:\n\n```ts\nimport {\n  /** Given a stringified `pbxproj`, return a JSON representation of the object. */\n  parse,\n  /** Given a JSON representation of a `pbxproj`, return a `.pbxproj` string that can be parsed by Xcode. */\n  build,\n} from \"@bacons/xcode/json\";\n\nimport fs from \"fs\";\nimport path from \"path\";\n\nconst pbxproj = parse(fs.readFileSync(\"/path/to/project.pbxproj\"));\n\nconst pbxprojString = build(pbxproj);\n```\n\n- `PBXVariantGroup` is a localized `PBXGroup`.\n\n## File Path Resolution\n\nFiles will have an attribute `sourceTree` which indicates how the file path should be resolved.\n\n- `BUILT_PRODUCTS_DIR`: Paths are relative to the built products directory.\n- `DEVELOPER_DIR`: Paths are relative to the developer directory.\n- `SOURCE_ROOT`: Paths are relative to the project.\n- `SDKROOT`: Paths are relative to the SDK directory.\n- `\u003cgroup\u003e`: Paths are relative to the group.\n- `\u003cabsolute\u003e`: Source is an absolute path.\n\nFor example, a file object like:\n\n```json\n{\n  \"isa\": \"PBXFileReference\",\n  \"name\": \"AppDelegate.m\",\n  \"path\": \"multitarget/AppDelegate.m\",\n  \"sourceTree\": \"\u003cgroup\u003e\"\n}\n```\n\nIndicates that the `path` \"multitarget/AppDelegate.m\" is relative to `sourceTree` \"\u003cgroup\u003e\". We need to check the containing `PBXGroup`'s `path` (only defined when the group is linked to a directory in the file system). Groups can live inside of other groups so this process is recursive.\n\n## Versioning\n\nCertain values loosely map to each other. For instance the top-level `objectVersion` (which indicates the versioning used for the objects in the top-level `objects` dictionary), maps to the `rootObject` -\u003e `PBXProject`'s `compatibilityVersion` string. Here is an up-to-date mapping (May 2022):\n\n| `PBXProject.compatibilityVersion` | `XcodeProject.objectVersion` |\n| --------------------------------- | ---------------------------- |\n| `'Xcode 16.0'`                    | `70`                         |\n| `'Xcode 15.0'`                    | `60`                         |\n| `'Xcode 14.0'`                    | `56`                         |\n| `'Xcode 13.0'`                    | `55`                         |\n| `'Xcode 12.0'`                    | `54`                         |\n| `'Xcode 11.4'`                    | `53`                         |\n| `'Xcode 11.0'`                    | `52`                         |\n| `'Xcode 10.0'`                    | `51`                         |\n| `'Xcode 9.3'`                     | `50`                         |\n| `'Xcode 8.0'`                     | `48`                         |\n| `'Xcode 6.3'`                     | `47`                         |\n| `'Xcode 3.2'`                     | `46`                         |\n| `'Xcode 3.1'`                     | `45`                         |\n\n[spec]: http://www.monobjc.net/xcode-project-file-format.html\n\n# Attribution\n\n- [Best guess API doc][spec].\n- [CocoaPods/Xcodeproj](https://github.com/CocoaPods/Xcodeproj/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevanbacon%2Fxcode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevanbacon%2Fxcode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevanbacon%2Fxcode/lists"}