dart_define

https://pub.dev/documentation/dart_define/latest/
Admin
dart_define is an all-in-one tool for managing secrets and launch configurations in Flutter and Dart...
Tokens:2,476
Snippets:32
Trust Score:9.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install dart_define CLI Tool

Source: https://pub.dev/documentation/dart_define/latest/index

Installs the dart_define command-line interface globally. This allows direct execution of `dart_define` commands without needing `pub run`.

```bash
dart pub global activate dart_define
```

--------------------------------

### Configure Flavors in pubspec.yaml

Source: https://pub.dev/documentation/dart_define/latest/packages/dart_define

Define application variables and flavors within the pubspec.yaml file using dart_define. This setup allows for multiple configurations for different environments or white labels.

```yaml
dart_define:
    variables: 
        - name: APP_NAME 
          description: The apps name
          default: My App
          required: false 
        - name: APP_ID
          description: The apps unique id
          default: com.my.app
          required: false
    flavors: 
        - name: production 
          description: The production flavor 
        - name: staging
          description: The staging flavor
        - name: development
          description: The development flavor  

```

--------------------------------

### Dart Enum for Flavors

Source: https://pub.dev/documentation/dart_define/latest/packages/dart_define

An example of a Dart enum automatically generated by dart_define, which represents the available flavors. The current flavor can be accessed via DartDefine.flavor.

```dart
/// `dart_define` generates this enum based on the flavors in your configurations
/// You can access the current flavor used to launch the application by calling
/// DartDefine.flavor
enum Flavor {
    /// The production flavor
    production,

    /// The staging flavor
    staging,

    /// The development flavor
    development,
}

```

--------------------------------

### Building Flutter app with dart_define configuration

Source: https://pub.dev/documentation/dart_define/latest/index

Commands to build Android (APK) and iOS applications using the configurations provided by dart_define.

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

--------------------------------

### Run Flutter App with Flavor Configuration

Source: https://pub.dev/documentation/dart_define/latest/packages/dart_define

Command to run a Flutter application using a specific flavor configuration file. This ensures the app launches with the correct settings for the chosen environment.

```bash
flutter run --dart-define-from-file=config/development.json

```

--------------------------------

### Running Flutter app with a specific flavor configuration

Source: https://pub.dev/documentation/dart_define/latest/index

Demonstrates how to launch a Flutter application using a flavor-specific configuration file.

```bash
flutter run --dart-define-from-file=config/development.json
```

--------------------------------

### CI/CD Pipeline: Running Generator

Source: https://pub.dev/documentation/dart_define/latest/packages/dart_define

Commands to execute the `dart_define` generator within a CI/CD environment. It includes options for running as a dev dependency or a globally activated CLI tool, and emphasizes the use of the `--force` flag when caching is involved.

```bash
# 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
```

--------------------------------

### Generate Flavor Configuration JSON Files

Source: https://pub.dev/documentation/dart_define/latest/packages/dart_define

Command-line interface (CLI) commands to generate JSON configuration files for each defined flavor. These files are used by dart_define to load flavor-specific settings.

```bash
dart_define generate --json_path=config/production.json --FLAVOR=production
dart_define generate --json_path=config/staging.json --FLAVOR=staging
dart_define generate --json_path=config/development.json --FLAVOR=development

```

--------------------------------

### Using dart_define variables in iOS configuration

Source: https://pub.dev/documentation/dart_define/latest/index

Shows how environment variables are referenced in iOS configuration files.

```text
$(STRING_VALUE)
```

--------------------------------

### Running Flutter app with dart_define configuration

Source: https://pub.dev/documentation/dart_define/latest/index

This command executes a Flutter application using a generated JSON configuration file, allowing environment-specific variables to be applied.

```bash
flutter run --dart-define-from-file=dart_define.json
```

--------------------------------

### Using a custom YAML configuration path

Source: https://pub.dev/documentation/dart_define/latest/index

Explains how to specify a custom path for the `dart_define` configuration file using the `--yaml_path` flag.

```bash
# Example usage (assuming a custom path like 'my_config/pubspec.yaml')
# dart_define generate --yaml_path=my_config/pubspec.yaml
```

--------------------------------

### Generate Boilerplate with Dart Define CLI

Source: https://pub.dev/documentation/dart_define/latest/packages/dart_define

Initiates the generation of configuration boilerplate files. This command reads settings from `pubspec.yaml` to create files necessary for accessing defined variables.

```bash
dart_define generate
```

--------------------------------

### Configuring dart_define flavors in pubspec.yaml

Source: https://pub.dev/documentation/dart_define/latest/index

Defines variables and flavors within the `pubspec.yaml` file for managing multiple environment configurations.

