Firebase Basics

Firebase iOS Setup Guide

⛔️ CRITICAL RULE: STATE MANAGEMENT (OBSERVATION VS COMBINE) ⛔️

When writing or updating SwiftUI code, you MUST prioritize the modern Swift Observation framework (@Observable macro and @State) as your default approach.

However, it is acceptable to use Combine (ObservableObject, @Published, @StateObject, @EnvironmentObject) under the following conditions:

• The user explicitly asks you to use Combine.

• There are strong signals in the existing codebase that the project is heavily relying on Combine.

If neither of those conditions are true, default to the Swift 5.9+ Observation framework.

⛔️ CRITICAL RULE: INITIALIZATION ORDER ⛔️

When using SwiftUI, you MUST ensure FirebaseApp.configure() is called BEFORE any Firebase-dependent state objects are initialized.

• UNSAFE (CRASH): Declaring a @State (for @Observable) or @StateObject (for Combine) property in the root App struct if its initializer touches Firebase. Property initializers run before the App.init() body, meaning the object's init() will fire before Firebase is configured.

• SAFE: Initialize Firebase in App.init() and pass your state objects into the sub-views (like ContentView), or use onAppear for delayed setup.

Failing to follow this will result in a fatal crash: Default FirebaseApp is not configured.

1. Create a Firebase Project and App (Automated)

Do not use the Firebase Console. Use the CLI to automate setup:

1. Create the project: npx -y firebase-tools@latest projects:create

2. Action: Read the Xcode project (.pbxproj or Info.plist) to determine the iOS bundle ID.

3. Register the iOS app: npx -y firebase-tools@latest apps:create IOS <bundle-id>

4. Fetch the config: npx -y firebase-tools@latest apps:sdkconfig IOS <App-ID>

5. Save the output as GoogleService-Info.plist in your Xcode project folder. Ensure you remove any non-XML CLI output headers, and ensure the file is linked to the main application target.

2. Installation (Automated via Swift Package Manager CLI)

Do not use raw text parsing, sed, or Ruby scripts (like xcodeproj gem) to modify .pbxproj files directly.

Instead, use the xcode-project-setup skill. Load that skill using your tools to securely execute its native Swift package setup script. That skill handles installing the required SPM packages and safely linking the GoogleService-Info.plist file.

💡 TIP: ALWAYS USE THE LATEST SDK VERSION To ensure access to the latest features and security fixes, always check for the most recent version of the Firebase iOS SDK at https://github.com/firebase/firebase-ios-sdk/releases and use that version when adding the SPM dependency.

3. Initialization

Configure the shared FirebaseApp instance. You can do this either in a modern SwiftUI App structure or a traditional AppDelegate.

SwiftUI (Modern - SAFE PATTERN)

import SwiftUI
import FirebaseCore

@main
struct YourApp: App {
  // ⛔️ FATAL CRASH: @State private var auth = AuthManager()
  // property initializers run before init(), causing FirebaseApp not configured error
  @State private var authManager: AuthManager

  init() {
    // ✅ SAFE: This runs FIRST
    FirebaseApp.configure()
    
    // ✅ SAFE: Initialize state ONLY AFTER Firebase is configured
    _authManager = State(initialValue: AuthManager())
  }

  var body: some Scene {
    WindowGroup {
      ContentView()
        .environment(authManager)
    }
  }
}

AppDelegate (Traditional / UIKit)

import UIKit
import FirebaseCore

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(_ application: UIApplication,
                   didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
    // ✅ SAFE: Always the first line in didFinishLaunching
    FirebaseApp.configure()
    return true
  }
}

4. App Check (Debug Token Persistence)

When using App Check in local development or the iOS Simulator, the Firebase iOS SDK generates a new UUID debug token whenever NSUserDefaults is erased (such as during a simulator reset or fresh install). This causes debug token churn and invalidates tokens previously registered in the Firebase console.

[!WARNING] CRITICAL: Never Hardcode or Commit Debug Tokens App Check debug tokens allow clients to bypass attestation and access backend resources without a genuine device. Treat them as sensitive secrets. Never commit debug tokens into version control or hardcode them directly into source code. If a token is compromised, revoke it immediately in the Firebase Console.

To persist a stable debug token across simulator resets without committing secrets:

1. Obtain or generate a stable UUID debug token and register it in the Firebase Console under Security > App Check > Apps > Manage debug tokens.

2. Supply AppCheckDebugToken via your local environment instead of hardcoding it in code:

   • Xcode Scheme Environment Variables (Recommended):

     • Select Product > Scheme > Edit Scheme... (or Cmd + <).

     • Navigate to Run > Arguments > Environment Variables.

     • Add AppCheckDebugToken = <YOUR_DEBUG_TOKEN>.

     • Tip: Keep your personal scheme unshared or ensure user scheme data (xcuserdata/) is included in .gitignore so your personal debug token is not committed.

   • In Code (Only with Secure / Gitignored Loading): If setting the environment variable in code before initializing AppCheckDebugProviderFactory, load the token dynamically from a gitignored local file or build configuration—never hardcode the raw token string:

     Copy

     #if DEBUG
     // ⛔️ DO NOT hardcode literal tokens: setenv("AppCheckDebugToken", "secret-uuid", 0)
     // ✅ SAFE: Load dynamically from a gitignored local file, xcconfig, or process environment
     // Note: loadGitIgnoredDebugToken() is a placeholder for your custom helper (e.g., reading from a gitignored plist)
     if let debugToken = loadGitIgnoredDebugToken() {
       setenv("AppCheckDebugToken", debugToken, 0)
     }
     let providerFactory = AppCheckDebugProviderFactory()
     AppCheck.setAppCheckProviderFactory(providerFactory)
     #endif
     
     FirebaseApp.configure() // Must be called AFTER setting the App Check provider factory

Setting this environment variable avoids invalidating tokens registered in the Firebase console by ensuring a consistent debug token is reused across simulator resets and fresh app installs.