Envied
Handles environment variables in dart from a .env file.
Install / Use
/learn @petercinibulk/EnviedREADME
A cleaner way to handle your environment variables in Dart/Flutter.
(GREATLY inspired by Envify)
</div> <br>Table of Contents
<br>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 String 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,
dart pub add envied dev:envied_generator 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
.envandenv.g.dartfiles to your.gitignorefile, 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 String key1 = _Env.key1;
@EnviedField()
static const String KEY2 = _Env.KEY2;
@EnviedField(defaultValue: 'test_')
static const String 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)
Note that the value must be static final and not static const for this to work, i.e.
abstract class Env {
@EnviedField(obfuscate: true)
static final String apiKey = _Env.apiKey;
}
Keep in mind that this only makes it more difficult to access the obfuscated or encrypted values, it does NOT make them completely secure. A determined individual may still be able to retrieve them. For more details, 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.
Using System Environment Variables
Using the environment option in either an Envied or EnviedField instructs the generator to use the value from the
.env file as the key for a system environment variable read from Platform.environment.
For example, let's use the Envied class and the following .env files:
@Envied(environment: true)
final class Env {
@EnviedField(varName: 'API_KEY')
static const String apiKey = _Env.apiKey;
}
... or ...
@Envied()
final class Env {
@EnviedField(environment: true, varName: 'API_KEY')
static const String apiKey = _Env.apiKey;
}
latest.env
API_KEY=LATEST_API_KEY
stage.env
API_KEY=STAGE_API_KEY
Depending on which .env file you use to generate can result in the API_KEY being read from either
Platform.environment['LATEST_API_KEY'] or Platform.environment['STAGE_API_KEY']. This can allow for the .env
files to be safely checked in to the source control, the specific values to be set at build time, and keep the secrets
safely stored in the host environment.
For instructions on switching the .env file at build time, see Setting file from CLI.
Setting file from CLI
To change which .env file is used by default using the CLI, pass it in via the --define flag as follows:
dart run build_runner build --define=envied_generator:envied=path=my_other.env
And also set the override parameter to true inside build.yaml file. Without it envied always uses the default
.env path.
targets:
$default:
builders:
envied_generator|envied:
options:
override: true
This allows you to have multiple .env files, one per backend for instance, and then switch which one gets included in
the build easily from CI/CD scripts such as github workflows.
Multiple environments
Say you need to have different environ
Related Skills
node-connect
346.4kDiagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps
frontend-design
107.2kCreate distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
openai-whisper-api
346.4kTranscribe audio via OpenAI Audio Transcriptions API (Whisper).
qqbot-media
346.4kQQBot 富媒体收发能力。使用 <qqmedia> 标签，系统根据文件扩展名自动识别类型（图片/语音/视频/文件）。
