Replaceplugin_name throughout this guide with the name of your plugin. The example below usesios, replaceios withmacos/darwin as applicable.

1. Turn on the Swift Package Manager feature.

2. Start by creating a directory under theios,macos, and/ordarwin directories. Name this new directory the name of the platform package.

   • plugin_name/

     • ios/

       • …
       • plugin_name/

3. Within this new directory, create the following files/directories:

   • Package.swift (file)
   • Sources (directory)
   • Sources/plugin_name (directory)

   Your plugin should look like:

   • plugin_name/

     • ios/

       • …
       • plugin_name/

         • Package.swift
         • Sources/

           • plugin_name/

4. Use the following template in thePackage.swift file:

   Package.swift

   swift

   // swift-tools-version: 5.9// The swift-tools-version declares the minimum version of Swift required to build this package.​importPackageDescription​letpackage=Package(// TODO: Update your plugin name.name:"plugin_name",platforms:[// TODO: Update the platforms your plugin supports.// If your plugin only supports iOS, remove `.macOS(...)`.// If your plugin only supports macOS, remove `.iOS(...)`..iOS("13.0"),.macOS("10.15")],products:[// TODO: Update your library and target names.// If the plugin name contains "_", replace with "-" for the library name..library(name:"plugin-name",targets:["plugin_name"])],dependencies:[],targets:[.target(// TODO: Update your target name.name:"plugin_name",dependencies:[],resources:[// TODO: If your plugin requires a privacy manifest// (e.g. if it uses any required reason APIs), update the PrivacyInfo.xcprivacy file// to describe your plugin's privacy impact, and then uncomment this line.// For more information, see:// https://developer.apple.com/documentation/bundleresources/privacy_manifest_files// .process("PrivacyInfo.xcprivacy"),​// TODO: 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])])

   content_copy

