Managing configuration correctly is an important part of building reliable Dart and Flutter applications. API URLs, feature flags, application modes, credentials, environment-specific settings, and other configuration values often need to change between development, testing, staging, and production.

Hardcoding these values directly into your Dart source code can make applications difficult to maintain and can create security problems. Dart provides several approaches for handling configuration, including compile-time environment variables, String.fromEnvironment, bool.fromEnvironment, int.fromEnvironment, dart run -D, and Flutter’s --dart-define options.

This guide explains Dart environment variables and configuration from the basics to practical production patterns.

What Are Environment Variables?

Environment variables are configuration values supplied to an application from outside its source code.

For example, an application may use different API endpoints:

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

Staging:
https://staging-api.example.com

Production:
https://api.example.com

Instead of writing:

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

you can make the value configurable:

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

Then provide the value when compiling or running the application.

This makes the same codebase usable across multiple environments.

Why Is Configuration Important in Dart?

A well-designed configuration system provides several benefits:

• Different settings for development and production
• Easier deployment
• Better separation between code and configuration
• Easier testing
• Support for feature flags
• Reduced hardcoding
• Cleaner application architecture
• More flexible CI/CD pipelines

For example, you may want:

Development → Debug logging enabled
Staging     → Test API enabled
Production  → Production API enabled

The application code can remain the same while the configuration changes.

---

Dart Environment Variables vs Configuration

Although these terms are often used together, they are not exactly the same.

Environment variables generally refer to values supplied by the operating system, shell, build system, or deployment environment.

Application configuration is broader and can include:

• API endpoints
• Application names
• Feature flags
• Logging settings
• Timeouts
• Environment names
• Build identifiers
• Service configuration

In Dart and Flutter, compile-time environment declarations are commonly handled using String.fromEnvironment, bool.fromEnvironment, and related APIs.

---

Using String.fromEnvironment

One of the most common ways to read a Dart compile-time environment value is:

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

Here:

• API_URL is the environment key.
• String.fromEnvironment() retrieves its value.
• const is important because this value is intended for compile-time configuration.

For example:

void main() {
  const apiUrl = String.fromEnvironment('API_URL');

  print(apiUrl);
}

You can provide the value using a Dart command such as:

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

The application can then access the configured value.

---

Using bool.fromEnvironment

Boolean configuration values can be read using:

const enableLogging = bool.fromEnvironment('ENABLE_LOGGING');

For example:

void main() {
  const enableLogging = bool.fromEnvironment('ENABLE_LOGGING');

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

You can run the application with:

dart run -DENABLE_LOGGING=true

This is particularly useful for feature flags.

For example:

const newDashboard =
    bool.fromEnvironment('NEW_DASHBOARD');

Then:

if (newDashboard) {
  showNewDashboard();
} else {
  showOldDashboard();
}

---

Using int.fromEnvironment

Dart also supports integer configuration:

const timeoutSeconds =
    int.fromEnvironment('TIMEOUT_SECONDS');

You can provide:

dart run -DTIMEOUT_SECONDS=30

Then:

void main() {
  const timeoutSeconds =
      int.fromEnvironment('TIMEOUT_SECONDS');

  print('Timeout: $timeoutSeconds seconds');
}

This can be useful for configurable:

• Timeouts
• Retry counts
• Pagination sizes
• Cache durations
• Limits

---

Providing Default Values

A configuration value may not always be provided.

Dart allows you to specify a default value.

For strings:

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

For booleans:

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

For integers:

const timeout = int.fromEnvironment(
  'TIMEOUT_SECONDS',
  defaultValue: 30,
);

Default values make applications more resilient when a configuration parameter is missing.

---

Dart -D Environment Definitions

The -D option allows you to provide compile-time environment declarations.

For example:

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

Multiple values can be supplied:

dart run \
  -DAPI_URL=https://api.example.com \
  -DENVIRONMENT=production \
  -DENABLE_LOGGING=false

Your Dart code can then read them:

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

---

Configuration in Flutter

Flutter applications also support Dart environment declarations.

For example:

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

You can access the value in Dart:

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

For multiple values:

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

Then:

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

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

const enableLogging =
    bool.fromEnvironment('ENABLE_LOGGING');

This is one of the most useful configuration patterns for Flutter projects.

---

Flutter Build Configuration

The same approach can be used when creating release builds.

For Android:

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

For an Android App Bundle:

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

For iOS:

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

The application receives the configuration during the build process.

---

Development, Staging, and Production

A common application structure contains multiple environments.

For example:

Development
Staging
Production

Each environment may have different configuration.

Development

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

Staging

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

Production

API_URL=https://api.example.com
ENVIRONMENT=production
ENABLE_LOGGING=false

The Dart source code doesn’t need to change.

Only the build configuration changes.

---

Creating a Central Configuration Class

For larger projects, repeatedly calling String.fromEnvironment() throughout the application can become difficult to maintain.

A better approach is to create a centralized configuration class.

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

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

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

  static const timeoutSeconds = int.fromEnvironment(
    'TIMEOUT_SECONDS',
    defaultValue: 30,
  );
}

