Using Environment Variables to Configure Flavor-Specific Settings and API Keys in Flutter

In Flutter development, managing different configurations for various environments or product flavors is a common requirement. Using environment variables to configure flavor-specific settings and API keys can greatly enhance your app’s flexibility, security, and maintainability. This article delves into how to effectively use environment variables in Flutter to manage different settings for various builds.

What are Environment Variables?

Environment variables are a set of dynamic named values that can affect the way running processes behave on a computer. They are external to the application’s code and configuration files, providing a convenient way to configure the application’s behavior without modifying its source code. This is especially useful for managing settings that vary across different environments (e.g., development, staging, production) or flavors (e.g., free, premium).

Why Use Environment Variables?

• Security: Keep sensitive information like API keys out of your codebase.
• Flexibility: Easily switch between different environments without changing the code.
• Maintainability: Simplify configuration management by centralizing settings in environment variables.
• Build Configurations: Facilitate different builds with varying features and configurations.

How to Implement Environment Variables in Flutter

There are several ways to implement environment variables in Flutter. We will explore using the flutter_dotenv package, as it’s a popular and straightforward approach.

Step 1: Add the flutter_dotenv Package

First, add the flutter_dotenv package to your pubspec.yaml file:

dependencies:
  flutter_dotenv: ^5.2.0  # Use the latest version

Then, run flutter pub get to install the package.

Step 2: Create .env Files for Different Flavors

Create .env files for each flavor you intend to support. For instance, you might have:

• .env.development
• .env.staging
• .env.production

In each .env file, define your environment-specific variables:

.env.development:

API_URL=https://dev.example.com/api
API_KEY=dev_api_key
APP_NAME=My App (Development)

.env.staging:

API_URL=https://staging.example.com/api
API_KEY=staging_api_key
APP_NAME=My App (Staging)

.env.production:

API_URL=https://example.com/api
API_KEY=production_api_key
APP_NAME=My App

Step 3: Load Environment Variables in Your Flutter App

In your main.dart file, load the environment variables before running the app:

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

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await dotenv.load(fileName: ".env.development"); // Or .env.production or .env.staging
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: dotenv.get('APP_NAME'),
      home: MyHomePage(),
    );
  }
}

class MyHomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(dotenv.get('APP_NAME')),
      ),
      body: Center(
        child: Text('API URL: ${dotenv.get('API_URL')}'),
      ),
    );
  }
}

In this example, we load the .env.development file by default. To use different .env files for different flavors, you’ll need to adjust the file loading based on your build configuration.

Step 4: Configure Flavors in Flutter

Flutter supports multiple flavors (or build configurations) using command-line arguments. First, you need to set up the flavors in your build configurations.

For Android, edit your android/app/build.gradle file:

android {
    ...
    flavorDimensions += "environment"
    productFlavors {
        development {
            dimension = "environment"
            applicationIdSuffix = ".dev"
            versionNameSuffix = "-dev"
        }
        staging {
            dimension = "environment"
            applicationIdSuffix = ".staging"
            versionNameSuffix = "-staging"
        }
        production {
            dimension = "environment"
        }
    }
    ...
}

For iOS, you can use Xcode build configurations to manage flavors.

Step 5: Load the Correct .env File Based on Flavor

To load the appropriate .env file based on the selected flavor, you can use conditional compilation and build arguments.

Modify your main.dart to accept a flavor argument and load the corresponding .env file:

import 'dart:io' show Platform;
import 'package:flutter/material.dart';
import 'package:flutter_dotenv/flutter_dotenv.dart';

Future main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Determine the environment file name
  String envFileName = ".env.development"; // Default to development
  
  // Access the flavor argument at compile time for web, mobile, and desktop builds.
  // Note: kReleaseMode isn't effective here as env loading needs to occur during startup.
  const environment = String.fromEnvironment('FLAVOR', defaultValue: 'development');
  
  if (environment == 'production') {
    envFileName = ".env.production";
  } else if (environment == 'staging') {
    envFileName = ".env.staging";
  }
  
  // Load environment variables
  await dotenv.load(fileName: envFileName);

  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: dotenv.get('APP_NAME'),
      home: MyHomePage(),
    );
  }
}

class MyHomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(dotenv.get('APP_NAME')),
      ),
      body: Center(
        child: Text('API URL: ${dotenv.get('API_URL')}'),
      ),
    );
  }
}

Build the app with the flavor argument:

For Android:

flutter build apk --dart-define=FLAVOR=production

For iOS:

flutter build ios --dart-define=FLAVOR=production

You can also integrate this with your IDE (e.g., Android Studio or Xcode) by setting the --dart-define flag in your run configurations.

Additional Tips

• Secure Your API Keys: Avoid committing .env files to your Git repository. Add them to your .gitignore file.
• Validate Environment Variables: Ensure that all necessary environment variables are set before running your app. You can add checks in your code to verify that the required variables exist and have valid values.
• Use Different App Icons and Names: Change app icons and names based on the environment to differentiate between builds easily. This can be done in your build.gradle (for Android) or in Xcode (for iOS).

Conclusion

Using environment variables to manage flavor-specific settings and API keys in Flutter is a robust approach to enhance the security, flexibility, and maintainability of your apps. By leveraging the flutter_dotenv package and understanding how to configure flavors, you can efficiently manage different settings across various build environments, making your Flutter development process more streamlined and secure. Remember to protect your API keys and sensitive information by not committing .env files to your version control system.