Xcode Templates

Xcode Templates

Forsetti ships Xcode templates for a production starter app, UI modules, service modules, and standalone manifests.

Template Set

Template	Creates	Use When
Forsetti App	App target starter with app module, manifest, deployment mode, bootstrap, and module registry.	Starting a new Forsetti-based app.
Forsetti UI Module	UI module class, SwiftUI view, and manifest.	Adding a visual feature module.
Forsetti Service Module	Service module class and manifest.	Adding background behavior.
Forsetti Manifest	Standalone manifest file.	Adding or repairing manifest resources.

Installation Workflow

flowchart TD
    A["Clone repository"] --> B["Run install script"]
    B --> C["Create ~/Library/Developer/Xcode/Templates/Project Templates/Forsetti"]
    C --> D["Copy Forsetti templates"]
    D --> E["Open Xcode"]
    E --> F["Choose Forsetti template"]

Loading

Scripts/install-forsetti-xcode-template.sh

To remove installed templates:

Scripts/uninstall-forsetti-xcode-template.sh

Production Starter Architecture

flowchart LR
    ContentView["ContentView"] --> Mode{"DeploymentMode.current"}
    Mode -- development --> HostRoot["ForsettiHostRootView<br/>developer controls"]
    Mode -- production --> AppView["AppModuleView<br/>product UI"]
    ContentView --> Bootstrap["ForsettiBootstrap"]
    Bootstrap --> Registry["ModuleRegistry.registerAll"]
    Bootstrap --> Controller["ForsettiHostController"]
    Controller --> Runtime["ForsettiRuntime"]

Loading

The generated app starts in development mode so the module controls are visible immediately. Switch to production mode before shipping end-user builds.

Generated App Files

File	Purpose
AppModule.swift	App-owned ForsettiAppModule implementation.
AppModuleManifest.json	Manifest for the starter app module.
AppModuleView.swift	Starter SwiftUI product surface.
DeploymentMode.swift	Development vs production switch.
ForsettiBootstrap.swift	Runtime/controller wiring.
ModuleRegistry.swift	Registers app-owned module factories.
ContentView.swift	Chooses developer shell or production app UI.

Template Authoring Flow

flowchart TD
    A["Create module with Xcode template"] --> B["Add Forsetti package products"]
    B --> C["Confirm manifest is in Resources/ForsettiManifests"]
    C --> D["Register entry point"]
    D --> E["Register injected views if UI/app module"]
    E --> F["Boot in development mode"]
    F --> G["Run tests and guardrails"]
    G --> H["Switch production mode when ready"]

Loading

Common Template Fixes

Symptom	Fix
Template appears but app does not compile	Add ForsettiCore, ForsettiPlatform, and ForsettiHostTemplate products to the target.
Manifest is not discovered	Confirm it is bundled under Resources/ForsettiManifests.
Module does not activate	Confirm entryPoint matches the registry key.
Injected view is blank	Register the viewID in ForsettiViewInjectionRegistry.
Production UI still shows controls	Set deployment mode to production and render app-owned UI.