ezFlap

# Build Errors

# Overview

When ezFlap generates Dart code based on our ZML, ZSS, and annotations - it may occasionally run into problems.

For example, if the ZML uses a widget whose library is not imported into the ezFlap widget file - ezFlap will not be able to generate the necessary code correctly.

When ezFlap encounters a problem - it logs it into the console (the console where we run the flutter pub run build_runner watch command).

In most cases, when encountering errors, ezFlap will try to generate some code with correct Dart syntax, to make it easy for us to examine it in the generated .g.dart file.

Additionally, ezFlap will try to proceed with the build, so that if there are additional errors - we will see them all together.

In rare cases, when encountering errors, ezFlap may generate Dart code with incorrect syntax. If that happens, the .g.dart file will be created with the invalid code generated by ezFlap.

Normally, dartfmt is used on .g.dart files automatically when they are generated, as part of the normal build process (this is part of the Dart code generation infrastructure).

However, when the .g.dart file contains syntax errors - dartfmt cannot format it.

When that happens, because of the way the code generator works, the .g.dart file will look messy, with many redundant tabs, spaces, and newlines. This is an expected behavior, and once the cause for the syntax errors is resolved - the .g.dart file will be re-generated and properly formatted.

When we encounter this situation, we can:

  • Look for hints in the build console (i.e. look for ezFlap logged errors or warnings).
  • Review the errors in the .g.dart code (the IDE should mark them for us) to get an idea of what part of the ZML caused this.

Another technique is to delete snippets of the ZML, save the file, and see if it builds correctly. Once it does - we restore the deleted snippet and iteratively delete smaller and smaller snippets of code - until we zero in on the problematic tag or attribute.

# Check the Console

When ezFlap encounters errors, it will almost always succeed to generate syntactically-correct Dart code, but this code will contain other errors (e.g. such as usages of missing fields or methods), and will usually not work (or even compile).

It is generally a good idea to keep an eye out for warnings and errors in the build console, but even more so when we see errors in generated (and sometimes also non-generated) code.

# Common Errors

In this section we list several common mistakes that lead to errors.

# Missing or Incorrect part Directive

Every ezFlap widget file, service file, reactive entity file, or any other file that contains classes for which code needs to be generated must start with a part '<file name>.g.dart'; directive.

If this directive is missing, or if the actual name of the file is different from the name provided to part - then no code will be generated and no errors will be logged in the build console.

# Missing Class Annotation

The State class of every ezFlap widget needs to have the @EzWidget annotation.

Services need @EzService, JSON classes need @EzJson, and so on.

If the class annotation is missing - no code will be generated, and no errors will be logged in the build console.

# Wrong createState() Return Type

The return type of the createState() method of the widget class that extends EzStatefulWidgetBase must be the widget state class.

If you use a different type (e.g. State) - in some scenarios ezFlap will fail to generate code that uses that widget.

# Missing Import

The library of every widget referenced from inside the ZML or ZSS needs to be imported into the ezFlap widget file.

# Nullability in ZML

Various ZML attributes and text interpolations accept Dart expressions.

Dart's nullability rules are applied within these expressions.

For example, when accessing a nullable field - we may need to use the ? and ! operators.

If we get it wrong - ezFlap won't detect it, and we will eventually get warnings or errors from the Dart compiler.

# Missing Last-Tag in ZSS Selector

Unlike CSS selectors, the last part of the ZSS selector must contain a tag name.

For example, this selector is valid: Column.top .pink Container Text.bold.italic.

But this selector is not: Column.top .pink Container .bold.italic.

# ezFlap Bugs

If you encounter an ezFlap bug, like:

  • The ZML, ZSS, and code are all valid - but ezFlap doesn't generate code for the widget.
  • ezFlap generates code that doesn't compile.
  • The generated code compiles, but its behavior is different from what you would expect based on this guide.

Then please create a small (minimal, if possible) reproducible example, and submit an issue in Github (opens new window).

← Code of Conduct →