Introduction
Flutter's Material and Cupertino libraries are undergoing a major transition. As of April 7th, the code in the flutter/flutter repository is frozen, meaning no new changes can be merged. This is the first step toward moving these libraries into dedicated packages (material_ui and cupertino_ui) on pub.dev. If you contribute to these libraries or rely on them in your plugins, this guide will walk you through what you need to know and what actions to take. From handling open pull requests to preparing for the eventual migration, we've got you covered.
What You Need
- A Flutter project or plugin that uses Material or Cupertino widgets.
- Access to the flutter/flutter and flutter/packages repositories (if you contribute).
- Familiarity with Git, pull requests, and issue tracking on GitHub.
- Flutter SDK version 3.44 or later (for a smooth migration path).
- A development environment set up for Flutter (any channel: stable, beta, dev).
Step-by-Step Guide
Step 1: Understand the Code Freeze and Its Implications
The freeze means that from April 7 onward, no new commits to the Material and Cupertino libraries within flutter/flutter will be accepted. This ensures that the code copied to the new packages is stable. If you don't contribute to these libraries, you can skip the remaining steps—your apps will continue to work without immediate changes. However, if you do contribute, read on.
Step 2: Keep Your Existing Pull Requests Open
If you have open PRs that modify Material or Cupertino code, do not close them. Reviewers will still provide feedback and updates. Once the new packages (material_ui and cupertino_ui) are published on pub.dev, instructions will be provided on how to port your PRs to the flutter/packages repository. Your changes will eventually be released as part of a new package version.
Step 3: Track Existing Issues in the Same Repository
Issues related to Material and Cupertino will remain in the flutter/flutter issue tracker—they won't be moved. This is consistent with how other packages in flutter/packages are handled. If you filed a bug or feature request, continue monitoring it in the same location. No action is needed from you for now.
Step 4: Prepare Your Environment for Migration
To ensure a seamless transition when the new packages are released, upgrade your Flutter SDK to version 3.44 or above. This release contains the frozen copy of Material and Cupertino that will be used as the base for the new packages. By being on this version, you guarantee that any future upgrade will not introduce breaking changes until you explicitly migrate to the new packages.
Step 5: After Package Release – Port PRs and Migrate
Once the 1.0.0 versions of material_ui and cupertino_ui are published, follow the official instructions to port any open PRs to the flutter/packages repo. This typically involves rebasing your changes onto the new repository and updating imports. For app developers, the migration guide will explain how to add the package dependencies and replace the old imports.
Step 6: Be Ready for Deprecation and Removal
The old Material and Cupertino code inside flutter/flutter will be deprecated in the stable release following 3.44, and removed entirely in a later release. When that time comes, detailed migration instructions will be published. You need to have migrated your projects to the new packages before then to avoid build failures. Mark your calendar and stay tuned to Flutter's official channels.
Tips for a Smooth Transition
- Monitor announcements: Follow the Flutter team on GitHub, Twitter, or the Flutter blog to catch migration instructions as soon as they drop.
- Test early: As soon as the new packages are available, test your app or plugin with them in a sandbox environment. Identify any breaking changes before the old code is removed.
- Update your CI/CD pipelines: If your continuous integration relies on the old library locations, update them to use the new packages once the migration is official.
- Engage with the community: Discuss migration issues on the Flutter Discord or GitHub discussions. You’re not alone in this transition.
- Use the frozen SDK as a baseline: Until you migrate, stick with a Flutter SDK that includes the frozen libraries (3.44+). Avoid upgrading to later SDK versions that may have already deprecated or removed the old code.