From a68d28424dde3958576035300a406b791d8b05e5 Mon Sep 17 00:00:00 2001
From: Zayin Krige <zkrige@gmail.com>
Date: Wed, 21 Oct 2026 06:27:49 +0200
Subject: [PATCH] feat(apple): let the host app supply the FlutterDartProject
 for background engines

BackgroundWorker created its headless FlutterEngine with project: nil, so every
task built a fresh FlutterDartProject whose settings can differ from the main
engine's. Add WorkmanagerPlugin.setDartProject(_:) so the host app can share
one project with the background engines. Behavior is unchanged when it is not
called.
---
 docs/quickstart.mdx                              | 13 +++++++++++++
 .../workmanager_apple/BackgroundWorker.swift     |  2 +-
 .../workmanager_apple/WorkmanagerPlugin.swift    | 16 ++++++++++++++++
 3 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
index 59b6ce2e..517aafe4 100644
--- a/docs/quickstart.mdx
+++ b/docs/quickstart.mdx
@@ -85,6 +85,19 @@ import workmanager_apple
 }
 ```
 
+Background engines create their own `FlutterDartProject` by default. If your
+app needs them to use the same project as the main engine (for example when a
+code push tool resolves the newest downloaded patch each time a project is
+created), create one project at launch, pass it to your engine, and call
+`WorkmanagerPlugin.setDartProject(_:)` with it before any task runs:
+
+```swift
+let project = FlutterDartProject()
+WorkmanagerPlugin.setDartProject(project)
+```
+
+When the call is omitted, behavior is unchanged.
+
 <Info>
 **UIScene lifecycle:** Apple requires UIKit apps to adopt the UIScene lifecycle
 from the release following iOS 26. After migration, call
diff --git a/workmanager_apple/ios/workmanager_apple/Sources/workmanager_apple/BackgroundWorker.swift b/workmanager_apple/ios/workmanager_apple/Sources/workmanager_apple/BackgroundWorker.swift
index 8f9b7fbb..770c682d 100644
--- a/workmanager_apple/ios/workmanager_apple/Sources/workmanager_apple/BackgroundWorker.swift
+++ b/workmanager_apple/ios/workmanager_apple/Sources/workmanager_apple/BackgroundWorker.swift
@@ -158,7 +158,7 @@ class BackgroundWorker {
 
         var flutterEngine: FlutterEngine? = FlutterEngine(
             name: backgroundMode.flutterThreadlabelPrefix,
-            project: nil,
+            project: WorkmanagerPlugin.dartProject,
             allowHeadlessExecution: true
         )
 
diff --git a/workmanager_apple/ios/workmanager_apple/Sources/workmanager_apple/WorkmanagerPlugin.swift b/workmanager_apple/ios/workmanager_apple/Sources/workmanager_apple/WorkmanagerPlugin.swift
index bcfaf6ab..bf07a2dc 100644
--- a/workmanager_apple/ios/workmanager_apple/Sources/workmanager_apple/WorkmanagerPlugin.swift
+++ b/workmanager_apple/ios/workmanager_apple/Sources/workmanager_apple/WorkmanagerPlugin.swift
@@ -45,6 +45,22 @@ public class WorkmanagerPlugin: WorkmanagerPluginBase, FlutterPlugin, Workmanage
     /// (fluttercommunity/flutter_workmanager#653).
     static var mainBinaryMessenger: FlutterBinaryMessenger?
 
+    static var dartProject: FlutterDartProject?
+
+    /// Sets the `FlutterDartProject` used by the background engines.
+    ///
+    /// Without this call each background engine creates its own project. Apps
+    /// whose project settings change while the app runs (for example code push
+    /// tools that resolve the newest downloaded patch when a project is
+    /// created) should create one project at launch and share it with the main
+    /// engine and with this plugin.
+    ///
+    /// - Parameter project: The project the host app created at launch
+    @objc
+    public static func setDartProject(_ project: FlutterDartProject) {
+        dartProject = project
+    }
+
     /// Sets the plugin registrant callback for background task execution.
     ///
     /// This callback is used to register additional plugins when background tasks