Navigating the Flutter Material and Cupertino Code Freeze: A Comprehensive Guide

Overview

Flutter's framework is undergoing a significant architectural shift: the Material and Cupertino design libraries are being extracted from the core flutter/flutter repository into dedicated packages—material_ui and cupertino_ui—hosted on pub.dev. As of April 7th, the Flutter team has frozen all contributions to these libraries within the main framework repository. This guide explains what the freeze means, how it affects different stakeholders (contributors, plugin authors, and app developers), and what steps you need to take now—and in the near future—to stay aligned with the upcoming changes.

If you write Flutter applications or plugins but never directly modify Material or Cupertino widgets, you can stop reading now; the freeze will not impact your daily work until the migration phase begins after the 3.44 stable release. However, if you are an active contributor or a developer who depends on internal APIs from these libraries, read on.

Prerequisites

To follow this guide effectively, you should:

• Be familiar with Flutter development and the framework's repository structure.
• Have experience opening and managing pull requests (PRs) in the flutter/flutter repository.
• Understand the difference between the flutter/flutter monorepo and the flutter/packages repository.
• Know how to use git and the flutter command-line tool.
• Be aware of the Flutter release channels (stable, beta, dev, master).

Step-by-Step Instructions

Step 1: Understand What the Freeze Entails

The code freeze means that no new changes will be accepted into the Material and Cupertino libraries inside flutter/flutter. This includes bug fixes, enhancements, or new widgets. All future development will resume in the flutter/packages repository once the new packages (material_ui and cupertino_ui) are published. The goal is to ensure a seamless migration path: the frozen code in the framework will be copied verbatim to the packages, so developers from any Flutter channel will have a consistent starting point when they upgrade to version 3.44 or later.

Step 2: What to Do if You Have Open Pull Requests

If you have an open PR that modifies files in the flutter/lib/src/material/ or flutter/lib/src/cupertino/ directories, do not close it.

1. Keep the PR open. Reviewers will continue to provide feedback and review your changes as usual.
2. Wait for the package release. Once the material_ui and cupertino_ui packages are published on pub.dev, the Flutter team will provide instructions on how to port your PR to the flutter/packages repository.
3. Port your changes. Follow the official porting guide (to be published) to move your modifications to the new packages. Your change will eventually ship as part of a new version of material_ui or cupertino_ui.

If you need to test your changes locally, you can still build Flutter from source using the frozen code in flutter/flutter. Just be aware that your final solution will need to target the packages repository.

Step 3: Reporting or Working on Issues

Issues related to Material or Cupertino will remain in the flutter/flutter issue tracker. This unified approach is the same pattern used for other packages in the flutter/packages repo and a few other repositories. If you encounter a bug or have a feature request:

• File the issue as you normally would in the flutter/flutter repo.
• Label it appropriately (e.g., "material", "cupertino").
• Do not expect fixes to land in the frozen framework code. Instead, fixes will be implemented in the new packages once they are released.

This means that for the short term, some issues may linger until the migration completes. The Flutter team will address them in the packages repository.

Step 4: For Plugin and App Developers (Not Yet Affected)

If you are not actively contributing to Material or Cupertino, the freeze has no immediate impact on your development workflow. You can continue using the existing Material and Cupertino widgets as before. The code freeze only affects contributions to the libraries themselves.

However, after the 3.44 stable release is published, the new packages will be available. At that point:

• The old Material and Cupertino code inside the framework will be deprecated in the stable release immediately following 3.44.
• Eventually, the deprecated code will be removed.
• You will need to migrate your projects to depend on the new packages. The Flutter team will provide detailed migration instructions when that time comes.

For now, you can stay tuned for announcements and continue using the standard Flutter SDK.

Step 5: Prepare for the Migration (Future Step)

Although the migration is not yet required, you can start preparing:

1. Stay on the latest stable channel. Upgrade your Flutter SDK to the latest stable version (or at least to 3.44 once released). The migration will require you to be on 3.44 or later.
2. Review your imports. Identify places where you directly import from package:flutter/material.dart or package:flutter/cupertino.dart. These will eventually need to be replaced with package:material_ui/material_ui.dart or package:cupertino_ui/cupertino_ui.dart.
3. Watch for deprecation warnings. After the deprecation is introduced, your IDE or flutter analyze will flag deprecated imports. Address them promptly.
4. Test your app with the new packages. Once the packages are published, you can add them to your pubspec.yaml and run flutter pub get to start using them. Follow the official migration guide for any breaking changes.

Common Mistakes to Avoid

• Closing open PRs prematurely. Many contributors might think the freeze means their PRs are rejected. Do not close them; they will be ported to the new packages.
• Ignoring deprecation warnings. Once deprecation begins, putting off updates can lead to broken builds when the old code is deleted. Plan your migration early.
• Migrating too early. Do not attempt to switch to the new packages before they are officially released and the migration guide is published. You risk using unstable APIs.
• Filing issues in the wrong repository. Keep issues related to Material/Cupertino in flutter/flutter; do not file them in flutter/packages unless they are about the new packages specifically.
• Assuming the freeze affects app developers. If you do not contribute to the libraries themselves, you do not need to take any action yet—continue developing as usual.

Summary

The Flutter Material and Cupertino code freeze marks a pivotal step toward decoupling these design libraries from the core framework. Active contributors should keep their PRs open and await porting instructions. All developers should stay on the latest stable channel and prepare for the eventual migration to the material_ui and cupertino_ui packages. By understanding the freeze and following these steps, you can ensure a smooth transition when the time comes.