env_flutter 0.1.4 icon indicating copy to clipboard operation
env_flutter: ^0.1.4 copied to clipboard

Easily configure any flutter application with global variables using a `.env` files.

env_flutter #

Pub Version

Load configuration at runtime from a .env file which can be used throughout the application.

The twelve-factor app stores config in environment variables (often shortened to env vars or env). Env vars are easy to change between deploys without changing any code... they are a language- and OS-agnostic standard.

About #

This library is a fork of java-james/flutter_dotenv dart library, with slight changes to make it read stage specific .env files.

An environment is the set of variables known to a process (say, PATH, PORT, ...). It is desirable to mimic the production environment during development (testing, staging, ...) by reading these values from a file.

This library parses that file and merges its values with the built-in Platform.environment map.

Usage #

  1. Create a .env file in the root of your project with the example content:
# This is a comment

Note: If deploying to web server, ensure that the config file is uploaded and not ignored. (Whitelist the config file on the server, or name the config file without a leading .)

  1. Add all .env files to your assets bundle in pubspec.yaml. Ensure that the path corresponds to the location of the .env file!
  - .env
  - .env.development
  - .env.production
  - .env.test
  - .env.local
  - .env.development.local
  - .env.production.local
  - .env.test.local
  1. Remember to add all the .env files as an entries in your .gitignore if it isn't already unless you want it included in your version control.
  1. Load the .env file in main.dart.
import 'package:env_flutter/env_flutter.dart';

// DotEnv dotenv = DotEnv() is automatically called during import.
// If you want to load multiple dotenv files or name your dotenv object differently, you can do the following and import the singleton into the relavant files:
// DotEnv another_dotenv = DotEnv()

Future main() async {
  // To load the .env file contents into dotenv.
  // NOTE: fileName defaults to .env and can be omitted in this case.
  // Ensure that the filename corresponds to the path in step 1 and 2.
  await dotenv.load();
  //... run the app

You can then access variables from .env throughout the application

import 'package:env_flutter/env_flutter.dart';

Optionally you could map env after load to a config model to access a config with types.

What other .env files can be used? #

  • .env: Default.
  • .env.local: Local overrides. This file is loaded for all environments except test.
  • .env.development, .env.test, .env.production: Environment-specific settings.
  • .env.development.local, .env.test.local, .env.production.local: Local overrides of environment-specific settings.

Files on the left have more priority than files on the right: #

flutter run: .env.development.local, .env.local, .env.development, .env
npm build: .env.production.local, .env.local, .env.production, .env
flutter test: .env.test.local, .env.test, .env (note .env.local is missing)

Advanced usage #

Refer to the test/dotenv_test.dart file for a better idea of the behavior of the .env parser.

Referencing #

You can reference variables defined above other within .env:


You can escape referencing by wrapping the value in single quotes:


Merging #

You can merge a map into the environment on load:

  await DotEnv.load(mergeWith: { "FOO": "foo", "BAR": "bar"});

You can also reference these merged variables within .env:


Using in tests #

There is a testLoad method that can be used to load a static set of variables for testing.

// Loading from a static string.
dotenv.testLoad(fileInput: '''FOO=foo

// Loading from a file synchronously.
dotenv.testLoad(fileInput: File('test/.env').readAsStringSync());

Null safety #

To avoid null-safety checks for variables that are known to exist, there is a get() method that will throw an exception if the variable is undefined. You can also specify a default fallback value for when the variable is undefined in the .env file.

Future<void> main() async {
  await dotenv.load();

  String foo = dotenv.get('VAR_NAME');

  // Or with fallback.
  String bar = dotenv.get('MISSING_VAR_NAME', fallback: 'sane-default');

  // This would return null.
  String? baz = dotenv.maybeGet('MISSING_VAR_NAME', fallback: null);

Usage with Platform Environment #

The Platform.environment map can be merged into the env:

  // For example using Platform.environment that contains a CLIENT_ID entry
  await DotEnv.load(mergeWith: Platform.environment);

Like other merged entries described above, .env entries can reference these merged Platform.Environment entries if required:


Discussion #

Use the issue tracker for bug reports and feature requests.

Pull requests are welcome.

license: MIT #

pub points


unverified uploader

Easily configure any flutter application with global variables using a `.env` files.

Repository (GitHub)
View/report issues


API reference


Icon for licenses.MIT (LICENSE)




Packages that depend on env_flutter