Now the application can use:

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

This creates a single location for application configuration.

---

Creating Environment-Specific Configurations

A more structured configuration class can expose useful properties.

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

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

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

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

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

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

Now you can write:

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

or:

if (AppConfig.isDevelopment) {
  // Development behavior
}

---

Using Configuration for API Endpoints

One of the most common use cases is configuring API URLs.

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

Your API service can then use:

class ApiService {
  static const baseUrl = AppConfig.apiUrl;

  // API methods can use baseUrl here.
}

Run development:

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

Build production:

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

This keeps environment-specific endpoints outside the main source code.

---

Feature Flags with Dart Configuration

Environment configuration is also useful for feature flags.

For example:

class AppConfig {
  static const enableNewDashboard =
      bool.fromEnvironment(
    'ENABLE_NEW_DASHBOARD',
    defaultValue: false,
  );
}

Then:

Widget buildDashboard() {
  if (AppConfig.enableNewDashboard) {
    return const NewDashboard();
  }

  return const OldDashboard();
}

You can enable the feature during a build:

flutter run \
  --dart-define=ENABLE_NEW_DASHBOARD=true

This can be useful for testing new functionality before making it the default.

---

Debug Configuration

You may want additional logging during development.

For example:

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

Then:

void logMessage(String message) {
  if (AppConfig.enableLogging) {
    print(message);
  }
}

Development:

flutter run \
  --dart-define=ENABLE_LOGGING=true

Production:

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

---

Environment Names

You can configure the current application environment:

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

Then:

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

The application can display or use:

print('Running environment: $environment');

Possible values include:

development
staging
production

---

Using Configuration with CI/CD

Environment configuration becomes especially useful in CI/CD systems.

A CI/CD pipeline can build different versions of an application using different configuration values.

For example:

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

A staging pipeline might use:

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

This allows one source code repository to generate multiple application variants.

---

Do Not Put Secrets in Dart Environment Variables

This is one of the most important points about Dart configuration.

Using:

--dart-define=API_KEY=some-secret

does not automatically make that value secure.

For mobile and web applications, compile-time values can potentially be extracted from the built application.

Therefore, you should not assume that Dart environment variables are a secure secret-storage mechanism.

Avoid treating values such as:

Database passwords
Private API keys
Server credentials
Private signing secrets
Admin passwords

as safely hidden just because they were supplied through --dart-define.

A client application should generally not contain credentials that must remain secret.

---

Configuration vs Secret Management

There is an important distinction:

Suitable for Dart configuration

API base URL
Environment name
Feature flags
Application version settings
Non-sensitive identifiers
Logging preferences
Timeout values

Not suitable for client-side secrets

Database passwords
Private server credentials
Master API keys
Private encryption keys
Administrative credentials

Sensitive secrets should normally remain on trusted backend infrastructure or use an appropriate platform/backend secret-management solution.

---

Using .env Files

Developers often use .env files in web and backend ecosystems.

For example:

API_URL=https://api.example.com
ENVIRONMENT=development

However, a .env file is not automatically supported as a native Dart environment-variable mechanism.

If you want .env-style configuration in a Dart or Flutter project, you typically need a package or another configuration-loading mechanism.

A common pattern is:

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

But remember that if these values are bundled into a client application, they should not be treated as secret.

---

Compile-Time Configuration vs Runtime Configuration

This distinction is important.

Compile-Time Configuration

The value is supplied when the application is built.

Example:

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

The value is determined during compilation.

This works well for:

• API URLs
• Feature flags
• Build environments
• Application variants
• Static configuration

Runtime Configuration

Runtime configuration is loaded while the application is running.

Examples include:

• Remote configuration
• Server-provided settings
• User preferences
• Local configuration files
• Database settings

Runtime configuration is useful when values need to change without rebuilding the application.

---

When Should You Use Compile-Time Configuration?

Use compile-time configuration when values are expected to differ between builds.

For example:

Development build → Development API
Staging build → Staging API
Production build → Production API

Compile-time configuration is simple, fast, and easy to integrate with build pipelines.

---

When Should You Use Runtime Configuration?

Runtime configuration is more appropriate when values need to change without rebuilding the application.

For example, an application might download:

{
  "maintenanceMode": false,
  "minimumVersion": "2.5.0"
}

from a backend.

This allows the server to change behavior without requiring a new application build.

---

A Practical Configuration Architecture

For a Flutter project, a clean structure might look like:

lib/
├── config/
│   ├── app_config.dart
│   ├── environment.dart
│   └── app_constants.dart
├── services/
│   ├── api_service.dart
│   └── auth_service.dart
├── screens/
└── main.dart

