Bowlerplate | Build what matters

Learn how to rename your application ID, package name, and display name for production readiness.

When starting a project from a boilerplate, one of the first things you'll want to do is rename the package name (Application ID) and the application's display name to match your brand. This is a critical step before publishing to the App Store or Google Play Store.

Renaming the package name is a breaking change for external services like Firebase, Google Sign-In, and Deep Links. Always follow the Post-Rename Checklist after changing these values.

The Simple Way (Automated CLI)

The boilerplate comes pre-configured with the change_app_package_name package, which automates the process of renaming the package name across Android and iOS.

Run the Rename Command

Navigate to the mobile/flutter directory and run the following command:

dart run change_app_package_name:main com.yourcompany.yourapp

This command will automatically update:

applicationId and namespace in Android.
Bundle Identifier in iOS.
Folder structures and imports where necessary.

Update Display Name

To change the name that appears on the user's home screen, update the native config files:

Android (android/app/src/main/AndroidManifest.xml):

<application android:label="Your App Name" ...>

iOS (ios/Runner/Info.plist):

<key>CFBundleName</key>
<string>Your App Name</string>
<key>CFBundleDisplayName</key>
<string>Your App Name</string>

Manual Steps (Optional)

If you need deeper customization or the automated tool doesn't cover a specific use case, you can perform these steps manually.

Android Customization

build.gradle.kts: Update namespace and applicationId in android/app/build.gradle.kts.
Path Structure: Move your Kotlin files in android/app/src/main/kotlin/ to match your new package structure (e.g., com/yourcompany/yourapp).
MainActivity: Update the package declaration at the top of MainActivity.kt.

iOS Customization

Xcode: Open ios/Runner.xcworkspace in Xcode.
Project Settings: Select the Runner target -> General tab -> Bundle Identifier.
Info.plist: Ensure CFBundleIdentifier uses $(PRODUCT_BUNDLE_IDENTIFIER).

Renaming the Flutter Package (Optional)

In Dart, there is a "package name" defined in your pubspec.yaml. By default, this boilerplate uses mobile.

While not strictly required, you might want to rename it to match your project name.

Changing the name in pubspec.yaml will break all absolute imports (e.g., import 'package:mobile/...') throughout your entire project.

How to rename the package:

Update pubspec.yaml: Change name: mobile to your new name.
Global Search & Replace: Search your IDE for package:mobile/ and replace it with package:your_new_name/.

Updating Deep Link Schemes

The boilerplate comes with deep linking for password resets. If you change your brand name, you'll likely want to change the URL scheme too.

Update Flutter Code

Search for clinic-scheduler in lib/main.dart and replace it with your app's scheme:

// lib/main.dart
if (deepLink.uri.scheme == 'your-new-scheme' && ...)

Update Android Config

Open android/app/src/main/AndroidManifest.xml and update the <data> tag:

<data android:scheme="your-new-scheme" android:host="reset-password" />

Update iOS Config

Open ios/Runner/Info.plist and update the CFBundleURLSchemes:

<key>CFBundleURLSchemes</key>
<array>
    <string>your-new-scheme</string>
</array>

Post-Rename Checklist (IMPORTANT)

Ensure you complete these steps to avoid issues with external services:

1. Update Firebase Configuration

Your existing google-services.json and GoogleService-Info.plist are tied to the old package name.

Go to the Firebase Console.
Add a new Android App and iOS App with your new package name.
Download the new config files and replace the old ones in:
- android/app/google-services.json
- ios/Runner/GoogleService-Info.plist

Update the package name/bundle ID in:

Google Cloud Console (for Google Sign-In)
Meta for Developers (for Facebook Login)
Apple Developer Portal (for Sign In with Apple)

3. Clean and Rebuild

Clear the build cache to ensure all changes are applied:

flutter clean
flutter pub get
flutter run

Rename Package & App Name