Repository navigation
Open
Labels
P2Important issues not at the top of the work listImportant issues not at the top of the work listteam-toolOwned by Flutter Tool teamOwned by Flutter Tool teamtoolAffects the "flutter" command-line tool. See also t: labels.Affects the "flutter" command-line tool. See also t: labels.tool-still-validIssues that have been deemed still valid as part of the Flutter Tools issue cleanup initiative.Issues that have been deemed still valid as part of the Flutter Tools issue cleanup initiative.triaged-toolTriaged by Flutter Tool teamTriaged by Flutter Tool team
Description
Update 2026-05-12: This is available under flutter config --enable-dart-data-assets. Please report any issues that you find.
Update 2026-09-29: With @RecordUse() info available in link hooks since Dart 3.13, this experiment can be used to do tree-shaking of assets (#64106).
The hook/build.dart of packages should be able to not only add native code assets, but also data assets.
In Flutter, these data assets should be made available through the existing asset bundle API.
This issue tracks the flutter implementation for this in flutter tools.
- Add
data_assettoBuildConfig.supportedAssetTypes. - Bundle the [
DataAsset]s fromBuildOutput.assetsin Flutter applications (on all 5 OSes, in all modes).- Open question: should asset contents be refreshed on hot reload / hot restart?
Tracking issue for Dart and Flutter combined:
Umbrella issue for native assets:
Reacted by Nick Fisher, phamconganh, Brandon DeRosier, A.S, Kyle Turney, t3h32eKK, Thibault Deckers, Matthias Ngeo and Xavier H.
Metadata
Metadata
Assignees
Labels
P2Important issues not at the top of the work listImportant issues not at the top of the work listteam-toolOwned by Flutter Tool teamOwned by Flutter Tool teamtoolAffects the "flutter" command-line tool. See also t: labels.Affects the "flutter" command-line tool. See also t: labels.tool-still-validIssues that have been deemed still valid as part of the Flutter Tools issue cleanup initiative.Issues that have been deemed still valid as part of the Flutter Tools issue cleanup initiative.triaged-toolTriaged by Flutter Tool teamTriaged by Flutter Tool team
Activity
dcharkes commentedon Sep 25, 2026
What benefits would we get from deprecating
pubspec.yamlassets:and asset transformers in favorDataAssets fromhook/build.dartandhook/link.dart?Migration path for users
->
(If we believe a lot of people will write this code over and over again, we could simplify this to:
If tree-shaking is wanted, add
@RecordUse()annotations to the code using assets. Check out this example app for various patterns with tree-shaking and resizing images, tree-shaking audio files, and tree-shaking and pruning translation files. The code might need massaging to center around const objects and static invocations with const arguments for tree-shaking to work. (This is standard practice already in the places where we have custom asset tree-shaking: icon fonts, and translation pipelines in g3.)Flavors and platforms-specific assets fold naturally into tree-shaking. These already require runtime branching in the code. The branch points should be annotated with
@RecordUse(), either const arguments or const instances. This refactoring will most likely be trivial due to flavors being a const-from-environment and platform-branching being done onPlatform.is...or a similar vm-platform-const value.What is needed to ship this?
flutter testflutter drive --releaseandflutter build apk integration_test/... --release.assets:special treatment toDataAssets special treatment in Flutter2.0xand similar directories for DPR (device pixel ratio), do the same for data assets.flavorandplatformto theLinkInputand run the link hooks without@RecordUse()but with this info for development mode. This would enable Flutter-specific link hooks to prevent copying assets for other flavors to the device. (But maybe in development mode you want the assets for all flavors?!) [asset_transformers] Provide the current target platform in the asset transformer #159323 Web: include different files depending on the flavor #141371 (Marked optional because you could do structure your code to include assets of all flavors and tree-shake them out based on recorded uses.)package:record_use(release builds only)Out of scope
pubspec.yaml->flutter->fonts. Now that tree-shaking info is available to packages, fonts might not need to be a built-in asset type to Flutter. They might be able to be built on top of data assets, including the tree shaking of icon fonts.pubspec.yaml->flutter->shaders. Same argument.pubspec.yaml->flutter->deferred-components->assets. Not many users use this. The clean way to do this would be to not require users to manually assign assets to deferred modules, but to infer this information from where the assets are used in the Dart code. Dart code is split up inloading_units which are assigned to deferred modules. The@RecordUse()recordings know in which loading unit the Dart code ended up. So, we should be able to automatically assign assets to the right deferred module. But since this is a niche use case we would defer supporting deferred loading.dcharkes commentedon Sep 25, 2026
@mit-mit @kevmoo @mariamhas WDYT? Is providing tree-shakable assets worth an ecosystem migration away from
pubspec.yaml->flutter->assets?cc @goderbauer
kevmoo commentedon Sep 25, 2026
I'm a BIG fan of less magic in Flutter and more general, extensible solution in Dart.
The technical bits looks reasonable on a first pass.
[flutter_tools] Include data assets from hooks when pubspec.yaml is e…
kevmoo commentedon Sep 29, 2026
Adding one follow-up thought on the migration / deprecation question (
Option 1: deprecate flutter: assets: in pubspec.yamlvsOption 2: additive hooks):pubspec.yamltransformers:: Strongly in favor.hook/build.dartandhook/link.dartstrictly supersede YAML asset transformers.DataAsset+@RecordUse()inhook/build.dart/hook/link.dartshould be the recommended path—that's where cross-package composition and tree-shaking (Tree shake unused assets #64106) have the highest leverage.hooks+data_assetsdependencies and write ahook/build.dartscript just to include a staticlogo.png. Ifflutter_toolscan desugarpubspec.yamlflutter: assets:into theDataAssetpipeline under the hood, we get a single engine (less magic in Flutter) while keeping the 2-line YAML ergonomics for simple static app bundles until/unless they need programmatic bundling or tree-shaking.dcharkes commentedon Sep 29, 2026
@CarlosMendonca @kevmoo If we keep
flutter:assets:, but deprecateflutter:assets:transformers:we should update the documentation as follows after the the first stable release that has the data assets experiment turned on by default:package:record_use(release builds only)zanderso commentedon Sep 29, 2026
Currently, assets (including asset transformers, I think?) are covered by hot reload/restart. Losing the ability to hot reload assets would be a regression.
mariamhas commentedon Sep 29, 2026
Im also curious how this might impact tooling like dart migrate which from my highlevel understanding depends on a pubspec?
dcharkes commentedon Sep 30, 2026
Yes, hot restart and hot reload are covered.
Migrating Fonts
I also took a look at the longer term plan for migrating fonts.
Option 1: Data assets only, fonts as package
The lean core, completely remove fonts bundling from the Flutter Engine and Font pre-loading from the Flutter engine/framework. For this we need two components:
SynchronousDataAssets. assets which can be accessed synchronously at runtime. Currently assets can only be assets via a Future, due to the system calls doing the actual loading. However, Fonts in the native platforms aremmaped in synchronously on their first use. And on web they are preloaded before the users' main. TheDataAssets from build hooks with the Flutter assets API (https://docs.flutter.dev/ui/assets/assets-and-images) is asynchronous. We need a synchronous variant for which the bundling format + embedder promise synchronous access.const TextStyle(fontFamily: 'Raleway')has no way to know that it'sraleway.ttf. A better way to structure this API would be to haveconst TextStyle(fontFamily2: raleway)whereconst raleway = FontFamily(asset: 'my_package/assets/raleway.ttf', bold: ...). This would be proper encapsulation. And also makes tree-shaking via@RecordUse()trivial because you can simply look at all the const instances. (The current icon-font tree-shaker cannot omit fonts and icon fonts when they are completely unused.)Option B: Leverage link hooks to collect the font-mappings in a JSON file in
package:fontsunder a known data-asset, and load that asset before the users' main to register all fonts.Option 2:
FontAssetsKeep all the special casing in the engine and framework for bundling fonts, but allow reporting them from build and link hooks. This keeps leveraging the
mmaplazy sync loading on the native backends, and the eager registration via reading theFontManifest.jsonin the engine before the user program runs.POC: #174860
(I'd recommend against this, this does not provide a leaner Flutter.)
Migrating Shaders
This is much easier than fonts. These are already accessed via an asset key, and asynchronous. And @bdero already has a PR in flight to make the
impellercexecutable available in build hooks (#189821).@bdero Are there any other things missing for fully supporting
shaders:from thepubspec.yamlfrom build hooks via data assets?dcharkes commentedon Sep 30, 2026
I cannot find any use of the pubspec assets in
flutter migrate.Side note: @zanderso mentioned that if we do want to remove support for an old way of doing things, we should write a migrator to the new world.
[flutter_tools] Bundle data assets from hooks in flutter test (flutte…
[flutter_tools] Include dev_dependencies hooks for release integratio…
mosuem commentedon Oct 12, 2026
Note
This comment was generated by an AI coding agent (Jetski) on behalf of @mosuem.
@dcharkes Follow-up on Migrating Fonts: I opened an updated, minimal version of #174860 in #194001 (paired with
package:font_asset0.1.0,mosuem/font_asset#1):flutter_tools: Hook fonts are bundled asAssetKind.fontand registered inFontManifest.json, so Flutter's existingIconTreeShakersubsets them in release builds (no duplicate tree-shaker orfont-subsetbinary inpackage:font_asset, and noMaterialIconsspecial-casing).enable-dart-data-assetsis enabled.addFont/addFontFamilyinhook/build.dart, allowing us to later move tree-shaking intopackage:font_asset's link hook and migrate toward Option 1 (DataAssets) without changing package build hooks.WDYT about landing #194001 behind
enable-dart-data-assetsas an incremental step?dcharkes commentedon Oct 12, 2026
I'd recommend against this, this does not provide a leaner Flutter.
zanderso commentedon Oct 12, 2026
Build hooks might be the best way to do the implementation under the covers, but I would like us to consider the overall Flutter developer experience and whether there are alternatives to a breaking change and mandatory migration. Developers, our developer tooling, and agents are all already familiar with listing assets in the pubspec file, and build hooks would be a new thing for all those pieces to learn. Even with migration tooling, agents would take time to catch up. Can we make this a seamless experience, including tree shaking, without the need for a breaking change?
A strawman for how that could work would be for an off-the-shelf build hook library that we vend to read the data that's already in the pubspec file, and then take the appropriate actions. Then the migration tool would simply create that hook in a project if it doesn't already exist. If a project already has a build hook, we give the user some code to copy-paste. Lots of missing details here, but the overall idea is to make this a low-friction developer experience.
Finally, I would really like to see an RFC on this topic that covers the overall vision/plan for Flutter assets. I think the complexity here is such that we shouldn't be trying to design solutions over chat or in back-and-forth on GitHub issues. Thanks!
[flutter_tools] Reload widget-preview when data assets change (flutte…
[flutter_tools] Bundle data assets from hooks in flutter test (flutte…
[flutter_tools] Include dev_dependencies hooks for release integratio…
[flutter_tools] Reload widget-preview when data assets change (flutte…
dcharkes commentedon Nov 9, 2026
@navaronbracke my general thinking is that tree-shaking is already possible. Do you have an actual use case where you want to branch on target platform that cannot be expressed in terms of tree-shaking? E.g. if you have
images/my_picture.pngbe something different for IOS or Android. you can also instead write your Dart code withPlatform.isAndroidandimages/android/my_picture.png. Could you give the data assets experiment with the shipped recorded_uses.json feature a spin to see if it covers your use case?