/flutter_gen

The Flutter code generator for your assets, fonts, colors, … — Get rid of all String-based APIs.

Primary LanguageDartMIT LicenseMIT

The Flutter code generator for your assets, fonts, colors, … — Get rid of all String-based APIs.

Inspired by SwiftGen.

Motivation

Using asset path string directly is not safe.

# pubspec.yaml
flutter:
  assets:
    - assets/images/profile.jpg

❌ Bad
What would happen if you made a typo?

Widget build(BuildContext context) {
  return Image.asset('assets/images/profile.jpeg');
}

// The following assertion was thrown resolving an image codec:
// Unable to load asset: assets/images/profile.jpeg

⭕️ Good
We want to use it safely.

Widget build(BuildContext context) {
  return Assets.images.profile.image();
}

Installation

Homebrew

Works with macOS and Linux.

$ brew install FlutterGen/tap/fluttergen

Pub Global

Works with macOS, Linux and Windows.

$ dart pub global activate flutter_gen

You might need to set up your path.

As a part of build_runner

  1. Add build_runner and FlutterGen to your package's pubspec.yaml file:
dev_dependencies:
  build_runner:
  flutter_gen_runner:
  1. Install FlutterGen
$ flutter pub get
  1. Use FlutterGen
$ flutter packages pub run build_runner build

Usage

Run fluttergen after the configuration pubspec.yaml.

$ fluttergen -h

$ fluttergen -c example/pubspec.yaml

Configuration file

FlutterGen generates dart files based on the key flutter and flutter_gen of pubspec.yaml.
Default configuration can be found here.

# pubspec.yaml
# ...

flutter_gen:
  output: lib/gen/ # Optional (default: lib/gen/)
  line_length: 80 # Optional (default: 80)

  # Optional
  integrations:
    flutter_svg: true
    flare_flutter: true
    rive: true
    lottie: true

  colors:
    inputs:
      - assets/color/colors.xml

flutter:
  uses-material-design: true
  assets:
    - assets/images/

  fonts:
    - family: Raleway
      fonts:
        - asset: assets/fonts/Raleway-Regular.ttf
        - asset: assets/fonts/Raleway-Italic.ttf
          style: italic

Available Parsers

Assets

Just follow the doc Adding assets and images#Specifying assets to specify assets, then FlutterGen will generate related dart files.
No other specific configuration is required.
Ignore duplicated.

# pubspec.yaml
flutter:
  assets:
    - assets/images/
    - assets/images/chip3/chip.jpg
    - assets/images/chip4/chip.jpg
    - assets/images/icons/paint.svg
    - assets/images/icons/dart@test.svg
    - assets/json/fruits.json
    - assets/flare/Penguin.flr
    - assets/rive/vehicles.riv
    - pictures/ocean_view.jpg

These configurations will generate assets.gen.dart under the lib/gen/ directory by default.

Usage Example

FlutterGen generates Image class if the asset is Flutter supported image format.

Example results of assets/images/chip.jpg:

  • Assets.images.chip is an implementation of AssetImage class.
  • Assets.images.chip.image(...) returns Image class.
  • Assets.images.chip.provider(...) returns ImageProvider class.
  • Assets.images.chip.path just returns the path string.
  • Assets.images.chip.values just returns the values list.
Widget build(BuildContext context) {
  return Assets.images.chip.image();
}

