lambda swift logo

lambda swift

What makes a SwiftUI app?

SwiftUI introduced a new application model that departs from the traditional main() function entry point. To understand the bare minimum needed for a functioning SwiftUI app, we must explore how Swift determines an entry point for programs, how the @main attribute and the SwiftUI App protocol work together, and how scenes like WindowGroup allow us to render views.

Entry Points: Command-Line Tools vs. GUI Applications

Every program needs an entry point – the place where execution begins. In a simple command-line tool, this is often a main function. For example, a C program calls a main function to start, and a Swift script or command-line tool can simply execute top-level code. In Swift, if you compile a single file with top-level statements, those statements implicitly form the entry point of the program (no explicit main function is needed). For instance, a one-file Swift program containing: 

print("Hello, World!")

can be compiled and run, and it will print Hello, World! to standard output. Swift automatically treats the top-level code in that single source file as the program’s entry point.

Graphical apps (such as iOS or macOS applications), however, differ from command-line tools because they need to stay running to respond to user events. Simply executing some code and exiting is not sufficient – an event loop must be started to keep the app alive. Traditionally, Cocoa (for macOS) and UIKit (for iOS) apps use special main functions that never return. These functions set up the application object, delegate, and run loop. For example, a minimal main.swift for an macOS app might look like this:

import Cocoa

NSApplicationMain(
  CommandLine.argc,
  CommandLine.unsafeArgv
)

This call to NSApplicationMain creates the application, then hands control to macOS’s event loop. On iOS, an analogous UIApplicationMain function is used to launch the app and start the UIKit event loop. The program will continue running inside these frameworks’ event loops until the user quits the app.

In practice, app developers rarely write a main.swift manually. In Objective-C era Xcode templates, a main.m file was generated with this boilerplate. In Swift, attributes were introduced to reduce this redundancy. Marking the app delegate class with @UIApplicationMain (or @NSApplicationMain on Mac) tells the compiler to synthesize the necessary main for you behind the scenes.

The Unified @main Attribute in Swift

Swift 5.3 introduced a more general, platform-independent mechanism for specifying an entry point: the @main attribute. This attribute can be applied to a class, struct, or enum to designate it as the program’s entry point. Using @main on a type implies that the type will provide a static main() function or otherwise satisfy the entry-point requirements. The compiler will invoke that main() to launch the program, instead of looking for a free-floating top-level code sequence or a main.swift file.

Under the hood, using @main on a type causes the Swift compiler to generate the needed boilerplate to call into your type’s main() method. This unified attribute supersedes the older @UIApplicationMain/@NSApplicationMain attributes (which have been formally deprecated in favor of @main as of Swift 5.10). In fact, before Swift 5.3, the @UIApplicationMain attribute was essentially doing the same job for UIApplication-based apps. Now, @main can be used in many contexts — including SwiftUI apps — to mark the single entry point of the program.

It is important to note that you can have only one @main entry point in the entire program. The Swift compiler enforces rules to avoid ambiguity in finding the start of execution. In summary, the compiler determines the entry point according to these rules:

  1. Single-file program – If you compile a single Swift file (with no other source files), any top-level code in that file is automatically the entry point (an implicit main). No explicit @main is needed in this case.
  2. Multi-file program – If your program has multiple Swift source files, by default Swift treats them as library code, which means top-level executable statements are disallowed (to prevent undefined startup order). In a multi-file setup, you must provide an explicit entry point (for example, by marking one type with @main or having a dedicated main.swift file).
  3. main.swift file present – As a special case in a multi-file program, if one source file is literally named main.swift, Swift will allow top-level code in that file and use it as the entry point. This is how traditional apps were structured if not using the attribute – the main.swift contained the call to UIApplicationMain/NSApplicationMain as shown above.

