Document custom asset bundle paths and flavor-specific configuration
- Dominant language
- Dart
- Stars
- 3.1k
- Forks
- 3.5k
- Avg merge
- 2d 4h
- Merged PRs (30d)
- 95
Description
### Related code pull request or issue
https://github.com/flutter/flutter/pull/192509
Tracking issue: https://github.com/flutter/flutter/issues/151342
### Feature summary
The proposed `bundle_path` field lets an asset use a different source path and runtime asset key. It reuses Flutter's existing flavor selection, so different configuration files can be bundled under one fixed key without copying over source files before each build.
This is a documentation follow-up for an unmerged proposal. The API and release availability should be confirmed before publishing documentation.
### Type of documentation needed
- [x] Update to an existing guide on docs.flutter.dev
- [x] CLI or tooling documentation
Update the asset and flavor guides with the source/output distinction, a configuration-file example, and the behavior of directory mappings and image variants.
### Code snippet or usage example
```yaml
flutter:
assets:
- path: configs/dev/branch-config.json
flavors: [dev]
bundle_path: assets/branch-config.json
- path: configs/prod/branch-config.json
flavors: [prod]
bundle_path: assets/branch-config.json
```
Dart uses `rootBundle.loadString('assets/branch-config.json')`. Native plugins use that same key with Flutter's Android or iOS asset lookup APIs.
### Additional context or resources
The implementation includes tool documentation covering the proposed semantics. The source document is `docs/tool/Asset-bundle-paths.md` in the linked PR.
Please cover:
- Existing behavior when `bundle_path` is omitted.
- Conflicts after flavor and platform filtering; no fallback precedence between declarations.
- Directory prefixes, resolution variants, and package namespaces.
- Source files remaining build dependencies.
- Mappings staying inside the Flutter asset bundle, rather than the platform application's top-level resources.
- Third-party asset generators needing support for the new field.
No breaking-change migration guide is expected because the field is optional.
Contributor guide
Research direction
Start by reading docs/tool/Asset-bundle-paths.md in linked PR #192509, then confirm the proposed API and release availability before editing the asset and flavor guides. Done means documenting source/output paths, flavor and platform filtering, directory and variant behavior, package namespaces, dependencies, bundle boundaries, and generator support.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- dart
- Domain
- documentation, tooling
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100