About

A builder that can be used to embed assets into your Dart or Flutter project.

🛠️ Getting started

Add build_runner and asset_bundle_generator as a development dependency to your project:

dart pub add --dev build_runner asset_bundle_generator

Create a build.yaml in the root of your project and paste the following content into it. If you already have a build.yaml file, then your only need to adjust your sources and add asset_bundle_generator as a new builder.

targets:
  $default:
    sources:
      - $package$
      - lib/**

      # Need to provide all files in `assets/` as a source to the builders,
      # otherwise asset_bundle_generator cannot see any included files like
      # `assets/file.txt`.
      - assets/**

    builders:
      asset_bundle_generator:
        options:
          # The path to the output directory for all generated files and
          # directories.
          #
          # Defaults to `lib/src/asset_bundle`.
          output: lib/assets

          # An array of [Glob Patterns](https://github.com/begin/globbing) that
          # define for which files an asset should be generated.
          #
          # Defaults to an empty array.
          include:
            # Includes all files in `assets/configs` and all its subdirectories.
            - assets/configs/**

            # Includes a single file.
            - assets/file.txt

          # An array of [Glob Patterns](https://github.com/begin/globbing) that
          # define for which files **no asset** should be generated.
          #
          # Defaults to an empty array.
          exclude:
            # Exclude a single file from the `assets/configs/` directory.
            - assets/configs/device.conf

          # Determines when the assets should be generated (or regenerated).
          #
          # Possible values include:
          #
          #   * always
          #
          #     Always recreate the generated asset files.
          #
          #   * onlyMissing
          #
          #     Only create the missing asset files.
          #
          #   * onlyMissingAndMismatchedHashes
          #
          #     Only create the missing asset files and the ones where the
          #     SHA256 in the generated file does not match the SHA256
          #     of the actual asset.
          #
          # Defaults to `onlyMissingAndMismatchedHashes`.
          creation_mode: always

          # Configure how the dartdoc preview comments should be generated.
          preview:
            # Whether or not the preview comments should be included at all.
            #
            # Defaults to true.
            include: true

            # Whether or not the file type of the asset should be guessed, so
            # that the dartdoc comment can have an explicit type.
            #
            # Defaults to true.
            #guess_type: false
            
            # The maximum size in bytes of an asset for which a dartdoc comment
            # should still be generated. If the asset exceeds the max size then
            # no comment will be generated.
            #
            # Defaults to 10 KB.
            #max_file_size: 10

          # How assets should be named in the generated Dart code.
          rename:
            # A regular expression that is used to convert filenames into
            # strings that can be used as a valid identifier in Dart.
            #
            # The value of the first capture group is used for the identifier.
            #
            # Defaults to `"\s*\.?\s*(\S+)\s*"`.
            #sanitizer: ...
            
            # A regular expression that determines how to split the identifier
            # that was captured by `sanitizer` into words.
            # 
            # Defaults to `"[\._-]"`.
            #split: ""

          utility:
            # If `true` the getter `Asset.text`, which decodes `Asset.data` into
            # UTF-8, replaces invalid (or unterminated) character sequences with
            # the Unicode Replacement character # `U+FFFD` (�).
            # Otherwise a `FormatException` is thrown..
            #
            # Defaults to true.
            allow_malformed_utf8: false

Now you can build 🏗️ your assets with:

dart run build_runner build

The generated files will be put into lib/assets (the value configured for output).