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 --> Gate["Production root<br/>boot and activate"]
    Gate --> AppView["AppModuleView<br/>product UI after activation"]
    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. Production mode does not render the app module view until runtime boot and explicit app module activation have succeeded.

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.

The starter app module manifest includes view_injection because the generated app module contributes its primary view through UIContributions.

Template Manifest Contract

New templates should emit schema 1.1 manifests with manifest template 1.1. The manifest should declare capabilities and runtime requirements together so activation failures are diagnosable from the manifest alone.

{
  "schemaVersion": "1.1",
  "manifestTemplateVersion": "1.1",
  "moduleID": "com.example.app.module",
  "displayName": "Example App Module",
  "moduleVersion": {
    "major": 1,
    "minor": 0,
    "patch": 0
  },
  "moduleType": "app",
  "supportedPlatforms": ["iOS", "macOS"],
  "minForsettiVersion": {
    "major": 0,
    "minor": 1,
    "patch": 1
  },
  "maxForsettiVersion": null,
  "capabilitiesRequested": ["view_injection", "toolbar_items"],
  "iapProductID": null,
  "entryPoint": "ExampleAppModule",
  "defaultModuleRole": "ui",
  "runtimeRequirements": {
    "io": [],
    "ui": {
      "viewIDs": ["example.primary"],
      "slotIDs": ["main"],
      "toolbarItemIDs": ["example.refresh"],
      "routeIDs": [],
      "pointerIDs": []
    },
    "dataIsolation": {
      "mode": "private_to_module",
      "ownedStoreIDs": [],
      "requiredDefaultRoles": []
    }
  }
}

flowchart TD
    Template["Xcode template"] --> Swift["Swift module class"]
    Template --> Manifest["Schema 1.1 manifest"]
    Manifest --> Capabilities["capabilitiesRequested"]
    Manifest --> Runtime["runtimeRequirements"]
    Swift --> Registry["entryPoint registration"]
    Runtime --> Activation["Runtime validation before start(context)"]
    Registry --> Activation

Loading

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.
Activation fails with unsatisfiedRuntimeRequirement	Confirm capabilities, runtime requirements, default roles, and host providers are aligned.
Module activates in development but not production	Confirm production boot uses the configured app module ID and that activation succeeds before rendering.
Injected view is blank	Register the viewID in ForsettiViewInjectionRegistry.
Production UI still shows controls	Set deployment mode to production and use the generated production root path.