envied 0.5.4+1
envied: ^0.5.4+1 copied to clipboard
Explicitly reads environment variables into a dart file from a .env file for more security and faster start up times.
ENVied
A cleaner way to handle your environment variables in Dart/Flutter.
(GREATLY inspired by Envify)
Table of Contents #
Overview #
Using a .env
file such as:
KEY=VALUE
or system environment variables such as:
export VAR=test
and a dart class:
import 'package:envied/envied.dart';
part 'env.g.dart';
@envied
abstract class Env {
@EnviedField(varName: 'KEY')
static const key = _Env.key;
}
Envied will generate the part file which contains the values from your .env
file using build_runner
You can then use the Env class to access your environment variable:
print(Env.key); // "VALUE"
Install #
Add both envied
and envied_generator
as dependencies,
If you are using creating a Flutter project:
$ flutter pub add envied
$ flutter pub add --dev envied_generator
$ flutter pub add --dev build_runner
If you are using creating a Dart project:
$ dart pub add envied
$ dart pub add --dev envied_generator
$ dart pub add --dev build_runner
This installs three packages:
- build_runner, the tool to run code-generators
- envied_generator, the code generator
- envied, a package containing the annotations.
Usage #
Add a .env
file at the root of the project. The name of this file can be specified in your Envied class if you call it something else such as .env.dev
.
KEY1=VALUE1
KEY2=VALUE2
Create a class to ingest the environment variables (lib/env/env.dart
). Add the annotations for Envied on the class and EnviedField for any environment variables you want to be pulled from your .env
file.
IMPORTANT! Add both
.env
andenv.g.dart
files to your.gitignore
file, otherwise, you might expose your environment variables.
// lib/env/env.dart
import 'package:envied/envied.dart';
part 'env.g.dart';
@Envied(path: '.env.dev')
abstract class Env {
@EnviedField(varName: 'KEY1')
static const key1 = _Env.key1;
@EnviedField()
static const KEY2 = _Env.KEY2;
@EnviedField(defaultValue: 'test_')
static const key3 = _Env.key3;
}
Then run the generator:
dart run build_runner build
You can then use the Env class to access your environment variables:
print(Env.key1); // "VALUE1"
print(Env.KEY2); // "VALUE2"
Obfuscation/Encryption #
Add the obfuscate
flag to EnviedField
@EnviedField(obfuscate: true)
Please keep in mind that this only increases the amount of effort to retrieve the obfuscated/encrypted values. If someone tries hard enough, he will eventually find the values. For more information, see https://github.com/frencojobs/envify/pull/28 and https://github.com/petercinibulk/envied/pull/4!
Optional Environment Variables #
Enable allowOptionalFields
to allow nullable types. When a default
value is not provided and the type is nullable, the generator will
assign the value to null instead of throwing an exception.
By default, optional fields are not enabled because it could be confusing while debugging. If a field is nullable and a default value is not provided, it will not throw an exception if it is missing an environment variable.
For example, this could be useful if you are using an analytics service for an open-source app, but you don't want to require users or contributors to provide an API key if they build the app themselves.
@Envied(allowOptionalFields: true)
abstract class Env {
@EnviedField()
static const String? optionalServiceApiKey = _Env.optionalServiceApiKey;
}
Optional fields can also be enabled on a per-field basis by setting
@EnviedField(optional: true)
Environment Variable Naming Conventions #
The envied
package provides a convenient way to handle environment variables in Dart applications. With the addition of the useConstantCase
flag in the @EnvField
and @Envied
annotation, developers can now easily adhere to the Dart convention for constant names. The useConstantCase
flag allows the automatic transformation of field names from camelCase
to CONSTANT_CASE
when the @EnvField
annotation is not explicitly assigned a varName
.
By default, this is set to false
, which means that the field name will retain its original format unless varName
is specified. When set to true
, the field name will be automatically transformed into CONSTANT_CASE
, which is a commonly used case type for environment variable names.
@Envied(path: '.env', useConstantCase: true)
final class Env {
@EnviedField()
static const String apiKey = _Env.apiKey; // Transformed to 'API_KEY'
@EnviedField(varName: 'apiKey')
static const String apiKey = _Env.apiKey; // Searches for a variable named 'apiKey' inside the .env file and assigns it to apiKey
}
This option can also be enabled on a per-field basis by setting
@EnviedField(useConstantCase: true)
static const String apiKey; // Transformed to 'API_KEY'
@EnviedField()
static const String apiKey; // Retains its original value, which is `apiKey`
@EnviedField(varName: 'DEBUG_API_KEY')
static const String apiKey; // Searches for a variable named 'DEBUG_API_KEY' inside the .env file and assigns it to apiKey
These example illustrates how the field name apiKey
is automatically transformed to API_KEY
, adhering to the CONSTANT_CASE
convention commonly used as the variable name inside the .env
file. This feature contributes to improved code consistency and readability, while also aligning with Effective Dart naming conventions.
Build configuration overrides #
You can override the default .env
file path by creating a build.yaml
file in the root of your project.
targets:
$default:
builders:
envied_generator|envied:
options:
path: .env.custom
override: true
Note that both path
and override
must be set for the override to work.
Known issues #
When modifying the .env
file, the generator might not pick up the change due to dart-lang/build#967.
If that happens simply clean the build cache and run the generator again.
dart run build_runner clean
dart run build_runner build --delete-conflicting-outputs
For more information please see petercinibulk/envied#6 and/or the original issue dart-lang/build#967.
License #
MIT © Peter Cinibulk