Enable Swift Package Manager

Run the following command:

flutter config --enable-swift-package-manager

Disable Swift Package Manager

Disabling Swift Package Manager will cause Flutter to use CocoaPods for all dependencies. However, Swift Package Manager will remain intregrated with your project. To remove integration, follow "How to remove Swift Package Manager integration" instructions below.

Disable for a single project

In the project's pubspec.yaml, under the flutter section, add disable-swift-package-manager: true.

# The following section is specific to Flutter packages.
flutter:
  disable-swift-package-manager: true

Disable globally for all projects

Run the following command:

flutter config --no-enable-swift-package-manager

Converting an existing Objective-C Flutter Plugin to a Swift Package

Replace plugin_name throughout this guide with the name of your plugin.

1. Start by creating a directory under the ios, macos, and/or darwin directories. Name this new directory the name of the platform package. The below example uses ios, replace ios with macos/darwin if applicable.

/plugin_name/plugin_name_ios/ios/plugin_name_ios

2. Within this new directory, create the following files/directories:
   • Package.swift (file)
   • Sources (directory)
   • Sources/plugin_name_ios (directory)
   • Sources/plugin_name_ios/include (directory)
   • Sources/plugin_name_ios/include/plugin_name_ios (directory)
   • Sources/plugin_name_ios/include/plugin_name_ios/.gitkeep (file)
     • Needed to ensure the directory is committed, even if empty. Can be removed if files are added to the directory.

/plugin_name/plugin_name_ios/ios/plugin_name_ios/Package.swift
/plugin_name/plugin_name_ios/ios/plugin_name_ios/Sources
/plugin_name/plugin_name_ios/ios/plugin_name_ios/Sources/plugin_name_ios
/plugin_name/plugin_name_ios/ios/plugin_name_ios/Sources/plugin_name_ios/include
/plugin_name/plugin_name_ios/ios/plugin_name_ios/Sources/plugin_name_ios/include/plugin_name_ios
/plugin_name/plugin_name_ios/ios/plugin_name_ios/Sources/plugin_name_ios/include/plugin_name_ios/.gitkeep

3. Use the following template in the Package.swift

// swift-tools-version: 5.9
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
    name: "plugin_name_ios",
    platforms: [
        .iOS("12.0"),
        .macOS("10.14")
    ],
    products: [
        // If the plugin name contains "_", replace with "-" for the library name
        .library(name: "plugin-name-ios", targets: ["plugin_name_ios"])
    ],
    dependencies: [],
    targets: [
        .target(
            name: "plugin_name_ios",
            dependencies: [],
            resources: [
                // If your plugin requires a privacy manifest, for example if it uses any required
                // reason APIs, update the PrivacyInfo.xcprivacy file to describe your plugin's
                // privacy impact, and then uncomment these lines. For more information, see
                // https://developer.apple.com/documentation/bundleresources/privacy_manifest_files
                // .process("PrivacyInfo.xcprivacy"),

                // If you have other resources that need to be bundled with your plugin, refer to
                // the following instructions to add them:
                // https://developer.apple.com/documentation/xcode/bundling-resources-with-a-swift-package
            ],
            cSettings: [
                .headerSearchPath("include/plugin_name_ios")
            ]
        )
    ]
)

• If the plugin name contains _, the library name must be a - separated version of the plugin name.

4. If your plugin has a PrivacyInfo.xcprivacy, move it to Sources/plugin_name_ios/PrivacyInfo.xcprivacy and uncomment the resource in the Package.swift.

            resources: [
                // If your plugin requires a privacy manifest, for example if it uses any required
                // reason APIs, update the PrivacyInfo.xcprivacy file to describe your plugin's
                // privacy impact, and then uncomment these lines. For more information, see
                // https://developer.apple.com/documentation/bundleresources/privacy_manifest_files
-                // .process("PrivacyInfo.xcprivacy"),
+                .process("PrivacyInfo.xcprivacy"),

                // If you have other resources that need to be bundled with your plugin, refer to
                // the following instructions to add them:
                // https://developer.apple.com/documentation/xcode/bundling-resources-with-a-swift-package
            ],

5. Move any resource files from ios/Assets to Sources/plugin_name_ios (or a subdirectory). Then add them to your Package.swift if applicable. See https://developer.apple.com/documentation/xcode/bundling-resources-with-a-swift-package for more instructions.

6. Move any public headers from ios/Classes to Sources/plugin_name_ios/include/plugin_name_ios

   • If you're unsure what headers are public, check your podspec for public_header_files. If not found, that means all of your headers were public. You should consider whether or not you want all of your headers to be public.
   • The pluginClass defined in your pubspec.yaml must be public and within this directory.