5. Update thesupported platforms in yourPackage.swift file.

   Package.swift

   swift

   platforms:[// TODO: Update the platforms your plugin supports.// If your plugin only supports iOS, remove `.macOS(...)`.// If your plugin only supports macOS, remove `.iOS(...)`..iOS("13.0"),.macOS("10.15")],

   content_copy

6. Update the package, library, and target names in yourPackage.swift file.

   Package.swift

   swift

   letpackage=Package(// TODO: Update your plugin name.name:"plugin_name",platforms:[.iOS("13.0"),.macOS("10.15")],products:[// TODO: Update your library and target names.// If the plugin name contains "_", replace with "-" for the library name.library(name:"plugin-name",targets:["plugin_name"])],dependencies:[],targets:[.target(// TODO: Update your target name.name:"plugin_name",dependencies:[],resources:[// TODO: If your plugin requires a privacy manifest// (e.g. if it uses any required reason APIs), update the PrivacyInfo.xcprivacy file// to describe your plugin's privacy impact, and then uncomment this line.// For more information, see:// https://developer.apple.com/documentation/bundleresources/privacy_manifest_files// .process("PrivacyInfo.xcprivacy"),​// TODO: 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])])

   content_copy
   infoNote

   If the plugin name contains_, the library name must be a- separated version of the plugin name.

7. If your plugin has aPrivacyInfo.xcprivacy file, move it toios/plugin_name/Sources/plugin_name/PrivacyInfo.xcprivacy and uncomment the resource in thePackage.swift file.

   Package.swift

   swift

   resources:[// TODO: If your plugin requires a privacy manifest// (e.g. if it uses any required reason APIs), update the PrivacyInfo.xcprivacy file// to describe your plugin's privacy impact, and then uncomment this line.// For more information, see:// https://developer.apple.com/documentation/bundleresources/privacy_manifest_files.process("PrivacyInfo.xcprivacy"),​// TODO: 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],

   content_copy

8. Move any resource files fromios/Assets toios/plugin_name/Sources/plugin_name (or a subdirectory). Add the resource files to yourPackage.swift file, if applicable. For more instructions, seehttps://developer.apple.com/documentation/xcode/bundling-resources-with-a-swift-package.

9. Move all files fromios/Classes toios/plugin_name/Sources/plugin_name.

10. Theios/Assets,ios/Resources, andios/Classes directories should now be empty and can be deleted.

11. If your plugin usesPigeon, update your Pigeon input file.

    pigeons/messages.dart

    dart

    kotlinOptions:KotlinOptions(),javaOut:'android/app/src/main/java/io/flutter/plugins/Messages.java',javaOptions:JavaOptions(),swiftOut:'ios/Classes/messages.g.swift',swiftOut:'ios/plugin_name/Sources/plugin_name/messages.g.swift',swiftOptions:SwiftOptions(),

    content_copy

12. Update yourPackage.swift file with any customizations you might need.

    1. Open theios/plugin_name/ directory in Xcode.

    2. In Xcode, open yourPackage.swift file. Verify Xcode doesn't produce any warnings or errors for this file.

       lightbulbTip

       If Xcode doesn't show any files, quit Xcode (Xcode > Quit Xcode) and reopen.

       If Xcode doesn't update after you make a change, try clickingFile > Packages > Reset Package Caches.

    3. If yourios/plugin_name.podspec file hasCocoaPodsdependencys, add the correspondingSwift Package Manager dependencies to yourPackage.swift file.

    4. If your package must be linked explicitlystatic ordynamic (not recommended by Apple), update theProduct to define the type:

       Package.swift

       swift

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

       content_copy

    5. Make any other customizations. For more information on how to write aPackage.swift file, seehttps://developer.apple.com/documentation/packagedescription.

       lightbulbTip

       If you add targets to yourPackage.swift file, use unique names. This avoids conflicts with targets from other packages.

13. Update yourios/plugin_name.podspec to point to new paths.

    ios/plugin_name.podspec

    ruby

    s.source_files='Classes/**/*.swift's.resource_bundles={'plugin_name_privacy'=>['Resources/PrivacyInfo.xcprivacy']}s.source_files='plugin_name/Sources/plugin_name/**/*.swift's.resource_bundles={'plugin_name_privacy'=>['plugin_name/Sources/plugin_name/PrivacyInfo.xcprivacy']}

    content_copy

14. Update loading of resources from bundle to useBundle.module.

    swift

    #ifSWIFT_PACKAGEletsettingsURL=Bundle.module.url(forResource:"image",withExtension:"jpg")#elseletsettingsURL=Bundle(for:Self.self).url(forResource:"image",withExtension:"jpg")#endif

    content_copy
    infoNote

    Bundle.module only works if there are resourcesdefined in thePackage.swift file orautomatically included by Xcode). Otherwise, usingBundle.module results in an error.

15. If your.gitignore doesn't include.build/ and.swiftpm/ directories, you'll want to update your.gitignore to include:

    .gitignore

    .build/.swiftpm/

    content_copy

    Commit your plugin's changes to your version control system.

16. Verify the plugin still works with CocoaPods.

    1. Turn off Swift Package Manager.

       sh

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

       content_copy

    2. Navigate to the plugin's example app.

       sh

       cd path/to/plugin/example/

       content_copy

    3. Ensure the plugin's example app builds and runs.

       sh

       flutter run

       content_copy

    4. Navigate to the plugin's top-level directory.

       sh

       cd path/to/plugin/

       content_copy

    5. Run CocoaPods validation lints.

       sh

       pod lib lint ios/plugin_name.podspec  --configuration=Debug --skip-tests --use-modular-headers --use-libraries

       content_copy
       sh

       pod lib lint ios/plugin_name.podspec  --configuration=Debug --skip-tests --use-modular-headers

       content_copy

17. Verify the plugin works with Swift Package Manager.

    1. Turn on Swift Package Manager.

       sh

       flutter config --enable-swift-package-manager

       content_copy

    2. Navigate to the plugin's example app.

       sh

       cd path/to/plugin/example/

       content_copy

    3. Ensure the plugin's example app builds and runs.

       sh

       flutter run

       content_copy
       infoNote

       Using the Flutter CLI to run the plugin's example app with the Swift Package Manager feature turned on migrates the project to add Swift Package Manager integration.

       This raises the example app's Flutter SDK requirement to version 3.24 or higher.

       If you'd like to run the example app using an older Flutter SDK version, do not commit the migration's changes to your version control system. If needed, you can alwaysundo the Swift Package Manager migration.

    4. Open the plugin's example app in Xcode. Ensure thatPackage Dependencies shows in the leftProject Navigator.

18. Verify tests pass.

    • If your plugin has native unit tests (XCTest), make sure you alsoupdate unit tests in the plugin's example app.

    • Follow instructions fortesting plugins.

Replaceplugin_name throughout this guide with the name of your plugin. The example below usesios, replaceios withmacos/darwin as applicable.

1. Turn on the Swift Package Manager feature.

2. Start by creating a directory under theios,macos, and/ordarwin directories. Name this new directory the name of the platform package.

   • plugin_name/

     • ios/

       • …
       • plugin_name/

3. Within this new directory, create the following files/directories:

   • Package.swift (file)
   • Sources (directory)
   • Sources/plugin_name (directory)
   • Sources/plugin_name/include (directory)
   • Sources/plugin_name/include/plugin_name (directory)
   • Sources/plugin_name/include/plugin_name/.gitkeep (file)
     • This file ensures the directory is committed. You can remove the.gitkeep file if other files are added to the directory.

   Your plugin should look like:

   • plugin_name/

     • ios/

       • …
       • plugin_name/

         • Package.swift
         • Sources/plugin_name/include/plugin_name/

           • .gitkeep/

4. Use the following template in thePackage.swift file:

   Package.swift

   swift

   // swift-tools-version: 5.9// The swift-tools-version declares the minimum version of Swift required to build this package.​importPackageDescription​letpackage=Package(// TODO: Update your plugin name.name:"plugin_name",platforms:[// TODO: Update the platforms your plugin supports.// If your plugin only supports iOS, remove `.macOS(...)`.// If your plugin only supports macOS, remove `.iOS(...)`..iOS("13.0"),.macOS("10.15")],products:[// TODO: Update your library and target names.// If the plugin name contains "_", replace with "-" for the library name.library(name:"plugin-name",targets:["plugin_name"])],dependencies:[],targets:[.target(// TODO: Update your target name.name:"plugin_name",dependencies:[],resources:[// TODO: If your plugin requires a privacy manifest// (e.g. if it uses any required reason APIs), update the PrivacyInfo.xcprivacy file// to describe your plugin's privacy impact, and then uncomment this line.// For more information, see:// https://developer.apple.com/documentation/bundleresources/privacy_manifest_files// .process("PrivacyInfo.xcprivacy"),​// TODO: 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:[// TODO: Update your plugin name..headerSearchPath("include/plugin_name")])])

   content_copy

5. Update thesupported platforms in yourPackage.swift file.

   Package.swift

   swift

   platforms:[// TODO: Update the platforms your plugin supports.// If your plugin only supports iOS, remove `.macOS(...)`.// If your plugin only supports macOS, remove `.iOS(...)`..iOS("13.0"),.macOS("10.15")],

   content_copy

6. Update the package, library, and target names in yourPackage.swift file.

   Package.swift

   swift

   letpackage=Package(// TODO: Update your plugin name.name:"plugin_name",platforms:[.iOS("13.0"),.macOS("10.15")],products:[// TODO: Update your library and target names.// If the plugin name contains "_", replace with "-" for the library name.library(name:"plugin-name",targets:["plugin_name"])],dependencies:[],targets:[.target(// TODO: Update your target name.name:"plugin_name",dependencies:[],resources:[// TODO: If your plugin requires a privacy manifest// (e.g. if it uses any required reason APIs), update the PrivacyInfo.xcprivacy file// to describe your plugin's privacy impact, and then uncomment this line.// For more information, see:// https://developer.apple.com/documentation/bundleresources/privacy_manifest_files// .process("PrivacyInfo.xcprivacy"),​// TODO: 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:[// TODO: Update your plugin name..headerSearchPath("include/plugin_name")])])

   content_copy
   infoNote

   If the plugin name contains_, the library name must be a- separated version of the plugin name.

7. If your plugin has aPrivacyInfo.xcprivacy file, move it toios/plugin_name/Sources/plugin_name/PrivacyInfo.xcprivacy and uncomment the resource in thePackage.swift file.

   Package.swift

   swift

   resources:[// TODO: If your plugin requires a privacy manifest// (e.g. if it uses any required reason APIs), update the PrivacyInfo.xcprivacy file// to describe your plugin's privacy impact, and then uncomment this line.// For more information, see:// https://developer.apple.com/documentation/bundleresources/privacy_manifest_files.process("PrivacyInfo.xcprivacy"),​// TODO: 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],

   content_copy

8. Move any resource files fromios/Assets toios/plugin_name/Sources/plugin_name (or a subdirectory). Add the resource files to yourPackage.swift file, if applicable. For more instructions, seehttps://developer.apple.com/documentation/xcode/bundling-resources-with-a-swift-package.

9. Move any public headers fromios/Classes toios/plugin_name/Sources/plugin_name/include/plugin_name.

   • If you're unsure which headers are public, check yourpodspec file'spublic_header_files attribute. If this attribute isn't specified, all of your headers were public. You should consider whether you want all of your headers to be public.

   • ThepluginClass defined in yourpubspec.yaml file must be public and within this directory.

10. Handlingmodulemap.

    Skip this step if your plugin does not have amodulemap.

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

    To remove themodulemap for Swift Package Manager but keep it for CocoaPods, exclude themodulemap and umbrella header in the plugin'sPackage.swift file.

    The example below assumes themodulemap and umbrella header are located in theios/plugin_name/Sources/plugin_name/include directory.

    Package.swift

    swift

    .target(name:"plugin_name",dependencies:[],exclude:["include/cocoapods_plugin_name.modulemap","include/plugin_name-umbrella.h"],

    content_copy

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

    Tests/TestFile.m

    objc

    @importplugin_name;@importplugin_name.Test;#if __has_include(<plugin_name/plugin_name-umbrella.h>)@importplugin_name.Test;#endif

    content_copy

    If you would like to use a custommodulemap with your Swift package, refer toSwift Package Manager's documentation.

11. Move all remaining files fromios/Classes toios/plugin_name/Sources/plugin_name.

12. Theios/Assets,ios/Resources, andios/Classes directories should now be empty and can be deleted.

13. If your header files are no longer in the same directory as your implementation files, you should update your import statements.

    For example, imagine the following migration:

    • Before:

      ios/Classes/├── PublicHeaderFile.h└── ImplementationFile.m

      content_copy

    • After:

      ios/plugin_name/Sources/plugin_name/└── include/plugin_name/   └── PublicHeaderFile.h└── ImplementationFile.m

      content_copy

    In this example, the import statements inImplementationFile.m should be updated:

    Sources/plugin_name/ImplementationFile.m

    objc

    #import "PublicHeaderFile.h"#import "./include/plugin_name/PublicHeaderFile.h"

    content_copy

14. If your plugin usesPigeon, update your Pigeon input file.

    pigeons/messages.dart

    dart

    javaOptions:JavaOptions(),objcHeaderOut:'ios/Classes/messages.g.h',objcSourceOut:'ios/Classes/messages.g.m',objcHeaderOut:'ios/plugin_name/Sources/plugin_name/messages.g.h',objcSourceOut:'ios/plugin_name/Sources/plugin_name/messages.g.m',copyrightHeader:'pigeons/copyright.txt',

    content_copy

    If yourobjcHeaderOut file is no longer within the same directory as theobjcSourceOut, you can change the#import usingObjcOptions.headerIncludePath:

    pigeons/messages.dart

    dart

    javaOptions:JavaOptions(),objcHeaderOut:'ios/Classes/messages.g.h',objcSourceOut:'ios/Classes/messages.g.m',objcHeaderOut:'ios/plugin_name/Sources/plugin_name/include/plugin_name/messages.g.h',objcSourceOut:'ios/plugin_name/Sources/plugin_name/messages.g.m',objcOptions:ObjcOptions(headerIncludePath:'./include/plugin_name/messages.g.h',),copyrightHeader:'pigeons/copyright.txt',

    content_copy

    Run Pigeon to re-generate its code with the latest configuration.

15. Update yourPackage.swift file with any customizations you might need.

    1. Open theios/plugin_name/ directory in Xcode.

    2. In Xcode, open yourPackage.swift file. Verify Xcode doesn't produce any warnings or errors for this file.

       lightbulbTip

       If Xcode doesn't show any files, quit Xcode (Xcode > Quit Xcode) and reopen.

       If Xcode doesn't update after you make a change, try clickingFile > Packages > Reset Package Caches.

    3. If yourios/plugin_name.podspec file hasCocoaPodsdependencys, add the correspondingSwift Package Manager dependencies to yourPackage.swift file.

    4. If your package must be linked explicitlystatic ordynamic (not recommended by Apple), update theProduct to define the type:

       Package.swift

       swift

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

       content_copy

    5. Make any other customizations. For more information on how to write aPackage.swift file, seehttps://developer.apple.com/documentation/packagedescription.

       lightbulbTip

       If you add targets to yourPackage.swift file, use unique names. This avoids conflicts with targets from other packages.

16. Update yourios/plugin_name.podspec to point to new paths.

    ios/plugin_name.podspec

    ruby

    s.source_files='Classes/**/*.{h,m}'s.public_header_files='Classes/**/*.h's.module_map='Classes/cocoapods_plugin_name.modulemap's.resource_bundles={'plugin_name_privacy'=>['Resources/PrivacyInfo.xcprivacy']}s.source_files='plugin_name/Sources/plugin_name/**/*.{h,m}'s.public_header_files='plugin_name/Sources/plugin_name/include/**/*.h's.module_map='plugin_name/Sources/plugin_name/include/cocoapods_plugin_name.modulemap's.resource_bundles={'plugin_name_privacy'=>['plugin_name/Sources/plugin_name/PrivacyInfo.xcprivacy']}

    content_copy

17. Update loading of resources from bundle to useSWIFTPM_MODULE_BUNDLE:

    objc

    #if SWIFT_PACKAGENSBundle*bundle=SWIFTPM_MODULE_BUNDLE;#elseNSBundle*bundle=[NSBundlebundleForClass:[selfclass]];#endifNSURL*imageURL=[bundleURLForResource:@"image"withExtension:@"jpg"];

    content_copy
    infoNote

    SWIFTPM_MODULE_BUNDLE only works if there are actual resources (eitherdefined in thePackage.swift file orautomatically included by Xcode). Otherwise, usingSWIFTPM_MODULE_BUNDLE results in an error.

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

    .gitignore

    !.gitkeep

    content_copy

    Runflutter pub publish --dry-run to ensure theinclude directory is published.

19. Commit your plugin's changes to your version control system.

20. Verify the plugin still works with CocoaPods.

    1. Turn off Swift Package Manager:

       sh

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

       content_copy

    2. Navigate to the plugin's example app.

       sh

       cd path/to/plugin/example/

       content_copy

    3. Ensure the plugin's example app builds and runs.

       sh

       flutter run

       content_copy

    4. Navigate to the plugin's top-level directory.

       sh

       cd path/to/plugin/

       content_copy

    5. Run CocoaPods validation lints:

       sh

       pod lib lint ios/plugin_name.podspec  --configuration=Debug --skip-tests --use-modular-headers --use-libraries

       content_copy
       sh

       pod lib lint ios/plugin_name.podspec  --configuration=Debug --skip-tests --use-modular-headers

       content_copy

21. Verify the plugin works with Swift Package Manager.

    1. Turn on Swift Package Manager:

       sh

       flutter config --enable-swift-package-manager

       content_copy

    2. Navigate to the plugin's example app.

       sh

       cd path/to/plugin/example/

       content_copy

    3. Ensure the plugin's example app builds and runs.

       sh

       flutter run

       content_copy
       infoNote

       Using the Flutter CLI to run the plugin's example app with the Swift Package Manager feature turned on migrates the project to add Swift Package Manager integration.

       This raises the example app's Flutter SDK requirement to version 3.24 or higher.

       If you'd like to run the example app using an older Flutter SDK version, do not commit the migration's changes to your version control system. If needed, you can alwaysundo the Swift Package Manager migration.

    4. Open the plugin's example app in Xcode. Ensure thatPackage Dependencies shows in the leftProject Navigator.

22. Verify tests pass.

    • If your plugin has native unit tests (XCTest), make sure you alsoupdate unit tests in the plugin's example app.

    • Follow instructions fortesting plugins.