flutter_app_config

Configure app name, ID, icon, and splash screen from pubspec.yaml only, then run one command to update Android and iOS.

What this package does (short)

  • Reads a small config block in pubspec.yaml
  • Updates Android + iOS files automatically
  • Provides a simple SplashScreen widget for your Flutter app

You don’t touch AndroidManifest.xml, Info.plist, or Xcode/Gradle files manually.

Quick start in 3 steps

1. Add dependency

dependencies:
  flutter:
    sdk: flutter
  flutter_app_config: ^1.0.0

2. Add configuration block (root level)

Add this at the same level as dependencies: in your app’s pubspec.yaml:

flutter_app_config:
  app_name: "My App"                        # Text under the app icon
  package_id: "com.example.myapp"           # Android package / iOS bundle id
  version_name: "1.0.0"                     # Optional – defaults to pubspec version
  version_code: 1                           # Optional – Android build number
  custom_icon_path: "assets/icons/app_icon.png"   # Your app icon
  splash_image_path: "assets/images/splash.png"   # Splash image shown before home

Important: flutter_app_config: must not be inside dependencies: – keep it at the root level of the file.

3. Apply config

Run this from your app project root:

dart run flutter_app_config:configure
# or:
flutter pub run flutter_app_config:configure

Run this again every time you change flutter_app_config in pubspec.yaml.

Optional: Use the splash screen widget

import 'package:flutter/material.dart';
import 'package:flutter_app_config/flutter_app_config.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My App',
      home: SplashScreen(
        config: const SplashConfig(
          imagePath: '', // Empty = Flutter logo, or pass your own asset path
          duration: Duration(seconds: 2),
          backgroundColor: 0xFF2196F3,
        ),
        home: const HomePage(),
      ),
    );
  }
}

class HomePage extends StatelessWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Home')),
      body: const Center(child: Text('Welcome!')),
    );
  }
}

Configuration Options

All configuration is done in pubspec.yaml under flutter_app_config:

name: my_app
version: 1.0.0+1

dependencies:
  flutter:
    sdk: flutter
  flutter_app_config: ^1.0.0

# ⚠️ Configuration section at ROOT LEVEL (same level as 'dependencies')
flutter_app_config:
  # Required
  app_name: "Your App Name"           # Display name shown under app icon
  package_id: "com.example.app"      # Package ID (Android) / Bundle ID (iOS)
  
  # Version (optional - uses pubspec.yaml version if not set)
  version_name: "1.0.0"              # Version string (e.g., 1.0.0)
  version_code: 1                    # Build number (integer)
  
  # Splash Screen
  splash_image_path: "assets/images/splash.png"  # Path like "assets/images/splash.png"
  
  # App Icon
  custom_icon_path: "assets/icons/app_icon.png"  # Path to your custom icon

⚠️ Important: The flutter_app_config: section must be at the root level of your pubspec.yaml file (same indentation as dependencies:), NOT inside the dependencies: section. Putting it inside dependencies: will cause a "Duplicate mapping key" YAML error.

Configuration Examples

Minimal:

flutter_app_config:
  app_name: "My App"
  package_id: "com.example.myapp"
  custom_icon_path: "assets/icons/app_icon.png"  # Your custom icon

Full configuration:

flutter_app_config:
  app_name: "My Awesome App"
  package_id: "com.company.myapp"
  version_name: "2.5.0"
  version_code: 25
  splash_image_path: "assets/images/custom_splash.png"   # Custom splash image
  custom_icon_path: "assets/icons/app_icon.png"          # Custom icon

Custom splash image only:

flutter_app_config:
  app_name: "My App"
  package_id: "com.example.myapp"
  splash_image_path: "assets/images/my_splash.png"  # Custom splash image
  custom_icon_path: "assets/icons/my_icon.png"      # Custom icon (512x512 recommended)

Setting Up App Icons

Using custom icon

Provide the path in custom_icon_path:

flutter_app_config:
  app_name: "My App"
  package_id: "com.example.myapp"
  custom_icon_path: "assets/icons/app_icon.png"  # Your custom icon (512x512 recommended)