7. Handling modulemap (skip this step if not using a custom modulemap)

   If you're using a modulemap for CocoaPods to create a Test submodule, consider removing it for Swift Package Manager. Note that this will make all public headers available via the module.

   To remove it for Swift Package Manager but keep it for CocoaPods, exclude the modulemap and umbrella header in the plugin's Package.swift. The example below assumes they are located within the Sources/plugin_name_ios directory.

           .target(
               name: "plugin_name_ios",
               dependencies: [],
   +           exclude: ["cocoapods_plugin_name_ios.modulemap", "plugin_name_ios-umbrella.h"],

   If you want to keep your unit tests compatible with both CocoaPods and Swift Package Manager, you can try the following:

   @import plugin_name_ios;
   - @import plugin_name_ios.Test;
   + #if __has_include(<plugin_name_ios/plugin_name_ios-umbrella.h>)
   +   @import plugin_name_ios.Test;
   + #endif

   If you would like to continue using a custom modulemap, please refer to Swift Package Manager's documentation.

8. Move all remaining files from ios/Classes to Sources/plugin_name_ios

9. ios/Assets, ios/Resources, ios/Classes should now be empty and can be deleted

10. If your header files were previously within the same directory as your implementation files, you may need to change your import statements.

For example, if the following changes were made:
* ios/Classes/PublicHeaderFile.h --> Sources/plugin_name_ios/include/plugin_name_ios/PublicHeaderFile.h
* ios/Classes/ImplementationFile.m --> Sources/plugin_name_ios/ImplementationFile.m

Within ImplementationFile.m, the import would change:

- #import "PublicHeaderFile.h"
+ #import "./include/plugin_name_ios/PublicHeaderFile.h"

11. If using pigeon, you'll want to update your pigeon input file

- objcHeaderOut: 'ios/Classes/messages.g.h',
+ objcHeaderOut: 'ios/plugin_name_ios/Sources/plugin_name_ios/messages.g.h',
- objcSourceOut: 'ios/Classes/messages.g.m',
+ objcSourceOut: 'ios/plugin_name_ios/Sources/plugin_name_ios/messages.g.m',

If your objcHeaderOut file is no longer within the same directory as the objcSourceOut, you can change the #import using ObjcOptions.headerIncludePath:

objcHeaderOut: 'ios/plugin_name_ios/Sources/plugin_name_ios/include/plugin_name_ios/messages.g.h',
objcSourceOut: 'ios/plugin_name_ios/Sources/plugin_name_ios/messages.g.m',
+ objcOptions: ObjcOptions(
+   headerIncludePath: './include/plugin_name_ios/messages.g.h',
+ ),

12. Update your Package.swift with any customizations you may need

    1. Open /plugin_name/plugin_name_ios/ios/plugin_name_ios/ in Xcode
       • If package does not show any files in Xcode, quit Xcode (Xcode > Quit Xcode) and reopen
       • You don't need to edit your Package.swift through Xcode, but Xcode will provide helpful feedback
       • If Xcode isn't updating after you make a change, try clicking File > Packages > Reset Package Caches
    2. Add dependencies
    3. If your package must be linked explicitly static or dynamic (not recommended), update the Product to define the type

    products: [
        .library(name: "plugin-name-ios", type: .static, targets: ["plugin_name_ios"])
    ],

    4. Make any other customizations - see https://developer.apple.com/documentation/packagedescription for more info on how to write a Package.swift.
    5. If you add additional targets to your Package.swift, try to name them uniquely. If your target name conflicts with another target from another package, this can cause issues that may require manual intervention to be able to use your plugin.

13. Update your plugin_name_ios.podspec to point to new paths.

- s.source_files = 'Classes/**/*.{h,m}'
+ s.source_files = 'plugin_name_ios/Sources/plugin_name_ios/**/*.{h,m}'

- s.public_header_files = 'Classes/**/*.h'
+ s.public_header_files = 'plugin_name_ios/Sources/plugin_name_ios/include/**/*.h'

- s.module_map = 'Classes/cocoapods_plugin_name_ios.modulemap'
+ s.module_map = 'plugin_name_ios/Sources/plugin_name_ios/include/cocoapods_plugin_name_ios.modulemap'

- s.resource_bundles = {'plugin_name_ios_privacy' => ['Resources/PrivacyInfo.xcprivacy']}
+ s.resource_bundles = {'plugin_name_ios_privacy' => ['plugin_name_ios/Sources/plugin_name_ios/PrivacyInfo.xcprivacy']}

14. Update getting of resources from bundle to use SWIFTPM_MODULE_BUNDLE

#if SWIFT_PACKAGE
   NSBundle *bundle = SWIFTPM_MODULE_BUNDLE;
 #else
   NSBundle *bundle = [NSBundle bundleForClass:[self class]];
 #endif
 NSURL *imageURL = [bundle URLForResource:@"image" withExtension:@"jpg"];

• Note: SWIFTPM_MODULE_BUNDLE will only work if there are actual resources (either defined in the Package.swift or automatically included by Xcode). Otherwise, it will fail.

15. If your plugin_name_ios/Sources/plugin_name_ios/include directory only contains a .gitkeep, you'll want update your .gitignore to include the following:

!.gitkeep

Then run flutter pub publish --dry-run to ensure the include directory will be published.

16. Verify plugin still works with CocoaPods

    1. Disable Swift Package Manager

    flutter config --no-enable-swift-package-manager
    

    2. Run flutter run with the example app and ensure it builds and runs

17. Verify plugin works with Swift Package Manager

    1. Enable Swift Package Manager

    flutter config --enable-swift-package-manager
    

    2. Run flutter run with the example app and ensure it builds and runs
    3. Open the example app in Xcode and ensure Package Dependencies show in the left Project Navigator

18. Verify tests pass

• If your plugin has Native unit tests (XCTest), make sure you also complete "Updating unit tests in plugin example app" below.
• Follow instructions for testing plugins

Converting an existing Swift Flutter Plugin to a Swift Package

Replace plugin_name throughout this guide with the name of your plugin.

1. Start by creating a directory under the ios, macos, and/or darwin directories. Name this new directory the name of the platform package. The below example uses ios, replace ios with macos/darwin if applicable.

/plugin_name/plugin_name_ios/ios/plugin_name_ios

2. Within this new directory, create the following files/directories:
   • Package.swift (file)
   • Sources (directory)
   • Sources/plugin_name_ios (directory)

/plugin_name/plugin_name_ios/ios/plugin_name_ios/Package.swift
/plugin_name/plugin_name_ios/ios/plugin_name_ios/Sources
/plugin_name/plugin_name_ios/ios/plugin_name_ios/Sources/plugin_name_ios

3. Use the following template in the Package.swift

// swift-tools-version: 5.9
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
    name: "plugin_name_ios",
    platforms: [
        .iOS("12.0"),
        .macOS("10.14")
    ],
    products: [
        // If the plugin name contains "_", replace with "-" for the library name
        .library(name: "plugin-name-ios", targets: ["plugin_name_ios"])
    ],
    dependencies: [],
    targets: [
        .target(
            name: "plugin_name_ios",
            dependencies: [],
            resources: [
                // If your plugin requires a privacy manifest, for example if it uses any required
                // reason APIs, update the PrivacyInfo.xcprivacy file to describe your plugin's
                // privacy impact, and then uncomment these lines. For more information, see
                // https://developer.apple.com/documentation/bundleresources/privacy_manifest_files
                // .process("PrivacyInfo.xcprivacy"),

                // If you have other resources that need to be bundled with your plugin, refer to
                // the following instructions to add them:
                // https://developer.apple.com/documentation/xcode/bundling-resources-with-a-swift-package
            ]
        )
    ]
)

