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

<h2>Introduction</h2> <p>The Flutter team has announced a significant milestone: the <strong>Material</strong> and <strong>Cupertino</strong> libraries within the main Flutter framework (<code>flutter/flutter</code>) 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 <code>material_ui</code> and <code>cupertino_ui</code> on <a href="https://pub.dev">pub.dev</a>. 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.</p><figure style="margin:20px 0"><img src="https://picsum.photos/seed/3782892437/800/450" alt="Navigating the Flutter Material and Cupertino Code Freeze: A Step-by-Step Guide" style="width:100%;height:auto;border-radius:8px" loading="lazy"><figcaption style="font-size:12px;color:#666;margin-top:5px"></figcaption></figure> <h2>What You Need</h2> <ul> <li>A basic understanding of Flutter development and the official <code>flutter/flutter</code> repository.</li> <li>Access to your Flutter environment (SDK version 3.44 or later for the migration).</li> <li>For contributors: an active GitHub account with any pending pull requests (PRs) or issues.</li> <li>Familiarity with <a href="https://pub.dev">pub.dev</a> for package usage (optional for now).</li> </ul> <h2>Step 1: Understand the Code Freeze and Its Implications</h2> <p id="step1">The code freeze means that the Flutter team will stop merging any pull requests that modify the <code>material</code> or <code>cupertino</code> directories inside the <code>flutter/flutter</code> 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 (<code>material_ui</code> and <code>cupertino_ui</code>) are released (planned after the 3.44 stable release), all future development will happen in the <code>flutter/packages</code> 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.</p> <h2>Step 2: Determine If You Are Affected</h2> <p id="step2">Your next action depends on your role:</p> <ul> <li><strong>App or plugin developers</strong> who do <em>not</em> 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).</li> <li><strong>Active contributors</strong> to these libraries: you are directly affected. Continue with the steps below to handle your existing work and stay informed about the transition.</li> </ul> <h2>Step 3: Handle Existing Open Pull Requests (PRs)</h2> <p id="step3">If you have pull requests that touch Material or Cupertino code:</p> <ol> <li><strong>Do not close them.</strong> Leave them open in <code>flutter/flutter</code>.</li> <li>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.</li> <li>Once <code>material_ui</code> and <code>cupertino_ui</code> are live, the Flutter team will publish instructions on how to port your PRs to the <code>flutter/packages</code> repository. Follow those instructions carefully.</li> <li><strong>Tip:</strong> Keep an eye on the official <a href="https://github.com/flutter/flutter/issues">flutter/flutter issues</a> and the <a href="https://github.com/flutter/packages">flutter/packages</a> repository for the exact porting guidance.</li> </ol> <h2>Step 4: Manage New and Existing Issues</h2> <p id="step4">Issues related to Material or Cupertino will <strong>not</strong> be moved. They will continue to live in the <code>flutter/flutter</code> 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.</p> <h2>Step 5: Prepare for the Future Migration (After 3.44)</h2> <p id="step5">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:</p> <ul> <li><strong>Update your Flutter SDK</strong> 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.</li> <li><strong>Watch for deprecation notices.</strong> The old Material and Cupertino code inside <code>flutter/flutter</code> will be deprecated in the stable release <em>after</em> 3.44. At that point, you’ll see warnings in your IDE.</li> <li><strong>Plan for the eventual deletion</strong> 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.</li> </ul> <h2>Step 6: For Contributors – Know the Timeline</h2> <p id="step6">If you actively develop Material or Cupertino widgets, keep these milestones in mind:</p> <ul> <li><strong>Code freeze effective:</strong> April 7. No more merges into these libraries in <code>flutter/flutter</code>.</li> <li><strong>Next stable release (3.44):</strong> the frozen code is published as part of the stable SDK.</li> <li><strong>After 3.44:</strong> publication of <code>material_ui</code> and <code>cupertino_ui</code> packages on pub.dev. Development resumes in <code>flutter/packages</code>.</li> <li><strong>Following stable release:</strong> deprecation of the old libraries in the framework.</li> <li><strong>Later release:</strong> removal of the old code.</li> </ul> <h2>Tips and Best Practices</h2> <ul> <li><strong>Stay informed:</strong> Follow the <a href="https://github.com/flutter/flutter/issues">flutter/flutter issue tracker</a> and the official Flutter blog for announcements about the new packages and migration guides.</li> <li><strong>Don’t panic:</strong> The code freeze is designed to create a seamless migration path. The Flutter team is deliberately keeping breaking changes to a minimum.</li> <li><strong>If you’re a contributor:</strong> prepare by familiarizing yourself with the <code>flutter/packages</code> repository structure and contribution guidelines. This will speed up the porting of your PRs.</li> <li><strong>For app developers:</strong> you don’t need to do anything immediately, but consider adding the <code>material_ui</code> and <code>cupertino_ui</code> packages to your <code>pubspec.yaml</code> once they are stable. This proactive step avoids a last‑minute migration scramble.</li> <li><strong>Testing:</strong> After the migration, run your project’s tests thoroughly. Although the API should be identical, package‑specific dependencies might require minor adjustments.</li> <li><strong>Community support:</strong> Join the Flutter community forums or Discord to share experiences and get help from others who have already made the switch.</li> </ul> <p>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.</p>