How to Navigate Flutter's Material and Cupertino Library Decoupling
By
<h2>Introduction</h2>
<p>Flutter's Material and Cupertino libraries are undergoing a major transition. As of April 7th, the code in the <strong>flutter/flutter</strong> repository is frozen, meaning no new changes can be merged. This is the first step toward moving these libraries into dedicated packages (<em>material_ui</em> and <em>cupertino_ui</em>) on <strong>pub.dev</strong>. 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.</p><figure style="margin:20px 0"><img src="https://picsum.photos/seed/2763239272/800/450" alt="How to Navigate Flutter's Material and Cupertino Library Decoupling" 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 Flutter project or plugin that uses Material or Cupertino widgets.</li>
<li>Access to the <strong>flutter/flutter</strong> and <strong>flutter/packages</strong> repositories (if you contribute).</li>
<li>Familiarity with Git, pull requests, and issue tracking on GitHub.</li>
<li>Flutter SDK version 3.44 or later (for a smooth migration path).</li>
<li>A development environment set up for Flutter (any channel: stable, beta, dev).</li>
</ul>
<h2>Step-by-Step Guide</h2>
<h3 id="step1">Step 1: Understand the Code Freeze and Its Implications</h3>
<p>The freeze means that from April 7 onward, no new commits to the Material and Cupertino libraries within <strong>flutter/flutter</strong> 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.</p>
<h3 id="step2">Step 2: Keep Your Existing Pull Requests Open</h3>
<p>If you have open PRs that modify Material or Cupertino code, <strong>do not close them</strong>. Reviewers will still provide feedback and updates. Once the new packages (<em>material_ui</em> and <em>cupertino_ui</em>) are published on pub.dev, instructions will be provided on how to port your PRs to the <strong>flutter/packages</strong> repository. Your changes will eventually be released as part of a new package version.</p>
<h3 id="step3">Step 3: Track Existing Issues in the Same Repository</h3>
<p>Issues related to Material and Cupertino will remain in the <strong>flutter/flutter</strong> issue tracker—they won't be moved. This is consistent with how other packages in <strong>flutter/packages</strong> 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.</p>
<h3 id="step4">Step 4: Prepare Your Environment for Migration</h3>
<p>To ensure a seamless transition when the new packages are released, upgrade your Flutter SDK to version <strong>3.44 or above</strong>. 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.</p>
<h3 id="step5">Step 5: After Package Release – Port PRs and Migrate</h3>
<p>Once the 1.0.0 versions of <em>material_ui</em> and <em>cupertino_ui</em> are published, follow the official instructions to port any open PRs to the <strong>flutter/packages</strong> 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.</p>
<h3 id="step6">Step 6: Be Ready for Deprecation and Removal</h3>
<p>The old Material and Cupertino code inside <strong>flutter/flutter</strong> 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.</p>
<h2>Tips for a Smooth Transition</h2>
<ul>
<li><strong>Monitor announcements:</strong> Follow the Flutter team on GitHub, Twitter, or the Flutter blog to catch migration instructions as soon as they drop.</li>
<li><strong>Test early:</strong> 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.</li>
<li><strong>Update your CI/CD pipelines:</strong> If your continuous integration relies on the old library locations, update them to use the new packages once the migration is official.</li>
<li><strong>Engage with the community:</strong> Discuss migration issues on the Flutter Discord or GitHub discussions. You’re not alone in this transition.</li>
<li><strong>Use the frozen SDK as a baseline:</strong> 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.</li>
</ul>