• If the plugin name contains _, the library name must be a - separated version of the plugin name.

4. If your plugin has a PrivacyInfo.xcprivacy, move it to Sources/plugin_name_ios/PrivacyInfo.xcprivacy and uncomment the resource in the Package.swift.

            resources: [
                // If your plugin requires a privacy manifest, for example if it uses any required
                // reason APIs, update the PrivacyInfo.xcprivacy file to describe your plugin's
                // privacy impact, and then uncomment these lines. For more information, see
                // https://developer.apple.com/documentation/bundleresources/privacy_manifest_files
-                // .process("PrivacyInfo.xcprivacy"),
+                .process("PrivacyInfo.xcprivacy"),

                // If you have other resources that need to be bundled with your plugin, refer to
                // the following instructions to add them:
                // https://developer.apple.com/documentation/xcode/bundling-resources-with-a-swift-package
            ],

5. Move any resource files from ios/Assets to Sources/plugin_name_ios (or a subdirectory). Then add them to your Package.swift if applicable. See https://developer.apple.com/documentation/xcode/bundling-resources-with-a-swift-package for more instructions.
6. Move all files from ios/Classes to Sources/plugin_name_ios
7. ios/Assets, ios/Resources, ios/Classes should now be empty and can be deleted
8. If using pigeon, you'll want to update your pigeon input file

