envystic 0.3.0

Simplify and Secure Your Environment Variables (dotenv file or system) in Dart/Flutter.

Envystic

Envystic is a Dart/Flutter package that simplifies the management of environment variables (dotenv) and provides an extra layer of security. With Envystic, you can effortlessly handle environment variables in your Dart and Flutter projects, ensuring cleaner and more secure code.

Features

• Easy Environment Variable Management: Envystic simplifies the management of environment variables by providing a convenient and structured way to define and access them in your Dart and Flutter projects.

• Secure Variable Storage: Envystic allows you to provide an optional encryption key to encrypt the values of your environment variables, enhancing the security of sensitive information.

• Annotation-Based Configuration: Defining environment variables is straightforward with the use of annotations. The Envystic and EnvysticField annotations help generate the necessary code for accessing your environment variables.

• Custom Key Names: You can specify custom key names for your environment variables in the .env file, making it easy to reference them in your code.

• Flutter and Dart Support: Envystic is designed to work seamlessly with both Flutter and Dart projects, allowing you to manage environment variables consistently across different types of applications.

Installation

Flutter Project

flutter pub add envystic && flutter pub add --dev envystic_generator build_runner

Dart Project

dart pub add envystic && dart pub add --dev envystic_generator build_runner

Usage

1. Import the envystic package into your Dart/Flutter file:

import 'package:envystic/envystic.dart';

2. Define an environment variable class using the Envystic annotation and the EnvysticField annotation for each desired variable:

part 'env.g.dart';

@envystic
class Env extends _$Env {
  // If no encryption, you can omit `super.encryptionKey`
  // make it like: `const Env();`
  const Env({super.encryptionKey});

  @override
  @envysticField
  String get key1;

  @override
  @EnvysticField(name: 'FOO') // The value from 'FOO' in .env will be used
  int? get key2;

  // ignored
  String get drink => 'Coffee';
}

3. Generate the environment variable class using build_runner:

dart run build_runner build

This will generate the necessary code based on the annotations in your codebase.

4. Access the environment variables in your Dart/Flutter code:

void main() {
  final env = Env();
  // Access environment variables
  print(env.key1); 
  print(env.key2);
  print(env.drink); // "Coffee"
}

Configuration

The Envystic annotation supports the following optional parameters:

• path: The path to the environment variables file. By default, it is set to .env'.
• keyFormat: Specifies the format of key names in the environment file (e.g., .env). Defaults to [KeyFormat.none].

EnvysticAll Annotation

The EnvysticAll annotation provides an automatic way to load all keys from the environment file without the need to specify them individually using getters.

Example:

import 'package:envystic/envystic.dart';

part 'env_all.g.dart';

@EnvysticAll(path: '.env.example')
class EnvAll extends _$EnvAll {
  const Env({super.encryptionKey});

  @override
  @EnvysticField(
      name:
          'MY_SPECIAL_KEY') // This will be pulled from System environment variables if not exists in .env.example
  int? get specialKey;
}

void main() {
  final envAll = EnvAll(encryptionKey: encryptionKey);
  // Access all loaded environment variables
  print(envAll.specialKey); 
  print(envAll.key1);
  print(envAll.key2);
  print(envAll.foo);
  print(envAll.bar);
  ...
}

It is recommended to use the @Envystic annotation instead of @EnvysticAll. Using @Envystic allows you to specify only the fields needed, reducing class overload and ensuring better maintainability.

Encryption

Envystic provides a simple yet effective way to enhance the security of your dotenv values through encryption. By default, if no encryption is applied, Envystic will use base64 encoding to provide a basic level of protection for your sensitive data.

To activate encryption for your dotenv values, you can follow either of these methods:

Method 1: Via build.yaml

1. Open your build.yaml file or create one.
2. Locate the targets section and look for the $default target.
3. Under the $default target, find or add the envystic_generator|envystic builder and modify the options as follows:

targets:
  $default:
    builders:
      envystic_generator|envystic:
        options:
          # Choose the desired format for the keys: none, kebab, snake, pascal, or screamingSnake
          key_format: screamingSnake
          # Determine whether to generate the encryption_key_output if it doesn't already exist
          # Set this to true to enable generation of the encryption key for dotenv values.
          generate_encryption: true
          # `encryption_key_output` File path to use and save the encryption key.
          # If `generate_encryption` is true and `encryption_key_output` is not set, the default
          # value 'env_encryption.key' will be used.
          # Comment out the line below and set generate_encryption to false
          # to exclude encryption from dotenv values.
          encryption_key_output: env_encryption_output.key

Method 2: Via Command Line

1. Open your terminal or command prompt.
2. Use the following command to build your project while enabling encryption:

dart run build_runner build --define envystic_generator:envystic=generate_encryption=true --define envystic_generator:envystic=encryption_key_output=env_encryption_output.key

This command will generate the encryption key and store it in the file specified as encryption_key_output (in this example, env_encryption_output.key).

Alternatively, if you want to use the default output file name (env_encryption.key), you can omit the encryption_key_output parameter:

dart run build_runner build --define envystic_generator:envystic=generate_encryption=true

Methods

T get<T>(String envKey)

Retrieves the value associated with the given envKey from the loaded environment entries. The type of the returned value is inferred based on the actual field type.

Example:

final myValue = env.get<int>('MY_SPECIAL_KEY');

In this example, MY_SPECIAL_KEY is retrieved from the loaded environment entries as specified: integer. If the key does not exist or the value cannot be cast to the specified type, this method will throw an exception.

T? tryGet<T>(String envKey)

Tries to retrieve the value associated with the given envKey from the loaded environment entries. If the key does not exist or the value cannot be cast to the specified type, this method will return null instead of throwing an exception.

T getForField<T>(String fieldName)

Retrieves the value associated with the given fieldName from the loaded environment entries. The type of the returned value is inferred based on the specified generic type T.

Throws an exception if the fieldName does not exist in the loaded environment entries or if the value cannot be cast to the specified type T.

Example:

final myValue = env.getForField<int>('specialKey');

bool isKeyExists(String envKey)

Checks if the provided envKey exists in the loaded environment keys. Returns true if the key exists, false otherwise.

String? getFieldName(String envKey)

Gets the field name associated with the provided envKey. If the envKey exists, returns the corresponding field name; otherwise, returns null.

Author

itisnajim, [e-mail]

License

Envystic is available under the MIT license. See the LICENSE file for more info.