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.

Built-in templates

There are 11, listed in the order the wizard shows them. Pass the id to kxbuild project create -t on the command line. Every template targets iOS 15 and ships without signing files. Set up your certificate as described in Certificates and signing.

Native apps

Template	id	Contents
iOS App (SwiftUI)	app_swiftui	An App entry point and ContentView, no storyboard
iOS App (Swift, UIKit)	app_swift	A single-view UIKit app with a storyboard, SceneDelegate and asset catalog
iOS App (WKWebView shell)	app_webview	The whole UI is one WKWebView that loads a bundled www/ folder or a remote URL. Includes a progress bar, the back-swipe gesture and a JS-to-native bridge example.
iOS App (Objective-C, UIKit)	app_objc	A single-view Objective-C UIKit app with a storyboard and asset catalog
iOS App (Objective-C + Swift)	app_objc_swift	An Objective-C app with Swift files, showing calls both ways through the bridging header and -Swift.h
iOS App (Swift, CocoaPods)	app_swift_cocoapods	A Swift UIKit app with a Podfile. Runs pod install after creation.

Cross-platform apps

These three templates generate the project with each framework's own scaffolding tool, then kxbuild doctor sets up the iOS side. It takes a few minutes.

Template	id	Contents	Requires
Flutter App	flutter_app	iOS and Android projects from flutter create, with the bundle ID set on the Runner target	Flutter SDK
React Native App	react_native_app	Initialized with the React Native Community CLI, with pod install done	Node.js and CocoaPods, installed with the toolchain
Expo App	expo_app	Initialized with create-expo-app, then expo prebuild and pod install	Node.js and CocoaPods, installed with the toolchain

Libraries

Template	id	Contents
Framework (Swift)	framework_swift	A dynamic iOS framework with an umbrella header and a sample public class
Static Library (Objective-C)	lib_static_objc	lib<Name>.a, with public headers copied to include/<Name>/

Template structure

A template is a folder, and the folder name is the template id. Everything except template.json and template.sh is copied into the new project as is.

app_swift/
  template.json        name, description, order, requirements
  template.sh          optional, runs in the new project folder after copying
  .gitignore
  __NAME__.xcodeproj/
  __NAME__/
    AppDelegate.swift …

Placeholders are replaced in file contents and file names. Binary files are copied unchanged.

Placeholder	Replaced with
__NAME__	Project name
__BUNDLE_ID__	Bundle ID
__DATE__	Creation date, formatted yyyy/MM/dd

Example template.json

{
  "name":        { "en": "iOS App (Swift, UIKit)", "zh": "iOS 应用（Swift · UIKit）" },
  "description": { "en": "…", "zh": "…" },
  "category": "app",          // app | library | hybrid
  "order": 10,                // position in the list, lower comes first
  "requires": ["cocoapods"]   // optional external tools, shown after the name in the wizard
}

template.sh runs with bash after copying and placeholder replacement, in the new project folder. On Windows it uses the MSYS2 bash that ships with the toolchain. The script can read these environment variables.

Variable	Value
KXBUILD_PROJECT_NAME / KXBUILD_BUNDLE_ID	Project name, bundle ID
KXBUILD_PROJECT_DIR	New project folder
KXBUILD_TEMPLATE_ID / KXBUILD_TEMPLATE_DIR	Template id, template folder
KXBUILD_HOME / KXBUILD_BIN	Toolchain folder, kxbuild executable

A non-zero exit code means creation failed, and the project folder is kept. A template can have no files at all and generate the whole project from template.sh, which is how the built-in Flutter, React Native and Expo templates work. On Windows, call native tools by names like pod.bat, npx.cmd and flutter.bat.

Custom templates

Turn a project layout you use often into a template and pick it when you create a project.

Step	Details
1 Prepare a project	Create a project from the closest built-in template, shape it the way you want and make sure it builds. Delete build products such as build/ and xcuserdata/, and leave out certificates.
2 Add placeholders	Replace every occurrence of the project name with __NAME__, including the .xcodeproj folder name, the source folder name, the target and product names in the pbxproj, and Info.plist. Replace the bundle ID with __BUNDLE_ID__.
3 Add template.json	The folder name is the id. Don't reuse a built-in template's name. Use something like mycorp_app.
4 Install the template	Copy the whole folder to KXBUILD_HOME\resources\templates\. Reopen the New Project wizard and it's there.

You can also skip the files and write only a template.sh that generates the project with an existing scaffolding tool or git clone. Toolchain updates only overwrite folders with the same name, so custom templates survive, as long as their ids don't match a built-in one. To use a template on another machine, copy it to the same location there.

Next steps

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.

Build and configure

Debug versus Release, choosing a scheme, target and configuration, overriding build settings, where build products go, when you get an .ipa and when Swift package dependencies resolve.