Create, open and import projects
Create projects in VS Code, open existing ones, add Swift package dependencies and app extensions such as widgets, and convert a Swift package into an app project. Loaded projects show up in the KXBuild view, ready to run with F5. A table at the end lists which folder to open for each project type.
Create a project
Press Ctrl+Shift+P to open the Command Palette and run KXBuild: New Project, or choose "New Project" from the "···" menu in the KXBuild view's title bar. The wizard has four steps.
| Step | Details |
|---|---|
| 1 Pick a template | Templates that need extra tools say so. For what each one contains, see Project templates. |
| 2 Enter a project name | Letters, digits and underscores, starting with a letter |
| 3 Enter a bundle ID | Generated from the project name. You can change it. |
| 4 Choose a folder | The project is created in a subfolder with the same name. On Windows, use a short path, because React Native and Expo projects have deeply nested dependencies. |
When it's done, choose "Open in New Window" or "Open Here". The CocoaPods, Flutter, React Native and Expo templates run their setup automatically, which takes a few minutes. Progress shows in the KXBuild channel of the Output panel. If setup fails, the project folder is kept. Choose "Open Anyway" and finish the remaining steps by hand.
Open an existing project
Open the project folder with File > Open Folder…. For an Xcode project, open the folder that holds the .xcodeproj or .xcworkspace. For a Swift package, open the folder that holds Package.swift. For Flutter, React Native, Expo and Kotlin Multiplatform, open the project root. The KXBuild view lists the projects and targets it finds.
When the folder has several projects, F5 and Build act on the startup project. Click a project node to switch. See Sidebar and Status Bar > Startup project.
The first time you open a Flutter, React Native or Expo project, run "Doctor (fix environment)" from the "···" menu in the KXBuild view's title bar. It installs dependencies and checks the SDK. The project won't build until you do. For a CocoaPods project, run pod install in the folder that holds the Podfile first. See CocoaPods.
Add a Swift package dependency
Run KXBuild: Add Swift Package Dependency… from the Command Palette, or right-click a target in the KXBuild view and choose it. It's the equivalent of Xcode's Add Package Dependencies. Enter the package's Git URL or pick a local package folder, then choose the products to link. As in Xcode, a remote package defaults to the latest version, up to the next major version. Adding one needs an internet connection.
Convert a Swift package to an app project
A Swift package whose executable target is an app can't be installed on an iPhone or turned into an .ipa as it is. A package with only libraries is a library, so it isn't converted. To use it, add it to an app project. Open the folder that holds Package.swift and run KXBuild: Convert Swift Package to App Project from the Command Palette (or click the hint row in the KXBuild view). Enter the app name and bundle ID when asked. The app project is created in a subfolder of the package with the same name, and you commit it together with the package. It becomes the startup project, so you can press F5 to debug.
The conversion may add a .library line to Package.swift. Review and commit that change afterwards. For the full workflow, see Swift packages.
Add a target (extensions, App Clips, frameworks)
Right-click the project or a target in the KXBuild view and choose KXBuild: Add Target…, or run it from the Command Palette. It's the equivalent of Xcode's File > New > Target.
| Step | Details |
|---|---|
| 1 Choose the type | An app extension (widget, notification, share, keyboard, iMessage, Safari extension and more), an App Clip, a framework, a static library or a resource bundle |
| 2 Choose the app | The app to add it to. When you right-click an app target, that app is used. A framework, static library or resource bundle can also be added without an app |
| 3 Choose the language | Swift or Objective-C, for frameworks and static libraries |
| 4 Enter a name | Defaults to the app name plus the type, such as MyAppWidget. It's also the source folder name |
| 5 Enter an App Group | Fill it in when an extension or App Clip shares data with the app, such as group.com.example.myapp. Otherwise leave it empty |
A folder with the same name appears in the project folder, and it builds as is. An extension's bundle ID is the app's bundle ID plus a dot and the lowercased name, such as com.example.myapp.myappwidget. An App Clip's is the app's bundle ID plus .Clip. A framework is linked and embedded in the app, a static library is linked into it and a resource bundle is copied into it. They're built and installed with the app, so just press F5. See project add-target for every type.
Before installing an extension or App Clip on an iPhone, register an App ID for its bundle ID in the Apple Developer portal and create a provisioning profile for it. Put it in the keychain folder next to the app's profile. If you entered an App Group, create that App Group in the portal, enable App Groups on both App IDs (the app's and the extension's) and select it, then regenerate both provisioning profiles. The message shown after adding lists the App IDs to register and the capabilities to enable. See Certificates and signing.
Appendix: which folder to open
| Project type | Folder to open |
|---|---|
| Xcode project / workspace | The folder that holds the .xcodeproj / .xcworkspace |
| Swift package | The folder that holds Package.swift |
| CocoaPods workspace | The folder that holds the Podfile |
| Flutter | The Flutter project root |
| React Native / Expo | The React Native project root |
| Kotlin Multiplatform | The KMP project root |
| Unity / Godot / Cordova export | The exported Xcode project folder |
| cocos2d-x | The project root (the folder cocos new created) |
Next steps
Project templates
The 11 built-in templates for new projects, how a template folder is structured, and how to add your own. The VS Code wizard and the CLI use the same templates.
Sidebar and Status Bar
Where the extension lives in VS Code. What each KXBuild view node, title bar button, context menu item and Status Bar item does, where to pick your iPhone once it's connected, and which panel shows app output and build logs.