```yaml
dart_define:
    variables: 
        - name: APP_NAME 
          description: The apps name
          default: My App
          required: false 
        - name: APP_ID
          description: The apps unique id
          default: com.my.app
          required: false
    flavors: 
        - name: production 
          description: The production flavor 
        - name: staging
          description: The staging flavor
        - name: development
          description: The development flavor  
```

--------------------------------

### Generating dart_define configuration for specific flavors

Source: https://pub.dev/documentation/dart_define/latest/index

Generates configuration files for each defined flavor, specifying the output JSON path and the flavor name.

```bash
dart_define generate --json_path=config/production.json --FLAVOR=production
dart_define generate --json_path=config/staging.json --FLAVOR=staging
dart_define generate --json_path=config/development.json --FLAVOR=development
```

--------------------------------

### Dart enum for flavors

Source: https://pub.dev/documentation/dart_define/latest/index

Illustrates how the tool can generate a Dart enum representing the configured flavors, allowing runtime access to the current flavor.

```dart
/// `dart_define` generates this enum based on the flavors in your configurations
/// You can access the current flavor used to launch the application by calling
/// DartDefine.flavor
enum Flavor {
    /// The production flavor
    production,

    /// The staging flavor
    staging,

    /// The development flavor
    development,
}
```

--------------------------------

### Generating dart_define with specific variables

Source: https://pub.dev/documentation/dart_define/latest/index

Allows generation of the configuration file while overriding default or environment variables directly via CLI arguments. The `--force` flag is recommended for CI/CD to ensure updates.

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

--------------------------------

### Configure dart_define in pubspec.yaml

Source: https://pub.dev/documentation/dart_define/latest/index

Defines application variables, their types, default values, and whether they are required within the `pubspec.yaml` file. It also allows configuration of generated file paths and class names, and defines application flavors.

```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 

    # OPTIONAL: The path to the json file to generate. 
    # Defaults to dart_define.json
    json_path: dart_define.json 
       
    # OPTIONAL: The path to the dart file to generate. 
    # Defaults to lib/dart_define.gen.dart
    dart_path: lib/dart_define.gen.dart 
       
    # OPTIONAL: The name of the generated class. 
    # Defaults to dart_define
    class_name: dart_define 

    # 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

    # OPTIONAL: The flavors to use within the app
    flavors:

          # REQUIRED: The name of the flavor
        - name: production 

          # REQUIRED: The description of the flavor
          description: The production flavor 
        - name: staging
          description: The staging flavor
        - name: development
          description: The development flavor

```

--------------------------------

### Define Variables in pubspec.yaml

Source: https://pub.dev/documentation/dart_define/latest/packages/dart_define

Configure your application's variables, including types, defaults, and requirements, within the `pubspec.yaml` file. This section also allows specifying paths for generated files, class names, and application flavors.

```yaml
dart_define:
    dart: true
    json: true
    json_path: dart_define.json 
    dart_path: lib/dart_define.gen.dart 
    class_name: dart_define 
    variables:
        - name: STRING_VALUE 
          description: An example String value 
          default: hello world!
          required: false 
        - name: INT_VALUE
          description: An example int value
          default: 3
          required: false
        - name: BOOL_VALUE
          description: An example bool value
          required: true
    flavors:
        - name: production 
          description: The production flavor 
        - name: staging
          description: The staging flavor
        - name: development
          description: The development flavor
```

--------------------------------

### Add dart_define to Project Dependencies

Source: https://pub.dev/documentation/dart_define/latest/index

Adds the dart_define package as a development dependency to your Flutter or Dart project. This method requires prefixing `dart_define` commands with `pub run`.

```bash
flutter pub add --dev dart_define
```

--------------------------------

### Generate dart_define configuration

Source: https://pub.dev/documentation/dart_define/latest/index

This command generates a JSON configuration file for dart_define. It can be run via the Dart CLI or as a global CLI tool. Environment variables can be overridden via CLI arguments.

```bash
dart pub global activate dart_define
dart_define generate
```

```bash
dart run dart_define generate
```

--------------------------------

### Using dart_define variables in Android build.gradle

Source: https://pub.dev/documentation/dart_define/latest/index

Configuration values can be injected into the Android build process, making them available in native resources like `AndroidManifest.xml`.

```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
}
```

--------------------------------

### Using dart_define variables in AndroidManifest.xml

Source: https://pub.dev/documentation/dart_define/latest/index

Defines how to use injected string values within the AndroidManifest.xml file.

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

--------------------------------

### Accessing dart_define variables in Dart code

Source: https://pub.dev/documentation/dart_define/latest/index

The tool generates Dart boilerplate code to easily access environment variables defined in the configuration. These static constants are initialized using `String.fromEnvironment`.

```dart
/// 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;
```
Tokens:
Raw