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

<h2 id="overview">Overview</h2> <p>Flutter's framework is undergoing a significant architectural shift: the Material and Cupertino design libraries are being extracted from the core <code>flutter/flutter</code> repository into dedicated packages—<strong>material_ui</strong> and <strong>cupertino_ui</strong>—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.</p><figure style="margin:20px 0"><img src="https://picsum.photos/seed/1527524360/800/450" alt="Navigating the Flutter Material and Cupertino Code Freeze: A Comprehensive Guide" style="width:100%;height:auto;border-radius:8px" loading="lazy"><figcaption style="font-size:12px;color:#666;margin-top:5px"></figcaption></figure> <p>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.</p> <h2 id="prerequisites">Prerequisites</h2> <p>To follow this guide effectively, you should:</p> <ul> <li>Be familiar with Flutter development and the framework's repository structure.</li> <li>Have experience opening and managing pull requests (PRs) in the <code>flutter/flutter</code> repository.</li> <li>Understand the difference between the <code>flutter/flutter</code> monorepo and the <code>flutter/packages</code> repository.</li> <li>Know how to use <code>git</code> and the <code>flutter</code> command-line tool.</li> <li>Be aware of the Flutter release channels (stable, beta, dev, master).</li> </ul> <h2 id="step-by-step">Step-by-Step Instructions</h2> <h3 id="step1-understand-the-freeze">Step 1: Understand What the Freeze Entails</h3> <p>The code freeze means that <strong>no new changes</strong> will be accepted into the Material and Cupertino libraries inside <code>flutter/flutter</code>. This includes bug fixes, enhancements, or new widgets. All future development will resume in the <code>flutter/packages</code> repository once the new packages (<code>material_ui</code> and <code>cupertino_ui</code>) 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.</p> <h3 id="step2-if-you-have-open-prs">Step 2: What to Do if You Have Open Pull Requests</h3> <p>If you have an open PR that modifies files in the <code>flutter/lib/src/material/</code> or <code>flutter/lib/src/cupertino/</code> directories, <strong>do not close it</strong>.</p> <ol> <li><strong>Keep the PR open.</strong> Reviewers will continue to provide feedback and review your changes as usual.</li> <li><strong>Wait for the package release.</strong> Once the <code>material_ui</code> and <code>cupertino_ui</code> packages are published on pub.dev, the Flutter team will provide instructions on how to port your PR to the <code>flutter/packages</code> repository.</li> <li><strong>Port your changes.</strong> 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 <code>material_ui</code> or <code>cupertino_ui</code>.</li> </ol> <p>If you need to test your changes locally, you can still build Flutter from source using the frozen code in <code>flutter/flutter</code>. Just be aware that your final solution will need to target the packages repository.</p> <h3 id="step3-handling-issues">Step 3: Reporting or Working on Issues</h3> <p>Issues related to Material or Cupertino will <strong>remain in the <code>flutter/flutter</code> issue tracker</strong>. This unified approach is the same pattern used for other packages in the <code>flutter/packages</code> repo and a few other repositories. If you encounter a bug or have a feature request:</p> <ul> <li>File the issue as you normally would in the <code>flutter/flutter</code> repo.</li> <li>Label it appropriately (e.g., "material", "cupertino").</li> <li>Do not expect fixes to land in the frozen framework code. Instead, fixes will be implemented in the new packages once they are released.</li> </ul> <p>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.</p> <h3 id="step4-for-plugin-and-app-developers">Step 4: For Plugin and App Developers (Not Yet Affected)</h3> <p>If you are not actively contributing to Material or Cupertino, the freeze has <strong>no immediate impact</strong> 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.</p> <p>However, after the 3.44 stable release is published, the new packages will be available. At that point:</p> <ul> <li>The old Material and Cupertino code inside the framework will be <strong>deprecated</strong> in the stable release immediately following 3.44.</li> <li>Eventually, the deprecated code will be removed.</li> <li>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.</li> </ul> <p>For now, you can stay tuned for announcements and continue using the standard Flutter SDK.</p> <h3 id="step5-migration-preparation">Step 5: Prepare for the Migration (Future Step)</h3> <p>Although the migration is not yet required, you can start preparing:</p> <ol> <li><strong>Stay on the latest stable channel.</strong> 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.</li> <li><strong>Review your imports.</strong> Identify places where you directly import from <code>package:flutter/material.dart</code> or <code>package:flutter/cupertino.dart</code>. These will eventually need to be replaced with <code>package:material_ui/material_ui.dart</code> or <code>package:cupertino_ui/cupertino_ui.dart</code>.</li> <li><strong>Watch for deprecation warnings.</strong> After the deprecation is introduced, your IDE or <code>flutter analyze</code> will flag deprecated imports. Address them promptly.</li> <li><strong>Test your app with the new packages.</strong> Once the packages are published, you can add them to your <code>pubspec.yaml</code> and run <code>flutter pub get</code> to start using them. Follow the official migration guide for any breaking changes.</li> </ol> <h2 id="common-mistakes">Common Mistakes to Avoid</h2> <ul> <li><strong>Closing open PRs prematurely.</strong> Many contributors might think the freeze means their PRs are rejected. Do not close them; they will be ported to the new packages.</li> <li><strong>Ignoring deprecation warnings.</strong> Once deprecation begins, putting off updates can lead to broken builds when the old code is deleted. Plan your migration early.</li> <li><strong>Migrating too early.</strong> 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.</li> <li><strong>Filing issues in the wrong repository.</strong> Keep issues related to Material/Cupertino in <code>flutter/flutter</code>; do not file them in <code>flutter/packages</code> unless they are about the new packages specifically.</li> <li><strong>Assuming the freeze affects app developers.</strong> If you do not contribute to the libraries themselves, you do not need to take any action yet—continue developing as usual.</li> </ul> <h2 id="summary">Summary</h2> <p>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 <code>material_ui</code> and <code>cupertino_ui</code> packages. By understanding the freeze and following these steps, you can ensure a smooth transition when the time comes.</p>