- swiftOut: 'ios/Classes/messages.g.swift',
+ swiftOut: 'ios/plugin_name_ios/Sources/plugin_name_ios/messages.g.swift',

9. Update your Package.swift with any customizations you may need
   1. Open /plugin_name/plugin_name_ios/ios/plugin_name_ios/ in Xcode
      • If package does not show any files in Xcode, quit Xcode (Xcode > Quit Xcode) and reopen
      • You don't need to edit your Package.swift through Xcode, but Xcode will provide helpful feedback
      • If Xcode isn't updating after you make a change, try clicking File > Packages > Reset Package Caches
   2. Add dependencies
   3. If your package must be linked explicitly static or dynamic, update the Product to define the type

   products: [
       .library(name: "plugin-name-ios", type: .static, targets: ["plugin_name_ios"])
   ],

   4. Make any other customizations - see https://developer.apple.com/documentation/packagedescription for more info on how to write a Package.swift.
   5. If you add additional targets to your Package.swift, try to name them uniquely. If your target name conflicts with another target from another package, this can cause issues that may require manual intervention to be able to use your plugin.
10. Update your plugin_name_ios.podspec to point to new paths.

- s.source_files = 'Classes/**/*.swift'
+ s.source_files = 'plugin_name_ios/Sources/plugin_name_ios/**/*.swift'

- s.resource_bundles = {'plugin_name_ios_privacy' => ['Resources/PrivacyInfo.xcprivacy']}
+ s.resource_bundles = {'plugin_name_ios_privacy' => ['plugin_name_ios/Sources/plugin_name_ios/PrivacyInfo.xcprivacy']}

11. Update getting of resources from bundle to use Bundle.module

#if SWIFT_PACKAGE
     let settingsURL = Bundle.module.url(forResource: "image", withExtension: "jpg")
#else
     let settingsURL = Bundle(for: Self.self).url(forResource: "image", withExtension: "jpg")
#endif

• Note: Bundle.module will only work if there are actual resources (either defined in the Package.swift or automatically included by Xcode). Otherwise, it will fail.

12. Verify plugin still works with CocoaPods
    1. Disable Swift Package Manager

    flutter config --no-enable-swift-package-manager
    

    2. Run flutter run with the example app and ensure it builds and runs
13. Verify plugin works with Swift Package Manager
    1. Enable Swift Package Manager

    flutter config --enable-swift-package-manager
    

    2. Run flutter run with the example app and ensure it builds and runs
    3. Open the example app in Xcode and ensure Package Dependencies show in the left Project Navigator
14. Verify tests pass

• If your plugin has Native unit tests (XCTest), make sure you also complete "Updating unit tests in plugin example app" below.
• Follow instructions for testing plugins

Updating unit tests in plugin example app

If your plugin has native XCTests, you may need to update them to work with Swift Package Manger if one of the following is true:

• You're using a CocoaPod dependency for the test
• Your plugin is explicitly set to type: .dynamic in its Package.swift

1. Open your example/ios/Runner.xcworkspace in Xcode
2. If you were using a CocoaPod dependency for tests, such as OCMock, you'll want to remove it from your Podfile

target 'RunnerTests' do
  inherit! :search_paths
