Modern Dart and Flutter applications often need different configuration values for development, testing, staging, and production environments.

For example, an application may use different:

• API base URLs
• Feature flags
• Application modes
• Debug settings
• Service endpoints
• Build configurations
• Environment-specific values

Instead of hardcoding these values throughout your source code, Dart provides several ways to manage configuration.

Understanding Dart environment variables and configuration is an important skill for Flutter developers because it helps you create applications that are easier to maintain, test, and deploy.

In this guide, we will explore Dart environment variables, compile-time configuration, Flutter build modes, .env files, configuration classes, flavors, security considerations, and practical project structures.

---

What Are Environment Variables?

Environment variables are values provided to an application from its surrounding environment instead of being directly hardcoded into the application source code.

For example, instead of writing:

const apiUrl = 'https://api.example.com';

you may want the application to use different URLs depending on the environment.

For example:

Development → https://dev-api.example.com
Staging     → https://staging-api.example.com
Production  → https://api.example.com

This makes it possible to use the same application code with different configurations.

---

Why Configuration Management Matters

Imagine an application with API URLs written in 20 different files:

'https://dev-api.example.com'

When you move to production, you would need to find and replace every occurrence.

This is difficult to maintain and can easily lead to mistakes.

A better approach is to centralize configuration:

class AppConfig {
  static const apiUrl = 'https://api.example.com';
}

Then use:

final url = '${AppConfig.apiUrl}/users';

Now you only need to change the configuration in one place.

---

Dart Environment Constants

Dart provides the String.fromEnvironment, bool.fromEnvironment, and int.fromEnvironment constructors for reading compile-time environment declarations.

For example:

const apiUrl = String.fromEnvironment('API_URL');

You can provide the value when running your application.

For a Dart program:

dart run -DAPI_URL=https://api.example.com

For Flutter:

flutter run --dart-define=API_URL=https://api.example.com

Then:

const apiUrl = String.fromEnvironment('API_URL');

can access that compile-time value.

---

Understanding --dart-define

One of the most useful configuration features for Flutter developers is:

--dart-define

You can pass configuration values during a build or run command.

For example:

flutter run --dart-define=API_URL=https://dev-api.example.com

Then read it in Dart:

const apiUrl = String.fromEnvironment('API_URL');

This is useful for values that need to change between builds.

---

Multiple Environment Variables

You can provide multiple values:

flutter run \
  --dart-define=API_URL=https://dev-api.example.com \
  --dart-define=ENVIRONMENT=development

Then:

const apiUrl = String.fromEnvironment('API_URL');
const environment = String.fromEnvironment('ENVIRONMENT');

You can use these values throughout your application.

---

Providing Default Values

You can provide a default value if an environment declaration is missing.

const apiUrl = String.fromEnvironment(
  'API_URL',
  defaultValue: 'https://api.example.com',
);

If API_URL is not provided, the default URL is used.

This can be useful for development, but be careful with production applications. Accidentally using a default configuration can cause an application to communicate with the wrong environment.

---

Boolean Environment Variables

Dart also supports boolean environment values.

const enableLogging = bool.fromEnvironment(
  'ENABLE_LOGGING',
  defaultValue: false,
);

Run:

flutter run --dart-define=ENABLE_LOGGING=true

Then:

if (enableLogging) {
  print('Logging enabled');
}

This is useful for feature flags and debugging options.

---

Integer Environment Variables

You can also read integer values:

const apiTimeout = int.fromEnvironment(
  'API_TIMEOUT',
  defaultValue: 30,
);

Then:

print(apiTimeout);

For example:

flutter run --dart-define=API_TIMEOUT=60

---

Creating a Central Configuration Class

Rather than reading environment values throughout the application, it is often better to create a central configuration class.

Example:

class AppConfig {
  static const apiUrl = String.fromEnvironment(
    'API_URL',
    defaultValue: 'https://api.example.com',
  );

  static const environment = String.fromEnvironment(
    'ENVIRONMENT',
    defaultValue: 'production',
  );

  static const enableLogging = bool.fromEnvironment(
    'ENABLE_LOGGING',
    defaultValue: false,
  );
}

Now your application can use:

