Docs: iOS flavor setup — say that `--path` combines with `--flavor`, and that all flavor storyboards must exist at build time

[ENKOJanJungblut]

The Flavor Support → iOS setup section of the README is clear about the one-time Xcode work: drag the generated LaunchScreen<Flavor>.storyboard files in, add a user-defined LAUNCH_SCREEN_STORYBOARD setting per scheme, and point the Info.plist launch screen entry at $(LAUNCH_SCREEN_STORYBOARD). Following it worked.

Two things are not written down, and both cost me time on a project with a larger number of flavors. Neither is a bug — it is information that currently only exists in the source or in an older issue.

1. --path and --flavor can be used together

The flags table documents --path and --flavor separately, and the flavor section says the config must "match the pattern flutter_native_splash-*.yaml". Read together, that suggests flavor mode requires the config files to sit in the project root under that exact name.

It does not. getConfig(configFile:, flavor:) in lib/cli_commands.dart takes the file from --path and still applies the flavor to every output path, so this works:

dart run flutter_native_splash:create \
  --path=./config/flutter_native_splash-staging.yaml \
  --flavor staging

Verified on 2.4.7: the config was read from the subdirectory, the Android output landed in android/app/src/staging/res/, and the iOS artefacts were named …Staging. That is exactly what a project needs when it keeps its per-flavor config files out of the project root, and one sentence in the flags table would make it discoverable.

For --flavors and --all-flavors the root-name requirement does appear to be real, since those scan the working directory for the pattern. Worth stating explicitly, because the asymmetry with --flavor is surprising.

2. Once the storyboards are referenced in Xcode, all of them have to exist

This is the one I would most like to see in the README. The natural CI setup is one job per flavor, generating only that flavor (--flavor X) on a fresh agent. But after the Xcode step, project.pbxproj references all N storyboards, and — as far as I can tell — Copy Bundle Resources is not per-configuration, so a build of flavor X still expects flavor Y's storyboard file to be on disk. On a fresh agent the other N−1 files were never generated.

#701 ("Flavors still bundling all storyboard files on release") is the same fact seen from the other side: all storyboards end up in the bundle. Reading that issue afterwards is what made it click, which is a sign it belongs in the setup instructions rather than in an issue from 2024.

If that is right, then --all-flavors (2.4.4+) is not merely a convenience for generating many at once — it is what the referenced-in-Xcode setup requires, unless the generated storyboards are committed. The README currently presents it only as the convenient option.

I have not tested the failure mode on a Mac, so please treat the mechanism as a question rather than a report — but either way the answer belongs next to the setup steps.

Suggested addition

Under ### iOS setup, after the Xcode steps:

Keep every flavor's storyboard available. Once the storyboards are referenced in the Xcode project, a build of any flavor expects all of them to be present, and all of them are copied into the bundle (see #701). If you generate per flavor in CI, either commit the generated storyboards or run --all-flavors so the references resolve. Generating a single flavor on a clean checkout is not enough.

And in the flags table, next to -f, --flavor:

Can be combined with --path when the config file does not live in the project root. --flavors and --all-flavors scan the working directory and need the flutter_native_splash-<flavor>.yaml name there.