Managing Environment Variables in Flutter Web

This article was translated specially for the channel FlutterPulseYou'll find lots of interesting things related to Flutter on this channel. Don't hesitate to subscribe!🚀

Introduction

Introduction

Managing environment variables in Flutter Web requires a different approach compared to mobile apps. Since Flutter Web cannot read .env files from the server, we need a hybrid strategy:

✅ Use flutter_dotenv for local development (loads .env files).
✅ Use dart-define for deployment (since .env cannot be used on production servers).
✅ Configure VS Code for easy environment switching.

This guide will walk you through the best way to manage environment variables in Flutter Web. 🚀

1. Installing Dependencies

Run the following command to add dotenv support:

flutter pub add flutter_dotenv

2. Creating Environment Files

Inside your Flutter project root, create three .env files:

.env.dev

API_URL=https://api.dev.local

.env.uat

API_URL=https://api.uat.local

.env.prod

API_URL=https://api.prod.local

Ignore .env Files in Git

Modify .gitignore to prevent committing environment files:

.env*

Also, register the .env files in your pubspec.yaml under assets:

flutter:
  assets:
    - .env.dev
    - .env.uat
    - .env.prod

3. Creating a Dedicated env_config.dart File

Instead of managing environment variables in main.dart, create a separate file to keep the code clean.

lib/core/env_config.dart

import 'package:flutter_dotenv/flutter_dotenv.dart';

class EnvConfig {
  /// Checks if the app is running on Web
  static final bool isWeb = const bool.fromEnvironment('IS_WEB', defaultValue: false);

  /// Reads the environment type (dev, uat, prod) from `dart-define`. Defaults to 'dev'.
  static final String env = const String.fromEnvironment('ENV', defaultValue: 'dev');

  /// Loads the correct environment file for local development.
  static Future<void> loadEnv() async {
    if (!isWeb) {
      String envFile = '.env.$env';
      try {
        await dotenv.load(fileName: envFile);
      } catch (e) {
        throw Exception('Failed to load environment file: $envFile. Make sure it exists.');
      }
    }
  }

  /// Retrieves the API URL from `dart-define` or `.env` file.
  static String get apiUrl {
    return const String.fromEnvironment('API_URL', defaultValue: '')
        .isNotEmpty
        ? const String.fromEnvironment('API_URL')
        : dotenv.env['API_URL'] ?? 'https://api.default.com';
  }
}

Why This Approach?

✅ Ensures correct .env file loads dynamically
✅ Supports both local (dotenv) & deployment (dart-define)
✅ Prevents missing environment file errors

4. Updating main.dart

Modify main.dart to load environment variables properly.

main.dart

import 'package:flutter/material.dart';
import 'core/env_config.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await EnvConfig.loadEnv();

  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Web Env',
      home: Scaffold(
        body: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              Text('API_URL: ${EnvConfig.apiUrl}'),
            ],
          ),
        ),
      ),
    );
  }
}

5. Running and Deploying the App

For Local Development (Using .env)

Run the app with the appropriate environment file:

flutter run --dart-define=ENV=dev

This loads .env.dev. Similarly, for UAT and Prod:

flutter run --dart-define=ENV=uat
flutter run --dart-define=ENV=prod

For Web Deployment (Using dart-define)

Since .env files cannot be read in production, we pass values using dart-define.

For Production:

flutter build web --dart-define=IS_WEB=true --dart-define=ENV=prod --dart-define=API_URL=https://api.prod.com

For UAT:

flutter build web --dart-define=IS_WEB=true --dart-define=ENV=uat --dart-define=API_URL=https://api.uat.com

For Dev:

flutter build web --dart-define=IS_WEB=true --dart-define=ENV=dev --dart-define=API_URL=https://api.dev.com

6. VS Code Configuration for Quick Environment Switching

To make switching environments easier, configure VS Code's .vscode/launch.json.

.vscode/launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Flutter Web (Dev)",
      "type": "dart",
      "request": "launch",
      "program": "lib/main.dart",
      "args": ["--dart-define=ENV=dev"],
      "envFile": "${workspaceFolder}/.env.dev"
    },
    {
      "name": "Flutter Web (UAT)",
      "type": "dart",
      "request": "launch",
      "program": "lib/main.dart",
      "args": ["--dart-define=ENV=uat"],
      "envFile": "${workspaceFolder}/.env.uat"
    },
    {
      "name": "Flutter Web (Prod)",
      "type": "dart",
      "request": "launch",
      "program": "lib/main.dart",
      "args": ["--dart-define=ENV=prod"],
      "envFile": "${workspaceFolder}/.env.prod"
    }
  ]
}

Conclusion

✅ Local Development → Uses .env files
✅ Production Deployment → Uses dart-define
✅ VS Code Configurations → Easily switch between environments

This approach ensures a clean, scalable, and production-ready solution for managing environment variables in Flutter Web. 🚀

💬 If anyone knows a way to manage a single environment setup for both local development and deployment, let me know in the comments!