# Build Errors
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
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
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.
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.dartcode (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
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
@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.
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
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).