flutter / flutter/website

Document custom asset bundle paths and flavor-specific configuration

Open
#13,868 0 comments 0 reactions 0 assignees View on GitHub
act.await-dev-pr p2-medium
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.