Navigating the Flutter Material and Cupertino Code Freeze: A Step-by-Step Guide

Introduction

The Flutter team has announced a significant milestone: the Material and Cupertino libraries within the main Flutter framework (flutter/flutter) are now frozen as of April 7. This means no further code changes will be accepted in these libraries inside the core repository. Instead, these libraries will be re‑released as independent packages named material_ui and cupertino_ui on pub.dev. Whether you’re a Flutter app developer, plugin author, or active contributor to Material or Cupertino, this guide walks you through every step you need to take right now — and what to expect in the coming months.

What You Need

• A basic understanding of Flutter development and the official flutter/flutter repository.
• Access to your Flutter environment (SDK version 3.44 or later for the migration).
• For contributors: an active GitHub account with any pending pull requests (PRs) or issues.
• Familiarity with pub.dev for package usage (optional for now).

Step 1: Understand the Code Freeze and Its Implications

The code freeze means that the Flutter team will stop merging any pull requests that modify the material or cupertino directories inside the flutter/flutter repository. The goal is to create a stable, identical copy of these libraries that will be used as the foundation for the new packages. Once the packages (material_ui and cupertino_ui) are released (planned after the 3.44 stable release), all future development will happen in the flutter/packages repository. For end‑users, this change is transparent for now — you can continue using the existing Material and Cupertino widgets in your apps without any immediate action.

Step 2: Determine If You Are Affected

Your next action depends on your role:

• App or plugin developers who do not contribute to the Material or Cupertino source code: you can stop reading after this step. The freeze does not impact your day‑to‑day development. However, you will need to prepare for a future migration once the new packages become the standard (more on that in Step 5).
• Active contributors to these libraries: you are directly affected. Continue with the steps below to handle your existing work and stay informed about the transition.

Step 3: Handle Existing Open Pull Requests (PRs)

If you have pull requests that touch Material or Cupertino code:

1. Do not close them. Leave them open in flutter/flutter.
2. Reviewers will continue to provide feedback and can still approve changes. However, the PRs will not be merged until after the new packages are published.
3. Once material_ui and cupertino_ui are live, the Flutter team will publish instructions on how to port your PRs to the flutter/packages repository. Follow those instructions carefully.
4. Tip: Keep an eye on the official flutter/flutter issues and the flutter/packages repository for the exact porting guidance.

Step 4: Manage New and Existing Issues

Issues related to Material or Cupertino will not be moved. They will continue to live in the flutter/flutter issue tracker — this is the unified approach used for many other packages in the Flutter ecosystem. You can still file new bug reports or feature requests for Material or Cupertino in the same location. There is no need to re‑open issues elsewhere.

Step 5: Prepare for the Future Migration (After 3.44)

Once the 3.44 stable release is out, the new packages will be published and eventually become the recommended way to use Material and Cupertino widgets. Here’s how to get ready:

• Update your Flutter SDK to version 3.44 or above on whatever channel you use (stable, beta, or master). This ensures you have the frozen version of the libraries, which will be the exact copy used for the new packages.
• Watch for deprecation notices. The old Material and Cupertino code inside flutter/flutter will be deprecated in the stable release after 3.44. At that point, you’ll see warnings in your IDE.
• Plan for the eventual deletion of the old code (some time after deprecation). The Flutter team will provide detailed migration instructions when the time comes. Migrating early (by switching to the new packages) will keep your project future‑proof.

Step 6: For Contributors – Know the Timeline

If you actively develop Material or Cupertino widgets, keep these milestones in mind:

• Code freeze effective: April 7. No more merges into these libraries in flutter/flutter.
• Next stable release (3.44): the frozen code is published as part of the stable SDK.
• After 3.44: publication of material_ui and cupertino_ui packages on pub.dev. Development resumes in flutter/packages.
• Following stable release: deprecation of the old libraries in the framework.
• Later release: removal of the old code.

Tips and Best Practices

• Stay informed: Follow the flutter/flutter issue tracker and the official Flutter blog for announcements about the new packages and migration guides.
• Don’t panic: The code freeze is designed to create a seamless migration path. The Flutter team is deliberately keeping breaking changes to a minimum.
• If you’re a contributor: prepare by familiarizing yourself with the flutter/packages repository structure and contribution guidelines. This will speed up the porting of your PRs.
• For app developers: you don’t need to do anything immediately, but consider adding the material_ui and cupertino_ui packages to your pubspec.yaml once they are stable. This proactive step avoids a last‑minute migration scramble.
• Testing: After the migration, run your project’s tests thoroughly. Although the API should be identical, package‑specific dependencies might require minor adjustments.
• Community support: Join the Flutter community forums or Discord to share experiences and get help from others who have already made the switch.

By following these steps, you can navigate the Material and Cupertino code freeze with confidence — whether you’re building apps, contributing code, or planning the next version of your plugin.