print(AppConfig.apiUrl);
print(AppConfig.environment);

This keeps configuration organized.

---

A Better Configuration Model

For larger projects, you can use an immutable configuration object.

class AppConfig {
  final String apiUrl;
  final String environment;
  final bool enableLogging;

  const AppConfig({
    required this.apiUrl,
    required this.environment,
    required this.enableLogging,
  });
}

Then define configurations for different environments.

const developmentConfig = AppConfig(
  apiUrl: 'https://dev-api.example.com',
  environment: 'development',
  enableLogging: true,
);

and:

const productionConfig = AppConfig(
  apiUrl: 'https://api.example.com',
  environment: 'production',
  enableLogging: false,
);

This approach can be useful when your application has complex configuration requirements.

---

Development, Staging, and Production

A common Flutter application has three environments.

Development

Used by developers while building features.

Example:

API: https://dev-api.example.com
Logging: Enabled
Debug features: Enabled

Staging

Used for testing before production.

Example:

API: https://staging-api.example.com
Logging: Limited
Test services: Enabled

Production

Used by real users.

Example:

API: https://api.example.com
Logging: Limited
Debug features: Disabled

The goal is to prevent development configuration from accidentally being shipped to users.

---

Using --dart-define for Different Environments

Development:

flutter run \
  --dart-define=ENVIRONMENT=development \
  --dart-define=API_URL=https://dev-api.example.com

Staging:

flutter run \
  --dart-define=ENVIRONMENT=staging \
  --dart-define=API_URL=https://staging-api.example.com

Production:

flutter run \
  --dart-define=ENVIRONMENT=production \
  --dart-define=API_URL=https://api.example.com

Your Dart code can remain unchanged.

---

Build-Time Configuration

Environment declarations are especially useful because they are available at compile time.

For example:

const environment = String.fromEnvironment('ENVIRONMENT');

The value is determined during compilation.

This is different from reading an arbitrary operating-system environment variable at runtime.

For Flutter applications, --dart-define is therefore a common mechanism for build-time configuration.

---

Compile-Time vs Runtime Configuration

This distinction is important.

Compile-Time Configuration

Values are supplied when the application is built or run.

Example:

flutter build apk --dart-define=API_URL=https://api.example.com

Then:

const apiUrl = String.fromEnvironment('API_URL');

Runtime Configuration

A value is obtained while the application is running.

Examples include:

• Remote configuration
• Local storage
• A downloaded configuration file
• Database settings
• Network response

These approaches solve different problems.

---

.env Files

Flutter developers often use .env files to organize configuration.

A typical .env file might contain:

API_URL=https://dev-api.example.com
ENVIRONMENT=development
ENABLE_LOGGING=true

However, Dart does not automatically load .env files.

You normally need a package or custom configuration mechanism to read them.

A commonly used approach is a package such as flutter_dotenv.

After adding the package, a project might contain:

.env
.env.development
.env.production

The exact loading approach depends on the package and project architecture.

---

Important .env Security Warning

A common misconception is:

“If I put a secret inside .env, it becomes secure.”

That is not true for a Flutter client application.

A mobile or web application ultimately runs on a user’s device or browser. Values bundled into the application can potentially be extracted.

Therefore, do not treat .env files, --dart-define, or Flutter source code as secure storage for highly sensitive server secrets.

Never put credentials such as:

Database passwords
Private server keys
Payment provider secret keys
Private signing secrets
Server administrator credentials

into a client application expecting them to remain secret.

---

.gitignore and Environment Files

If you use local .env files containing private development configuration, you may want to exclude them from Git.

For example:

.env
.env.*

However, make sure your team has a safe method for providing required configuration.

You can commit a template:

.env.example

Example:

API_URL=
ENVIRONMENT=
ENABLE_LOGGING=

This tells developers which configuration values are required without exposing local secrets.

---

Environment Configuration with JSON

Another approach is using a JSON configuration file.

For example:

{
  "environment": "development",
  "apiUrl": "https://dev-api.example.com"
}

The application can load and parse the file.

This can be useful when configuration contains multiple structured values.

However, remember that configuration bundled into the client should not be considered secret.

---