-  pod 'OCMock', '3.5'
end`

Then in the terminal, run pod install in the plugin_name_ios/example/ios directory

3. Navigate to Package Dependencies for the project

4. Click the + button and add any test-only dependencies by searching for them in the top right search bar.

Note: OCMock uses unsafe build flags and cant only be used if targeted by commit. fe1661a3efed11831a6452f4b1a0c5e6ddc08c3d is the commit for the 3.9.3 version.

5. Ensure it is added to the RunnerTests Target and click Add Package button

6. If you've explicitly set your plugin's library type to .dynamic in its Package.swift (not recommended), you'll also need to add it as a dependency to the RunnerTests target.

   1. First, ensure RunnerTests has a Link Binary With Libraries Build Phase
      

   2. If it does not already exist, create one by selecting the + button and selecting New Link Binary With Libraries Phase
      

   3. Navigate to Package Dependencies for the project

   4. Click the + button

   5. Click the Add Local... button on the bottom of the dialog that opens

   6. Navigate to plugin_name/plugin_name_ios/ios/plugin_name_ios and click Add Package button

   7. Ensure it is added to the RunnerTests Target and click Add Package button

7. Ensure tests pass Product > Test

How to manually add Swift Package Manager integration to iOS project if Flutter CLI fails to automatically migrate

Please file a bug before manually migrating to help the Flutter team improve the automatic migration. Please include the error message you received and consider including a copy of the of the following files in your bug report:

• ios/Runner.xcodeproj/project.pbxproj
• ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme (or the xcsheme for the flavor used)

Part 1: Add FlutterGeneratedPluginSwiftPackage Package Dependency

1. Open your app (your_app/ios/Runner.xcworkspace) in Xcode
2. Navigate to Package Dependencies for the project

3. Click the + button
4. Click the Add Local... button on the bottom of the dialog that opens
5. Navigate to your_app/ios/Flutter/Packages/FlutterGeneratedPluginSwiftPackage and click Add Package button
6. Ensure it is added to the Runner Target and click Add Package button

7. Ensure FlutterGeneratedPluginSwiftPackage was added to Frameworks, Libraries, and Embedded Content

Part 2: Add Run Prepare Flutter Framework Script Pre-Action

The following must be completed for each flavor.

1. Next, select Product > Scheme > Edit Scheme
2. Click the > next to "Build" in the left side bar
3. Select Pre-actions
4. Click the + button and select New Run Script Action from the menu
5. Click the "Run Script" title and change to Run Prepare Flutter Framework Script.
6. Change the "Provide build settings from" to the app.
7. Input the following in the text box:

/bin/sh "$FLUTTER_ROOT/packages/flutter_tools/bin/xcode_backend.sh" prepare

Part 3: Run app

1. Run the app in Xcode and ensure FlutterGeneratedPluginSwiftPackage is a target dependency and Run Prepare Flutter Framework Script is being run as a pre-action.

2. Also, ensure the app runs on the command line with flutter run.

How to manually add Swift Package Manager integration to macOS project if Flutter CLI fails to automatically migrate

Please file a bug before manually migrating to help the Flutter team improve the automatic migration. Please include the error message you received and consider including a copy of the of the following files in your bug report:

• macos/Runner.xcodeproj/project.pbxproj
• macos/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme (or the xcscheme for the flavor used)

Part 1: Add FlutterGeneratedPluginSwiftPackage Package Dependency

1. Open your app (your_app/macos/Runner.xcworkspace) in Xcode
2. Navigate to Package Dependencies for the project

3. Click the + button
4. Click the Add Local... button on the bottom of the dialog that opens
5. Navigate to your_app/macos/Flutter/Packages/FlutterGeneratedPluginSwiftPackage and click Add Package button
6. Ensure it is added to the Runner Target and click Add Package button

7. Ensure FlutterGeneratedPluginSwiftPackage was added to Frameworks, Libraries, and Embedded Content

Part 2: Add Run Prepare Flutter Framework Script Pre-Action

The following must be completed for each flavor.

1. Next, select Product > Scheme > Edit Scheme
2. Click the > next to "Build" in the left side bar
3. Select Pre-actions
4. Click the + button and select New Run Script Action from the menu
5. Click the "Run Script" title and change to Run Prepare Flutter Framework Script.
6. Change the "Provide build settings from" to the Runner target.
7. Input the following in the text box:

"$FLUTTER_ROOT"/packages/flutter_tools/bin/macos_assemble.sh prepare

Part 3: Run app

1. Run the app in Xcode and ensure FlutterGeneratedPluginSwiftPackage is a target dependency and Run Prepare Flutter Framework Script is being run as a pre-action.

2. Also, ensure the app runs on the command line with flutter run.

If a Swift Package Flutter plugin requires a higher OS version than the project, you may get an error like this:

Target Integrity (Xcode): The package product 'plugin_name_ios' requires minimum platform version 14.0 for the iOS platform, but this target supports 12.0

To still be able to use the plugin, you'll need to increase the Minimum Deployment of your project to match. Keep in mind, this will increase the minimum OS version that your app can run on.

How to add Swift Package Manager integration to a custom target

Follow the steps in How to manually add Swift Package Manager integration to iOS/macOS project if Flutter CLI fails to automatically migrate.

In Part 1, Step 6 use your custom target instead of the Flutter target.

In Part 2, Step 6 use your custom target instead of the Flutter target.

How to remove Swift Package Manager integration

1. Disable Swift Package Manager (see "Disable Swift Package Manager" instructions above).
2. Open your app (your_app/ios/Runner.xcworkspace) in Xcode
3. Navigate to Package Dependencies for the project
4. Click on the FlutterGeneratedPluginSwiftPackage package and then click the - button

4. Navigate to Frameworks, Libraries, and Embedded Content for the Runner target
5. Click on FlutterGeneratedPluginSwiftPackage and then click the - button

Coming soon...