The central configuration file can contain:

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

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

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

  static const requestTimeout =
      int.fromEnvironment(
    'REQUEST_TIMEOUT',
    defaultValue: 30,
  );
}

This keeps configuration organized and easy to locate.

---

Example: Complete Flutter Configuration

Here is a simple example:

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

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

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

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

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

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

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

Use it in your application:

void main() {
  if (AppConfig.enableLogging) {
    print('Environment: ${AppConfig.environment}');
    print('API: ${AppConfig.apiUrl}');
  }

  runApp(const MyApp());
}

Build with:

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

For production:

flutter build apk \
  --release \
  --dart-define=API_URL=https://api.example.com \
  --dart-define=ENVIRONMENT=production \
  --dart-define=ENABLE_LOGGING=false \
  --dart-define=TIMEOUT_SECONDS=30

---

Common Mistakes

1. Hardcoding Environment-Specific URLs

Avoid:

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

when multiple environments are required.

Prefer:

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

---

2. Treating --dart-define as Secret Storage

This is a common security mistake.

A compile-time value included in a client application should not be assumed to be confidential.

---

3. Forgetting Default Values

This:

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

may produce an empty string when the value is not supplied.

For many applications, a default is safer:

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

---

4. Scattering Configuration Everywhere

Avoid repeatedly doing:

String.fromEnvironment(...)

throughout dozens of files.

Instead, centralize configuration:

AppConfig.apiUrl
AppConfig.environment
AppConfig.enableLogging

---

5. Mixing Configuration with Business Logic

Configuration should ideally have its own layer.

For example:

Configuration
     ↓
Services
     ↓
Repositories
     ↓
Controllers
     ↓
UI

This makes the project easier to maintain.

---

Best Practices for Dart Configuration

Follow these practices when designing configuration for Dart or Flutter applications:

1. Centralize configuration

Keep environment-related values in one configuration layer.

2. Use meaningful names

Prefer:

API_URL
ENVIRONMENT
ENABLE_LOGGING
REQUEST_TIMEOUT

instead of:

X
VALUE1
CONFIG2

3. Provide sensible defaults

Defaults make local development easier and prevent unexpected failures.

4. Separate environments

Maintain clear configurations for:

Development
Staging
Production

5. Never rely on client-side configuration for secret protection

Anything bundled into a client application should be considered potentially discoverable.

6. Integrate configuration with CI/CD

Build pipelines should supply environment-specific values automatically.

7. Avoid unnecessary configuration

Only make values configurable when there is a real reason.

Too many configuration options can make applications harder to understand.

---

Dart Environment Variables: Quick Reference

Purpose	Dart API / Command
String value	String.fromEnvironment()
Boolean value	bool.fromEnvironment()
Integer value	int.fromEnvironment()
Dart run	dart run -DKEY=value
Flutter run	flutter run --dart-define=KEY=value
Flutter build	flutter build ... --dart-define=KEY=value
Default value	defaultValue:
Central configuration	AppConfig class

---

Example Configuration Commands

Development

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

Staging

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

Production

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

---

Frequently Asked Questions

What is an environment variable in Dart?

In Dart application development, environment configuration commonly refers to compile-time values supplied using Dart environment declarations. They can be accessed with APIs such as String.fromEnvironment() and bool.fromEnvironment().

How do I pass an environment variable to Dart?

You can use:

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

and retrieve it with:

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

How do I pass environment variables to Flutter?

Use:

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

Then:

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

Can I use environment variables for API keys?

You can technically pass values this way, but you should not consider --dart-define a secure secret-storage mechanism for a client application. Sensitive credentials should be kept on trusted backend infrastructure whenever possible.

Can Dart configuration change without rebuilding the application?

Compile-time environment declarations generally require a new build to change. If configuration must change while the application is running, consider a runtime configuration system instead.

Should I use .env files in Flutter?

.env files can be useful with appropriate tooling or packages, but they are not automatically a secure storage mechanism. Any value bundled into a client application should be treated as potentially accessible.

---

Conclusion

Dart provides a straightforward way to manage build-time configuration through environment declarations and APIs such as String.fromEnvironment(), bool.fromEnvironment(), and int.fromEnvironment().

For Flutter applications, --dart-define is particularly useful for separating development, staging, and production configuration:

flutter run --dart-define=ENVIRONMENT=development

Combined with a centralized AppConfig class, this approach can keep projects clean, flexible, and easier to deploy.

The most important rule is to understand the difference between configuration and secrets. Environment values are excellent for API endpoints, feature flags, environment names, and other non-sensitive settings, but they should not be treated as a secure vault for private credentials.

A well-designed configuration architecture allows the same Dart or Flutter codebase to support multiple environments while keeping deployment settings separate from application logic.