Configuration with Assets

Flutter can package configuration files as assets.

For example:

flutter:
  assets:
    - assets/config/

You could have:

assets/config/
├── development.json
├── staging.json
└── production.json

Then the application can load the appropriate configuration.

This approach is useful for non-secret configuration, but it should not be used to hide sensitive credentials.

---

Environment-Specific Configuration Files

For larger applications, you may organize configuration as:

lib/
└── config/
    ├── app_config.dart
    ├── development_config.dart
    ├── staging_config.dart
    └── production_config.dart

For example:

class DevelopmentConfig {
  static const apiUrl = 'https://dev-api.example.com';
  static const enableLogging = true;
}

Production:

class ProductionConfig {
  static const apiUrl = 'https://api.example.com';
  static const enableLogging = false;
}

This makes configuration explicit and easy to understand.

---

Using Flavors with Flutter

For larger Flutter applications, flavors are commonly used to create separate development, staging, and production builds.

For example:

Development
Staging
Production

You can have different:

• App names
• App icons
• Bundle identifiers
• API endpoints
• Firebase projects
• Configuration values

The exact flavor configuration differs between Android and iOS.

Flavors are especially useful for organizations maintaining multiple application environments.

---

Flutter Flavors + --dart-define

You can combine flavors with compile-time environment values.

For example:

flutter run \
  --flavor development \
  --dart-define=ENVIRONMENT=development

Staging:

flutter run \
  --flavor staging \
  --dart-define=ENVIRONMENT=staging

Production:

flutter run \
  --flavor production \
  --dart-define=ENVIRONMENT=production

This gives you both platform-level configuration and Dart-level configuration.

---

Using Configuration for API URLs

One of the most common use cases is API configuration.

Create:

class AppConfig {
  static const apiUrl = String.fromEnvironment(
    'API_URL',
    defaultValue: 'https://api.example.com',
  );
}

Then your API service can use:

class ApiService {
  String get baseUrl => AppConfig.apiUrl;
}

Now you can change the API endpoint without changing your service implementation.

---

Configuration for Feature Flags

Environment configuration can also control feature flags.

For example:

const enableNewDashboard = bool.fromEnvironment(
  'ENABLE_NEW_DASHBOARD',
  defaultValue: false,
);

Run:

flutter run --dart-define=ENABLE_NEW_DASHBOARD=true

Then:

if (enableNewDashboard) {
  // New dashboard
} else {
  // Existing dashboard
}

This can be useful when testing features before making them available in production.

---

Configuration for Debug Logging

You can control logging with an environment value.

const enableLogs = bool.fromEnvironment(
  'ENABLE_LOGGING',
  defaultValue: false,
);

Then:

void logMessage(String message) {
  if (enableLogs) {
    print(message);
  }
}

Development:

flutter run --dart-define=ENABLE_LOGGING=true

Production:

flutter build apk --dart-define=ENABLE_LOGGING=false

---

Configuration for API Timeouts

You can configure an API timeout:

const timeoutSeconds = int.fromEnvironment(
  'API_TIMEOUT',
  defaultValue: 30,
);

Then:

final timeout = Duration(
  seconds: timeoutSeconds,
);

This can be useful when different environments require different timeout settings.

---

Configuration for Application Modes

You can define an application mode:

const mode = String.fromEnvironment(
  'APP_MODE',
  defaultValue: 'production',
);

Then:

if (mode == 'development') {
  // Development behavior
}

However, avoid spreading environment checks throughout your entire application.

A centralized configuration layer is usually cleaner.

---

Avoid Scattering Configuration

Avoid doing this everywhere:

const apiUrl = String.fromEnvironment('API_URL');

in dozens of files.

Instead:

class AppConfig {
  static const apiUrl = String.fromEnvironment('API_URL');
}

Then:

AppConfig.apiUrl

This makes the project easier to maintain.

---

A Recommended Configuration Structure

For a medium-sized Flutter project, you could use:

lib/
├── config/
│   ├── app_config.dart
│   ├── environment.dart
│   └── app_constants.dart
├── services/
├── models/
├── repositories/
├── controllers/
└── main.dart

For example:

