Skip to content

Commit a875820

Browse files
Piinkssfshaza2
authored andcommitted
Add design migration guide (#13821)
Adds the migration guide for migrating to material_ui and cupertino_ui I believe we'll be adding more docs, or a dedicated page on the site, but it would be great to have a place to point for now that isn't just the latest the release blog. :) We'll be making a bigger call to action to migrate in the Fall release after we deprecate the original libraries. This should be good in the meantime for our early adopters. I already incorporated the early feedback we have received from them. Fixes flutter/flutter#191448 Related to flutter/flutter#191067 ## Presubmit checklist - [x] If you are unwilling, or unable, to sign the CLA, even for a _tiny_, one-word PR, please file an issue instead of a PR. - [ ] If this PR is not meant to land until a future stable release, mark it as draft with an explanation. - [x] This PR follows the [Google Developer Documentation Style Guidelines](https://developers.google.com/style)—for example, it doesn't use _i.e._ or _e.g._, and it avoids _I_ and _we_ (first-person pronouns). - [x] This PR uses [semantic line breaks](https://github.com/dart-lang/site-shared/blob/main/doc/writing-for-dart-and-flutter-websites.md#semantic-line-breaks) of 80 characters or fewer.
1 parent fcfe94f commit a875820

2 files changed

Lines changed: 246 additions & 0 deletions

File tree

‎sites/docs/src/content/release/breaking-changes/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,10 @@ They're sorted by release and listed in alphabetical order:
3737
### Not yet released to stable
3838

3939
* [Added enabled property and made onChanged optional for DropdownButton][]
40+
* [Migrate to standalone `material_ui` and `cupertino_ui` packages][]
4041

4142
[Added enabled property and made onChanged optional for DropdownButton]: /release/breaking-changes/dropdownbutton-enabled-property
43+
[Migrate to standalone `material_ui` and `cupertino_ui` packages]: /release/breaking-changes/material-ui-and-cupertino-ui
4244

4345
<a id="released-in-flutter-347" aria-hidden="true"></a>
4446
### Released in Flutter 3.47
Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
---
2+
title: Migrate to standalone material_ui and cupertino_ui packages
3+
description: >-
4+
The Material and Cupertino design libraries are now available as
5+
standalone packages, decoupling design systems from the Flutter SDK.
6+
---
7+
8+
{% render "docs/breaking-changes.md" %}
9+
10+
## Summary
11+
12+
The Material and Cupertino design libraries are now available as
13+
standalone packages: [`package:material_ui`][] and [`package:cupertino_ui`][].
14+
In Flutter 3.47, developers can opt in to these packages ahead of
15+
the formal deprecation of the in-framework design libraries.
16+
17+
## Background
18+
19+
Historically, Flutter's Material (`package:flutter/material.dart`)
20+
and Cupertino (`package:flutter/cupertino.dart`) widget libraries
21+
were bundled directly inside the core Flutter SDK.
22+
While this made it easy to get started with pixel-perfect widgets,
23+
bundling design systems inside the core framework presented several challenges:
24+
25+
* Widget updates, bug fixes, and new components were tied to
26+
quarterly Flutter SDK releases.
27+
* Contributions and iteration on design libraries moved slower
28+
than standalone Dart packages.
29+
* Applications couldn't update design libraries independently of
30+
the engine and framework.
31+
32+
To resolve these challenges, the design systems are now decoupled
33+
from the core framework.
34+
Starting in Flutter 3.47, version 1.0 of the standalone
35+
`material_ui` and `cupertino_ui` packages is published on `pub.dev`.
36+
37+
Decoupling the design systems provides several benefits:
38+
39+
* **Independent release cycles**:
40+
The packages can ship bug fixes, improvements, and new components
41+
on their own release schedules (planned for weekly releases),
42+
without requiring a full Flutter SDK upgrade.
43+
* **Faster contributions**:
44+
Community members can contribute directly to the libraries in the
45+
[`flutter/packages`][] repository.
46+
* **Style-neutral core**:
47+
Decoupling lays the groundwork for a style-neutral Flutter core widget
48+
catalog, making it easier to build and maintain custom design systems.
49+
50+
Contributions to `package:flutter/material.dart` and
51+
`package:flutter/cupertino.dart` inside the core SDK were frozen
52+
starting in Flutter 3.44.
53+
The initial 1.0.0 versions of `package:material_ui` and `package:cupertino_ui`
54+
match the frozen framework code to provide a seamless transition.
55+
Future releases of the packages will use semantic versioning for major, minor,
56+
and patch updates.
57+
The in-framework design libraries are scheduled for formal deprecation
58+
in an upcoming stable release.
59+
60+
## Migration guide
61+
62+
To migrate your project from the in-framework design libraries to the
63+
standalone packages, you can use the automated `dart fix` tool
64+
or perform the migration manually.
65+
66+
### Automated migration with dart fix
67+
68+
The quickest way to migrate is using the `migrate_design_widgets` fix rule
69+
with `dart fix`:
70+
71+
```console
72+
$ dart fix --apply --code=migrate_design_widgets
73+
```
74+
75+
This command automatically updates your imports from
76+
`package:flutter/material.dart` and `package:flutter/cupertino.dart`
77+
to the corresponding standalone package imports.
78+
79+
:::note
80+
If `dart fix` doesn't automatically add the new packages to your
81+
`pubspec.yaml` dependencies, manually add them by running
82+
`flutter pub add material_ui` or `flutter pub add cupertino_ui` as needed.
83+
:::
84+
85+
Run `dart fix` once more to ensure all other automated migrations are applied,
86+
and lint warnings addressed, such as import sorting.
87+
88+
### Manual migration
89+
90+
To migrate manually, follow these steps:
91+
92+
1. Add the standalone packages to your `pubspec.yaml` dependencies:
93+
94+
```console
95+
$ flutter pub add material_ui
96+
$ flutter pub add cupertino_ui
97+
```
98+
99+
1. Update the imports in your Dart files to reference the new packages.
100+
101+
Code before migration:
102+
103+
```dart
104+
import 'package:flutter/cupertino.dart';
105+
import 'package:flutter/material.dart';
106+
```
107+
108+
Code after migration:
109+
110+
```dart
111+
import 'package:cupertino_ui/cupertino_ui.dart';
112+
import 'package:material_ui/material_ui.dart';
113+
```
114+
115+
### Compatibility bridge
116+
117+
During the ecosystem transition, your application might depend on
118+
third-party packages that still import the legacy in-framework libraries
119+
(`package:flutter/material.dart` or `package:flutter/cupertino.dart`).
120+
121+
To allow your application to migrate to the standalone packages immediately
122+
without waiting for all dependencies to update, `material_ui` and
123+
`cupertino_ui` provide compatibility bridge utilities.
124+
Wrap your app using `MaterialUiCompatibilityBridge` inside
125+
`MaterialApp.builder`:
126+
127+
```dart
128+
import 'package:material_ui/material_ui.dart';
129+
130+
void main() {
131+
runApp(const MyApp());
132+
}
133+
134+
class MyApp extends StatelessWidget {
135+
const MyApp({super.key});
136+
137+
@override
138+
Widget build(BuildContext context) {
139+
return MaterialApp(
140+
theme: ThemeData(
141+
colorScheme: ColorScheme.fromSeed(
142+
seedColor: const Color(0xFF6750A4),
143+
),
144+
),
145+
builder: (BuildContext context, Widget? child) {
146+
return MaterialUiCompatibilityBridge(child: child!);
147+
},
148+
home: const HomeScreen(),
149+
);
150+
}
151+
}
152+
```
153+
154+
#### Bridge capabilities and limitations
155+
156+
`MaterialUiCompatibilityBridge` injects theme and localization data
157+
downward into the widget tree.
158+
This allows unmigrated child widgets and dependencies that read design state
159+
from context
160+
(such as `Theme.of(context)` or `MaterialLocalizations.of(context)`)
161+
to continue functioning properly.
162+
163+
However, the compatibility bridge cannot resolve type mismatches
164+
when a dependency exposes, accepts, or returns in-framework SDK types
165+
in its public API signatures (such as passing a `FloatingActionButtonLocation`,
166+
`ColorScheme`, or `TextTheme` as a parameter or callback return value).
167+
Because Dart enforces static typing across distinct package imports,
168+
values from `package:flutter/material.dart` cannot be assigned to parameters
169+
expecting types from `package:material_ui`.
170+
Dependencies with API-signature coupling must be migrated to the standalone
171+
package before your application can pass modern types to them.
172+
173+
### Decoupled localizations
174+
175+
As part of this transition, `flutter_localizations` is unbundled
176+
for design components.
177+
Localization delegates and translated strings for Material and Cupertino
178+
widgets now reside directly in `package:material_ui` and
179+
`package:cupertino_ui`.
180+
181+
Code before migration:
182+
183+
```dart
184+
import 'package:flutter/material.dart';
185+
import 'package:flutter_localizations/flutter_localizations.dart';
186+
187+
// ...
188+
MaterialApp(
189+
localizationsDelegates: const <LocalizationsDelegate<dynamic>>[
190+
GlobalCupertinoLocalizations.delegate,
191+
GlobalMaterialLocalizations.delegate,
192+
GlobalWidgetsLocalizations.delegate,
193+
],
194+
// ...
195+
);
196+
```
197+
198+
Code after migration:
199+
200+
```dart
201+
import 'package:material_ui/material_ui.dart';
202+
203+
// ...
204+
MaterialApp(
205+
localizationsDelegates: GlobalMaterialLocalizations.delegates,
206+
// ...
207+
);
208+
```
209+
210+
Setting `localizationsDelegates` to `GlobalMaterialLocalizations.delegates`
211+
automatically includes the Cupertino and Widgets delegates as well,
212+
simplifying localization setup.
213+
214+
### Guidance for package authors
215+
216+
If you maintain an open source package or plugin in the Flutter ecosystem,
217+
migrating to `package:material_ui` or `package:cupertino_ui` introduces
218+
a breaking change for consumers who haven't updated their dependencies.
219+
While the symbols and class names remain the same,
220+
they are technically referenced from an entirely new library.
221+
Treat this migration as a major version bump for your package.
222+
223+
## References
224+
225+
Package documentation:
226+
227+
* [`package:material_ui`][]
228+
* [`package:cupertino_ui`][]
229+
230+
Relevant issues:
231+
232+
* [Issue 191448][]
233+
234+
Relevant blog posts and announcements:
235+
236+
* [What's new in Flutter 3.47][]
237+
* [Flutter's Material and Cupertino code freeze][]
238+
239+
[`flutter/packages`]: {{site.repo.packages}}
240+
[Issue 191448]: {{site.repo.flutter}}/issues/191448
241+
[`package:cupertino_ui`]: {{site.pub-pkg}}/cupertino_ui
242+
[`package:material_ui`]: {{site.pub-pkg}}/material_ui
243+
[Flutter's Material and Cupertino code freeze]: {{site.main-url}}/blog/flutters-material-and-cupertino-code-freeze
244+
[What's new in Flutter 3.47]: {{site.main-url}}/blog/whats-new-in-flutter-3-47

0 commit comments

Comments
 (0)