Loads Environment Variables From .env

flutter_dotenv .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 mockturtl/dotenv dart library, initially with slight changes to make it work with flutter.

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

Create a .env file in the root of your project with the example content:

FOO=foo
BAR=bar
FOOBAR=$FOO$BAR
ESCAPED_DOLLAR_SIGN='$1000'
# 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 .)

Add the .env file to your assets bundle in pubspec.yaml. Ensure that the path corresponds to the location of the .env file!

assets:
  - .env

Remember to add the .env file as an entry in your .gitignore if it isn't already unless you want it included in your version control.

*.env

Load the .env file in main.dart. Note that flutter_dotenv >=5.0.0 has a slightly different syntax for consuming the DotEnv data.

v5.0.0 and later

import 'package:flutter_dotenv/flutter_dotenv.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(fileName: ".env");
  //...runapp
}

You can then access variables from .env throughout the application

import 'package:flutter_dotenv/flutter_dotenv.dart';
dotenv.env['VAR_NAME'];

Before v5.0.0

import 'package:flutter_dotenv/flutter_dotenv.dart' as DotEnv;

Future main() async {
  await DotEnv.load(fileName: ".env");
  //...runapp
}

Access env using:

import 'package:flutter_dotenv/flutter_dotenv.dart';
env['VAR_NAME'];

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

Advanced usage

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

Referencing

You can reference variables defined above other within .env:

  FOO=foo
  BAR=bar
  FOOBAR=$FOO$BAR

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

ESCAPED_DOLLAR_SIGN='$1000'

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:

  FOOBAR=$FOO$BAR

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
BAR=bar
''');

// 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);
  print(env["CLIENT_ID"]);

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

  CLIENT_URL=https://$CLIENT_ID.dev.domain.com

Discussion

Use the issue tracker for bug reports and feature requests.

Pull requests are welcome.

Prior art

mockturtl/dotenv (dart)
bkeepers/dotenv (ruby)
motdotla/dotenv (node)
theskumar/python-dotenv (python)
joho/godotenv (go)
slapresta/rust-dotenv (rust)
chandu/dotenv (c#)
tpope/lein-dotenv, rentpath/clj-dotenv (clojure)
mefellows/sbt-dotenv (scala)
greenspun/dotenv (half of common lisp)

Use this package as a library

Depend on it

Run this command:

With Flutter:

 $ flutter pub add flutter_dotenv

This will add a line like this to your package's pubspec.yaml (and run an implicit dart pub get):


dependencies:
  flutter_dotenv: ^5.0.2

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

Import it

Now in your Dart code, you can use:

import 'package:flutter_dotenv/flutter_dotenv.dart';

example/lib/main.dart

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

Future main() async {
  await dotenv.load(fileName: "assets/.env", mergeWith: {
    'TEST_VAR': '5',
  }); // mergeWith optional, you can include Platform.environment for Mobile/Desktop app

  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) => MaterialApp(
        title: 'Dotenv Demo',
        home: Scaffold(
          appBar: AppBar(
            title: Text('Dotenv Demo'),
          ),
          body: SingleChildScrollView(
            child: FutureBuilder<String>(
              future: rootBundle.loadString('assets/.env'),
              initialData: '',
              builder: (context, snapshot) => Container(
                padding: EdgeInsets.all(50),
                child: Column(
                  children: [
                    Text(
                      'Env map: ${dotenv.env.toString()}',
                    ),
                    Divider(thickness: 5),
                    Text('Original'),
                    Divider(),
                    Text(snapshot.data ?? ''),
                    Text(dotenv.get('MISSING', fallback: 'Default fallback value')),
                  ],
                ),
              ),
            ),
          ),
        ),
      );
}

#fluter #dart #mobile-apps