Widget build(BuildContext context) {
  return Assets.images.chip.image(
    width: 120,
    height: 120,
    fit: BoxFit.scaleDown,
  );

Widget build(BuildContext context) {
  // Assets.images.chip.path = 'assets/images/chip3/chip3.jpg'
  return Image.asset(Assets.images.chip.path);
}

If you are using SVG images with flutter_svg you can use the integration feature.

# pubspec.yaml
flutter_gen:
  integrations:
    flutter_svg: true

flutter:
  assets:
    - assets/images/icons/paint.svg
Widget build(BuildContext context) {
  return Assets.images.icons.paint.svg(
    width: 120,
    height: 120
  );
}

Available Integrations

Packages File extension Setting Usage
flutter_svg .svg flutter_svg: true Assets.images.icons.paint.svg()
flare_flutter .flr flare_flutter: true Assets.flare.penguin.flare()
rive .flr rive: true Assets.rive.vehicles.rive()
lottie .json lottie: true Assets.lottie.hamburgerArrow.lottie()

In other cases, the asset is generated as String class.

// If don't use the Integrations.
final svg = SvgPicture.asset(Assets.images.icons.paint);

final json = await rootBundle.loadString(Assets.json.fruits);

FlutterGen also support generating other style of Assets class:

# pubspec.yaml
flutter_gen:
  assets:
    outputs: 
      # Assets.imagesChip
      # style: camel-case

      # Assets.images_chip
      # style: snake-case

      # Assets.images.chip (default style)
      # style: dot-delimiter

flutter:
  assets:
    - assets/images/chip.png

The root directory will be omitted if it is either assets or asset.

assets/images/chip3/chip.jpg      => Assets.images.chip3.chip
assets/images/chip4/chip.jpg      => Assets.images.chip4.chip
assets/images/icons/paint.svg     => Assets.images.icons.paint
assets/images/icons/dart@test.svg => Assets.images.icons.dartTest
assets/json/fruits.json           => Assets.json.fruits
pictures/ocean_view.jpg           => Assets.pictures.oceanView

Example of code generated by FlutterGen

Fonts

Just follow the doc Use a custom font to specify fonts, then FlutterGen will generate related dart files.
No other specific configuration is required.
Ignore duplicated.

# pubspec.yaml
flutter:
  fonts:
    - family: Raleway
      fonts:
        - asset: assets/fonts/Raleway-Regular.ttf
        - asset: assets/fonts/Raleway-Italic.ttf
          style: italic
    - family: RobotoMono
      fonts:
        - asset: assets/fonts/RobotoMono-Regular.ttf
        - asset: assets/fonts/RobotoMono-Bold.ttf
          weight: 700

These configurations will generate fonts.gen.dart under the lib/gen/ directory by default.

Usage Example

Text(
  'Hi there, I\'m FlutterGen',
  style: TextStyle(
    fontFamily: FontFamily.robotoMono,
    fontFamilyFallback: const [FontFamily.raleway],
  ),

Example of code generated by FlutterGen

Colors

FlutterGen supports generating colors from XML format files.
Ignore duplicated.

# pubspec.yaml
flutter_gen:
  colors:
    inputs:
      - assets/color/colors.xml
      - assets/color/colors2.xml

FlutterGen can generate a Color class based on the name attribute and the color hex value. If the element has the attribute type, then a specially color will be generated.

Currently supported special color types:

Noticed that there is no official material color generation algorithm. The implementation is based on the mcg project.

<color name="milk_tea">#F5CB84</color>
<color name="cinnamon" type="material">#955E1C</color>
<color name="yellow_ocher" type="material material-accent">#DF9527</color>

These configurations will generate colors.gen.dart under the lib/gen/ directory by default.

Usage Example

Text(
  'Hi there, I\'m FlutterGen',
  style: TextStyle(
    color: ColorName.denim,
  ),

Example of code generated by FlutterGen

Credits

The material color generation implementation is based on mcg and TinyColor.

Issues

Please file FlutterGen specific issues, bugs, or feature requests in our issue tracker.

Plugin issues that are not specific to FlutterGen can be filed in the Flutter issue tracker.

Known Issues

Bad State: No Element when using build_runner

If you get an error message like this:

[SEVERE] flutter_gen_runner:flutter_gen_runner on $package$:

Bad state: No element
[SEVERE] Failed after 16.0s

The you most likely have a customized build.yaml to configure the build runner. In that case, all you have to do is to add the pubspec.yaml as build source to your build.yaml

targets:
  $default:
    sources:
      include:
        - pubspec.yaml  # add this line
        - ...

See #268 for the corresponding issue discussion.

Contributing

We are looking for co-developers.

If you wish to contribute a change to any of the existing plugins in this repo, please review our contribution guide and open a pull request.