dart_define 1.0.3

Utility for generating and populating dart-define config files

dart_define

Motivation 🔥

dart_define is an all-in-one tool to handle secrets and launch configurations both locally and in CI/CD pipelines super easily. Say goodbye to .env files or any other tedious and error-prone ways. With this package you can access your secrets in dart code as well as platform specific configurations.

Flutter supports adding compile-time variables with --dart-define option, and using them in both dart code and native configurations. However, with many variables, the commands become quite long quite fast. A workaround for that would be to create a custom launch shell scripts, or storing variables in a JSON file and using it with --dart-define-from-file option.

Hovewer, that raises a ton of other issues within CI/CD pipelines. You'd have to gitignore the launch config files, so you don't leak any secrets unwantedly. Then you'd have to create some custom script to initialize and fill those files with proper values in your CI/CD environments. Even after working your way around those issues, you'd have to be very careful to always remember update those pipelines when new values are added (missing values are not recognized at compile-time, leading to possible run-time errors in production).

With dart_define, you'll get easy ways of handling secrets and configurations in both local development environment as well as CI/CD pipelines. You can specify which variables are required, so the CLI tool will throw an exception if those are missing. This way missing values will result in failed pipeline run, not run-time error in production.

When the generator is run, dart_define reads the values from

1. CLI option override

   You can override values from system environment or yaml config defaults with CLI options, like so --MY_VARIABLE=MY_VALUE

2. System environment

   dart_define tries to read values from system environment for smooth integration with CI/CD pipelines

3. Default values

   You can specify default values within pubspec.yaml configuration, which will be used as fallback values if none of the above are provided. Note that if required is true (default), the generator will fail if 1 or 2 are not provided and the default value will be ignored.

Quick Start 🚀

1. Install the CLI tool, OR add it into dependencies

   # activate the CLI tool
   dart pub global activate dart_define
   

   OR

   # add the tool to dependencies
   flutter pub add --dev dart_define
   

2. Define your variables in pubspec.yaml

   dart_define:
   
       # OPTIONAL: Whether to generate the dart boilerplate or not. 
       # Defaults to true
       dart: true 
   
       # OPTIONAL: Whether to generate the json boilerplate or not. 
       # Defaults to true
       json: true 
   
       # REQUIRED: The variables to add to the generated config files
       variables: 
   
             # REQUIRED: The name of the variable
           - name: STRING_VALUE 
   
             # REQUIRED: The description of the variable
             description: An example String value 
   
             # REQUIRED: If `required` is false, this field is mandatory. 
             # Otherwise, it is ignored.
             default: hello world! 
   
             # OPTIONAL: If this is set to true, the CLI tool will 
             # throw an exception if the variable is not provided 
             # as an argument. This is handy when using the tool
             # in CI/CD pipelines.
             # Defaults to true.
             required: false 
           - name: INT_VALUE
             description: An example int value
             default: 3
             required: false
           - name: BOOL_VALUE
             description: An example bool value
             required: true
   

3. Generate boilerplate

   # If you activated the CLI tool
   dart_define generate
   

   OR

   # If you added the tool to dependencies
   dart run dart_define generate
   

   NOTE: You can override values and variables from pubspec.yaml config with CLI arguments

   NOTE: This will generate a json file with the given secretes / configurations. It is recommended to gitignore that file.

   

Using the configuration ⚙️

1. Use your variables in dart code

   This tool generates dart boilerplate, so you can access the values very easily.

    /// This is the code this tool creates
    class DartDefine {
        /// An example String value
        static const stringValue = String.fromEnvironment('STRING_VALUE');
   
        /// An example int value
        static const intValue = int.fromEnvironment('INT_VALUE');
   
        /// An example bool value
        static const boolValue = bool.fromEnvironment('BOOL_VALUE');
    }
   
    /// With this you can access the variables like so:
    String testValue = DartDefine.stringValue;
   

2. Access the values in platforms native configurations (see this article)

   Within android build.gradle

   // In app/build.gradle
   defaultConfig {
       applicationId STRING_VALUE
   
       // This allows us to access the value in eg. AndroidManifest.xml
       resValue "string", "STRING_VALUE", STRING_VALUE
   }
   

   Within AndroidManifest.xml

   <manifest xmlns:android="http://schemas.android.com/apk/res/android"
       package="@string/STRING_VALUE">
   </manifest>
   

   Within iOS config files

   $(STRING_VALUE)
   

3. Run the app from the configuration file

   flutter run --dart-define-from-file=dart_define.json✓
   

Configuring CI/CD pipeline ✔️

dart_define is designed to integrate smoothly into your CI/CD pipelines.

1. Add variables to pipelines secrets

   Since dart_define reads the values from environment secrets, you don't have to reference the variables later on. All you've got to do is to add them to the environments secrets!

2. Run the generator

   # If you have dart_define as (dev) dependecy, simply run
   dart run dart_define generate
   
   # If you activated dart_define as CLI tool locally
   dart pub global activate dart_define
   dart_define generate
   

   Alternatively, you can also specify the variables when running the command. This way you can fetch them from wherever you want.

   dart run dart_define generate --BOOL_VALUE=${BOOL_VALUE} --STRING_VALUE=${STRING_VALUE} --INT_VALUE=${INT_VALUE}
   

3. Use the configuration in the actual build commands

   flutter build apk --dart-define-from-file=dart_define.json
   flutter build ios --dart-define-from-file=dart_define.json