Note: Custom icon setup requires manual configuration. The configuration tool will update app metadata, but you'll need to generate and place icon files manually using tools like appicon.co or similar icon generators.

Automatic setup (optional, requires scripts)

If icon setup scripts are available, the configuration tool will attempt to set up icons when you run:

dart run flutter_app_config:configure

If scripts are present, the tool will:

  • Generate all required icon sizes for Android and iOS
  • Use macOS built-in tools (no ImageMagick needed on macOS)
  • Fall back to ImageMagick script on other platforms if needed

If scripts are not found, you'll need to set up icons manually (see below).

Manual Setup (Optional)

If you need to regenerate icons manually:

  1. Download Flutter logo from: https://flutter.dev/brand
  2. Use online tool: https://appicon.co/ to generate all sizes
  3. Replace icon files manually in:
    • Android: android/app/src/main/res/mipmap-*/ic_launcher.png
    • iOS: ios/Runner/Assets.xcassets/AppIcon.appiconset/

What Gets Configured?

Android:

  • ✅ android/app/src/main/AndroidManifest.xml - App name
  • ✅ android/app/src/main/res/values/strings.xml - App name resource
  • ✅ android/app/build.gradle.kts - Package ID, version name, version code
  • ✅ android/app/src/main/res/values/styles.xml - Removes native splash (transparent background)
  • ✅ App icons (all densities: mdpi, hdpi, xhdpi, xxhdpi, xxxhdpi) - Flutter logo

iOS:

  • ✅ ios/Runner/Info.plist - App display name
  • ✅ ios/Runner.xcodeproj/project.pbxproj - Bundle identifier
  • ✅ ios/Runner/Base.lproj/LaunchScreen.storyboard - Removes native splash (transparent)
  • ✅ App icons (all required sizes) - Flutter logo

Flutter:

  • ✅ Splash screen widget ready to use
  • ✅ Flutter logo displayed by default
  • ✅ Customizable duration and colors

Requirements

  • Flutter SDK >=3.0.0
  • Dart SDK >=3.0.0
  • For icon generation (optional): ImageMagick or use online tools like appicon.co

Complete Workflow Summary

  1. Add package → flutter pub add flutter_app_config
  2. Add config → Add flutter_app_config: section to pubspec.yaml
  3. Apply changes → Run dart run flutter_app_config:configure ⚠️ This is required!
  4. Add splash widget → Use SplashScreen in your main.dart
  5. Run app → flutter run

Important: Step 3 (dart run flutter_app_config:configure) is required every time you change the configuration in pubspec.yaml. This command reads your config and updates all Android/iOS files automatically.

Troubleshooting

"Duplicate mapping key" error:

# ❌ WRONG - Don't put flutter_app_config inside dependencies:
dependencies:
  flutter_app_config: ^1.0.0
  flutter_app_config:  # ❌ This causes duplicate key error!
    app_name: "My App"

# ✅ CORRECT - Put it at root level:
dependencies:
  flutter_app_config: ^1.0.0

flutter_app_config:  # ✅ At root level, same as 'dependencies'
  app_name: "My App"

Configuration tool not found:

# Make sure you're in your project root and have run: flutter pub get
dart run flutter_app_config:configure

# If that doesn't work, try:
flutter pub run flutter_app_config:configure

Changes not applied after updating pubspec.yaml:

# You must run the configuration tool after changing pubspec.yaml
dart run flutter_app_config:configure

Icons not showing:

# Clean and rebuild
flutter clean
flutter pub get
flutter run

Need to regenerate icons: Icon setup requires manual configuration. To set up icons:

  1. Download Flutter logo from https://flutter.dev/brand
  2. Use online tool https://appicon.co/ to generate all sizes
  3. Replace icon files manually

Icon setup not working:

  • Icon setup requires manual configuration using online tools or scripts
  • For custom icons: Use online tool https://appicon.co/ to generate all required sizes
  • For Flutter logo: Download from https://flutter.dev/brand and use https://appicon.co/ to generate sizes
  • Place generated icons in:
    • Android: android/app/src/main/res/mipmap-*/ic_launcher.png
    • iOS: ios/Runner/Assets.xcassets/AppIcon.appiconset/

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Libraries

flutter_app_config
main