Because of these rules, if you try to use @main in a context where the compiler is already using top-level code as an entry point, you will get a compile error. For example, marking a type with @main in a single-file script that contains top-level statements will produce an error: “'main' attribute cannot be used in a module that contains top-level code.”. In other words, you should either use the attribute or* use top-level code, but not both. (The Swift compiler even suggests using the flag -parse-as-library to treat the file as library code if you intend to use @main in a single file scenario. In an Xcode project, this situation is usually avoided by default, because SwiftUI app templates do not include any top-level code – they rely exclusively on the @main attribute on the app’s type.

SwiftUI’s App Protocol and Lifecycle

With the advent of SwiftUI (introduced in iOS 14 and related platforms), Apple provided a new app lifecycle that does not require a traditional app delegate or storyboard. Instead, a SwiftUI app is defined by a type conforming to the App protocol. This protocol (part of SwiftUI) represents the structure of an application. Here is a simplified definition of SwiftUI’s App protocol:

public protocol App {
  associatedtype Body: Scene
  var body: Self.Body { get }
  init()
}

In essence, any struct or class that conforms to App must have an initializer and a computed property body that provides the contents of the app. The body is defined to be some type of Scene – in practice, this is the scene (or collection of scenes) that your app will display. The requirement of an init() means the app must be instantiable; for example, an enum cannot conform to App because Swift enums without cases have no natural initializer (and nontrivial enums cannot be instantiated without a case). In contrast, a struct or class can satisfy this easily. Typically, the App conforming type is a struct with no stored properties (or only simple stored properties with default values), so it gets a default initializer automatically.

Marking your app struct with the @main attribute signals that this is the application’s entry point. SwiftUI leverages a protocol extension to provide the actual implementation of the required static main() for any App. In the SwiftUI framework, App has an extension that looks roughly like:

extension App {
  public static func main() { /* ... default implementation ... */ }
}

SwiftUI provides a default implementation of this main() method behind the scenes (it is not directly visible in our code). When you build a SwiftUI app, the system will call this synthesized App.main() to launch your application. The default implementation takes care of all the heavy lifting: it initializes the SwiftUI framework, creates the application instance, configures the app’s environment, and ultimately calls into the appropriate runtime functions to run the app. In fact, if one sets a breakpoint on the underlying UIApplicationMain (on iOS) or NSApplicationMain (on macOS), you can observe that those functions are invoked during the launch of a SwiftUI app. This confirms that under the hood, SwiftUI’s app lifecycle still builds on the platform’s native application startup mechanism. The difference is that SwiftUI abstracts it away so the developer never has to call these functions directly; they are called within the framework’s default main() implementation.

It’s worth noting that the SwiftUI app lifecycle introduced with App does not use the UIKit UIApplicationDelegate by default. Many responsibilities that used to live in an app delegate (or in the newer UISceneDelegate for multi-scene UIKit apps) are handled via SwiftUI modifiers and environment updates. For example, SwiftUI provides property wrappers and environment values to respond to app lifecycle events (such as scene phase changes) instead of delegate methods. If needed, you can still integrate an app delegate by using UIApplicationDelegateAdaptor, but it is not required for a basic SwiftUI app. The bare minimum SwiftUI app can be defined entirely with the App struct and its scenes.

Scenes and WindowGroup: Rendering Views in SwiftUI

The body of an App returns one or more scenes. A Scene in SwiftUI represents one instance of UI content that the app can display. Just as views are the building blocks of UI, scenes are the building blocks of apps in the SwiftUI lifecycle. SwiftUI defines a Scene protocol, which is conceptually similar to the View protocol (it even has a similar structure with an associated Body):

public protocol Scene {
  associatedtype Body: Scene
  var body: Self.Body { get }
}

Like View, Scene can have a recursive body (one scene can contain or return another scene). In practice, we don’t usually create custom types conforming to Scene from scratch. Instead, SwiftUI provides several concrete scene types for common use cases, and we compose our app from those. Currently the standard scene types include:

  • WindowGroup – A group of one or more app windows that display a given view hierarchy. This is the most common scene for basic apps, and on iOS/iPadOS it integrates with the system’s multi-window support (each WindowGroup can spawn multiple windows on iPad, or a single window on iPhone by default).
  • DocumentGroup – A scene type for document-based apps, managing the creation and opening of document files. This is used when your app is centered around editing or viewing documents.
  • Settings – A scene for a preferences/settings window (macOS only). Apps can use this to provide a standard Preferences window on Mac.
  • Window – A single dedicated window scene (macOS only), typically used when you want a fixed primary window instead of a window group.
  • MenuBarExtra – A scene for creating a menu bar extra on macOS (an icon in the menu bar with a pop-up menu or window).

Each of these structures conforms to Scene. Most SwiftUI apps use at least one WindowGroup in their App’s body. A WindowGroup scene acts as a container that will create a window for your app’s user interface. Inside the WindowGroup, you provide a view (using a ViewBuilder closure) that defines the content of the window. This is where your SwiftUI views are finally linked to the app lifecycle – the framework will create a window and host the view you return, rendering it on screen.

A Minimal SwiftUI App Example

Putting it all together, what is the smallest complete SwiftUI app? It’s essentially an @main app struct with a body containing a window and a view. For example, the ubiquitous “Hello, world” app in SwiftUI can be written as follows:

import SwiftUI

@main
struct HelloApp: App {
  var body: some Scene {
    WindowGroup {
      Text("Hello, World!")
    }
  }
}

This definition meets all the requirements for a SwiftUI application:

  • We import the SwiftUI framework, which is necessary to use App, WindowGroup, and SwiftUI views.
  • We declare a struct HelloApp that conforms to the App protocol. Marking it with @main makes it the entry point for the program.
  • The struct has a synthesized initializer (no custom init needed) and a computed property body that returns a scene. In this case, the scene is a WindowGroup.
  • The WindowGroup in turn contains a view – here we use a Text view with the classic "Hello, World!" string. This is the content that will appear in the app’s window.

When this program is launched, SwiftUI’s runtime will call the static main() provided by the App protocol (via the @main attribute on HelloApp). That will set up the application (equivalent to calling UIApplicationMain on iOS or NSApplicationMain on macOS under the hood) and create an instance of HelloApp. SwiftUI will then evaluate the body property to get the app’s scenes. In our case, it creates a WindowGroup scene and, inside it, a Text("Hello, World!") view. The framework takes care of creating a window for the WindowGroup and rendering the Text view in that window. The app will remain running, handling UI events, without any further code from us.

In summary, a SwiftUI app is defined by its App struct and scene content, rather than an explicit main() function that calls into UI frameworks. The minimum to get a SwiftUI app running is simply an @main conforming type to App with at least one scene in its body. There is no need to write a main.swift file, no need to manually call UIApplicationMain, and no need for an app delegate for basic tasks – the SwiftUI framework and the system manage all of that on your behalf. By understanding the roles of the @main attribute, the App protocol, and scene types like WindowGroup, we gain insight into how SwiftUI applications are structured and launched. This modern approach simplifies application bootstrap to just declaring your app’s structure, allowing developers to focus on the UI and behavior, while SwiftUI and Swift handle the entry point and lifecycle behind the scenes.

Swift Language Fundamentals →