enum Environment {
  development,
  staging,
  production,
}

and:

class AppConfig {
  static const apiUrl = String.fromEnvironment(
    'API_URL',
  );

  static const environment = String.fromEnvironment(
    'ENVIRONMENT',
    defaultValue: 'development',
  );
}

This gives you a single source of truth for application configuration.

---

Environment Variables in CI/CD

Environment configuration becomes particularly useful in CI/CD systems.

For example, your CI pipeline can build a production application with:

flutter build apk \
  --dart-define=ENVIRONMENT=production \
  --dart-define=API_URL=https://api.example.com

The important advantage is that the build system can provide configuration without requiring developers to modify the source code before every release.

---

Configuration in GitHub Actions

A CI workflow can provide values from its own environment or secret-management system and pass appropriate values into the Flutter build command.

Conceptually:

- name: Build Flutter App
  run: |
    flutter build apk \
      --dart-define=ENVIRONMENT=production \
      --dart-define=API_URL=${API_URL}

For sensitive server-side credentials, use your CI provider’s secret-management facilities rather than putting secrets directly into the repository.

Remember that if a value is compiled into a Flutter client application, it should be treated as potentially discoverable by users.

---

Configuration and Firebase

Many Flutter applications use multiple Firebase projects for:

• Development
• Staging
• Production

Environment-specific configuration can help select the appropriate Firebase setup.

For example:

Development → Development Firebase project
Staging     → Staging Firebase project
Production  → Production Firebase project

This prevents development data from accidentally being mixed with production data.

However, Firebase client configuration values should not automatically be considered secret merely because they come from configuration files. Security should be enforced using proper Firebase security rules, authentication, App Check where appropriate, and server-side controls.

---

Configuration for Different Platforms

Flutter applications can target:

• Android
• iOS
• Web
• macOS
• Windows
• Linux

Some configuration values may be platform-specific.

For example:

Android → Android-specific configuration
iOS     → iOS-specific configuration
Web     → Web-specific configuration

Your application configuration architecture should clearly separate values that are common across platforms from values that must be platform-specific.

---

Compile-Time Constants and const

Dart environment declarations are compile-time values.

For example:

const environment = String.fromEnvironment('ENVIRONMENT');

Because it is a compile-time environment declaration, it can be used where a compile-time constant is required.

This is different from reading a value from a file or network at runtime.

---

Environment Configuration Is Not Secret Storage

This is one of the most important concepts to understand.

The following are not secure secret storage mechanisms in a distributed Flutter application:

--dart-define
.env
assets/config.json
pubspec.yaml
Dart source code

If the value needs to remain secret from the user of the application, it generally should not be embedded in the client.

Instead, sensitive operations should be moved to a trusted backend.

For example:

Flutter App
     ↓
Your Backend
     ↓
Private Service

The backend can keep private credentials away from the client.

---

Common Mistakes

1. Hardcoding Environment-Specific URLs Everywhere

Avoid:

final url = 'https://dev-api.example.com';

in multiple services.

Centralize configuration.

---

2. Putting Secrets in .env

A .env file does not magically make secrets secure.

Do not embed private production credentials into a mobile or web application.

---

3. Using Production APIs During Development

Make sure development builds point to the development backend.

Otherwise, test operations can accidentally modify real production data.

---

4. Mixing Configuration with Business Logic

Avoid:

if (const String.fromEnvironment('ENVIRONMENT') == 'production') {
  // ...
}

throughout your business logic.

Prefer:

if (AppConfig.isProduction) {
  // ...
}

or, better yet, inject configuration into the relevant service.

---

5. Too Many Configuration Sources

If your project uses:

.dart-define
.env
JSON
Firebase config
hardcoded constants
platform configuration

without a clear strategy, debugging becomes difficult.

Choose a clear hierarchy and document it.

---

Best Practices

Follow these practices for maintainable Dart and Flutter configuration.

Centralize configuration

Keep environment-related values in one configuration layer.

Separate environments

Clearly distinguish:

Development
Staging
Production

Use --dart-define for build-time values

It is a useful mechanism for compile-time configuration.

Use flavors for platform-specific builds

Flavors are useful when builds need different app identities or platform configuration.

