simple_splash_view 0.1.2

Native splash generator (Android/iOS) with Kotlin/Swift using config from pubspec.yaml.

simple_splash_view

Native-first splash generator for Flutter apps (Android + iOS). Configure the splash experience once inside pubspec.yaml and this package writes every required Kotlin, Swift, XML, and asset integration for you.

---

Highlights

• Single source of truth � keep all splash settings in pubspec.yaml.
• Native fidelity � generates SplashActivity.kt, SplashViewController.swift, layouts, manifests, Podfile updates, and Gradle tweaks.
• Rich media � supports Lottie animations, static images, startup sounds, custom text, and loading indicators.
• Light & dark themes � provide dedicated assets/colors or let the generator fall back automatically.
• Idempotent patches � re-running the tool updates the same spots without creating duplicates.
• Autogenerated docs � every run refreshes simple_splash_view_usage.md with your exact configuration.

---

Requirements

• Flutter / Dart SDK >= 3.3.0 < 4.0.0.
• Android toolchain with Gradle/Android Gradle Plugin 7+ and a JDK (17 recommended).
• Xcode 14+ with CocoaPods (the tool can run pod install, or skip it via CLI).

---

Installation

1. Add the generator to your development dependencies:

   dev_dependencies:
     simple_splash_view: ^0.1.1
   

2. Declare the splash assets inside flutter.assets so Flutter bundles them:

   flutter:
     assets:
       - assets/splash/splash_light.json
       - assets/splash/splash_dark.json
       - assets/images/logo_light.png
       - assets/images/logo_dark.png
       - assets/audio/intro.mp3
   

3. Add the simple_splash_view section (see the configuration reference below).

4. Run the generator any time you change the splash config or assets:

   flutter pub run simple_splash_view
   

---

Quick Configuration Example

simple_splash_view:
  lottie: assets/splash/splash_light.json
  lottie_dark: assets/splash/splash_dark.json
  image: assets/images/logo_light.png
  image_dark: assets/images/logo_dark.png
  sound: assets/audio/intro.mp3
  text: "Built by You"
  background_color: "#F4F5F7"
  background_color_dark: "#050505"
  text_color: "#1E1E1E"
  text_color_dark: "#FAFAFA"
  indicator: true
  indicator_color: "#FF5722"
  indicator_color_dark: "#FFC107"
  indicator_position: below_visual
  text_position: bottom
  duration: 3200
  theme:
    mode: system
    app_theme: "Theme.App"
    splash_theme: "Theme.Splash"

---

Configuration Reference

Key	Type	Description	Default / Fallback
lottie	asset path	Lottie animation for light mode.	null
lottie_dark	asset path	Lottie animation for dark mode.	Falls back to lottie.
image	asset path	Static image/logo for light mode.	null.
image_dark	asset path	Static image/logo for dark mode.	Falls back to image.
sound	.mp3 / .wav	Optional startup sound.	null.
text	string	Caption shown under the visual.	null.
duration	milliseconds	Total splash duration before handing off to Flutter.	2500.
background_color	hex string	Light background color.	#FFFFFF.
background_color_dark	hex string	Dark background color.	Falls back to background_color or #000000.
text_color	hex string	Light text color.	#FFFFFF.
text_color_dark	hex string	Dark text color.	Falls back to text_color.
indicator	bool	Shows a circular loading indicator.	false.
indicator_color	hex string	Indicator tint for light mode.	Falls back to text_color.
indicator_color_dark	hex string	Indicator tint for dark mode.	Falls back to indicator_color.
indicator_position	enum	Placement of the spinner relative to the visual/text (table below).	auto.
text_position	enum	Placement of the text label (table below).	auto.
theme	map	Advanced overrides for Android themes (see next table).	Uses generated defaults.

Indicator & Text Positions

Value	Indicator placement	Text placement
auto	Chooses the best spot automatically.	Chooses the best spot automatically.
below_visual	Spinner/text render under the image/Lottie.	Text rendered right under the visual.
above_text	Spinner renders between the visual and text.	�
bottom	�	Text is pinned to the bottom of the screen.

Theme Block

Field	Description
mode	system (default), light, or dark. Forces specific brightness if set to light/dark.
app_theme	Optional Android theme to keep using for your MainActivity.
splash_theme	Override the generated EasySplashTheme if you already manage a custom style.
light_background_color	Forces the light background regardless of background_color.
dark_background_color	Forces the dark background regardless of background_color_dark.

Dark variants (images, Lottie, colors) automatically fall back to their light counterparts when omitted.

---

CLI Reference

flutter pub run simple_splash_view [options]

• --no-android � Skip Android-native updates (useful on macOS-less CI).
• --no-ios � Skip iOS-native updates.
• --skip-pod-install � Do not run pod install (handy when CocoaPods is unavailable).
• --quiet � Reduce console noise.
• --help / -h � Print usage information.

---

What Gets Generated

Android

• Copies all splash assets into android/app/src/main/res (including drawable-night/raw-night variants).
• Ensures required dependencies (androidx.appcompat, material, and lottie when needed) are present in build.gradle / build.gradle.kts.
• Creates/updates activity_splash.xml with the correct widgets, indicator, and text placement.
• Writes SplashActivity.kt that plays the animation, audio, and transitions into MainActivity.
• Patches AndroidManifest.xml to make SplashActivity the launcher and to wire up the generated theme.
• Generates/updates light & dark color resources.
• Runs the environment patcher to align proguardFiles, add keep rules, and report AGP/Gradle/JDK versions.

iOS

• Copies assets into ios/Runner/Resources and names them consistently for both light/dark variants.
• Generates SplashViewController.swift with the configured visuals, timing, indicator, and optional audio playback.
• Patches AppDelegate.swift to present the splash coordinator before Flutter boots and injects AVFoundation imports when sound is used.
• Ensures Podfile declares pod 'lottie-ios' whenever Lottie files are referenced, then optionally runs pod install.

Documentation Output

• After every run, the tool exports simple_splash_view_usage.md with your current configuration, timing, and theme values so team members can audit the exact setup.

---

Suggested Workflow

• Commit your Flutter project before running the generator so you can review diffs afterwards.
• Update the simple_splash_view section whenever you change assets/colors/text, then rerun flutter pub run simple_splash_view.
• Check the regenerated simple_splash_view_usage.md into version control for easy onboarding.
• For CI, invoke the generator with --no-ios or --no-android on platform-specific runners.
• Customize the generated android/app/src/main/res/layout/activity_splash.xml or ios/Runner/SplashViewController.swift only if you plan to maintain the changes manually (rerunning the generator will overwrite those files).

---

Troubleshooting

Issue	Fix
Splash assets do not appear	Ensure the asset paths exist, are listed under flutter.assets, and rerun the generator.
iOS build fails with missing pods	Install CocoaPods (sudo gem install cocoapods), run cd ios && pod install, or invoke the generator without --skip-pod-install.
Android launcher opens MainActivity directly	Remove manual launcher entries so the generator can manage AndroidManifest.xml, then rerun.
Sound is silent on iOS	Confirm the device is not in silent mode and that the audio format is .mp3 or .wav.
ProGuard/R8 strips generated code	The Environment Patcher already writes keep rules; rerun the generator to refresh them if you edited proguard-rules.pro.

---

Example & Testing

An example Flutter app is included in the repository (example/). Run it to see the generated splash in action:

cd example
flutter run

---

Contributing

Issues and pull requests are welcome. Please run dart format, add tests when applicable, and describe any platform-specific considerations in your PR.

---

License

Distributed under the MIT License. See LICENSE for details.