Document custom asset bundle paths and flavor-specific configuration #13868

Related code pull request or issue

flutter/flutter#192509

Tracking issue: flutter/flutter#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

• Update to an existing guide on docs.flutter.dev
• 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

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.