Keep secrets out of the client

Never assume client-side configuration is private.

Use CI/CD configuration

Provide environment-specific values during automated builds where appropriate.

Document required variables

Create a configuration template such as:

API_URL=
ENVIRONMENT=
ENABLE_LOGGING=

so new developers know what is required.

Avoid unnecessary environment checks

Do not make every part of the application aware of the environment.

Keep environment logic near the configuration boundary.

---

Recommended Project Example

A practical Flutter project might look like:

my_app/
├── android/
├── ios/
├── lib/
│   ├── config/
│   │   ├── app_config.dart
│   │   └── environment.dart
│   ├── models/
│   ├── services/
│   ├── repositories/
│   ├── screens/
│   └── main.dart
├── assets/
├── test/
├── .env.example
├── pubspec.yaml
└── README.md

A centralized configuration file could contain:

class AppConfig {
  static const apiUrl = String.fromEnvironment(
    'API_URL',
    defaultValue: 'https://api.example.com',
  );

  static const environment = String.fromEnvironment(
    'ENVIRONMENT',
    defaultValue: 'production',
  );

  static const enableLogging = bool.fromEnvironment(
    'ENABLE_LOGGING',
    defaultValue: false,
  );

  static bool get isDevelopment =>
      environment == 'development';

  static bool get isStaging =>
      environment == 'staging';

  static bool get isProduction =>
      environment == 'production';
}

Then your application can simply use:

if (AppConfig.isDevelopment) {
  print('Development environment');
}

---

Quick Dart Configuration Cheat Sheet

Requirement	Recommended Approach
API URL	String.fromEnvironment / --dart-define
Feature flag	bool.fromEnvironment / --dart-define
Numeric build configuration	int.fromEnvironment
Local developer configuration	.env with an appropriate package
Public configuration file	JSON/assets
Development/staging/production builds	Flutter flavors + configuration
CI/CD configuration	CI environment/configuration
Private server secrets	Keep them on a trusted backend
Centralized application configuration	Configuration class/object

---

Frequently Asked Questions

What is String.fromEnvironment() in Dart?

String.fromEnvironment() reads a compile-time environment declaration provided when Dart code is compiled or run.

Example:

const apiUrl = String.fromEnvironment('API_URL');

---

How do I pass environment variables to Flutter?

Use --dart-define.

flutter run --dart-define=API_URL=https://api.example.com

Then read it using:

const apiUrl = String.fromEnvironment('API_URL');

---

Does Flutter automatically load .env files?

No. Dart and Flutter do not automatically treat .env files as runtime environment variables. A package or custom loading mechanism is normally required.

---

Are --dart-define values secure?

No. Values compiled into a client application should not be treated as secrets. A user with sufficient access to the application can potentially inspect or extract them.

---

Should API URLs be stored in environment variables?

Using environment-specific configuration for API URLs can be a good practice because development, staging, and production environments often use different endpoints.

---

Should API keys be stored using --dart-define?

Only if the value is not actually a secret. A client-side application cannot reliably hide a secret that it needs to use.

Private credentials should generally be kept on a backend.

---

What is the difference between .env and --dart-define?

.env is a file-based configuration approach typically loaded through a package or custom code.

--dart-define provides compile-time environment declarations directly to Dart/Flutter tooling.

They solve similar configuration problems but work differently.

---

Final Thoughts

Environment configuration is an important part of professional Dart and Flutter development.

For simple projects, a centralized configuration class may be enough. As your application grows, you may combine --dart-define, environment-specific configuration, Flutter flavors, CI/CD variables, and a clear configuration architecture.

The most important thing to remember is that configuration and security are not the same thing. A value being outside your main Dart source code does not automatically make it secret.

A good Flutter configuration strategy should provide:

• Clear development, staging, and production environments
• Centralized configuration
• Easy CI/CD integration
• Fewer hardcoded environment-specific values
• Simple local development
• Safe handling of sensitive credentials
• Easy maintenance as the application grows

Once you understand these concepts, managing multiple Flutter environments becomes much easier and your projects become more reliable and deployment-friendly.

Good configuration keeps your code flexible; good security keeps your secrets protected.