Limitations

There is no built-in support for foreign module systems

Summary

Only AngularJS module references are natively supported. Angular Builder is not able to process CommonJS, AMD or ES6 module references.

Explanation

Not needing to use those module systems in the first place IS the main purpose of this project, so this shouldn't come as a surprise! ;-)

Using a foreign module system in your application's source files is not needed nor recommended. Angular Builder will still determine which files need to be included in the build, and in which order, even if you use alien module import declarations.

So you should rarely have a problem with this "limitation"; in a normal build scenario, foreign module references should only be used internally by external / third-party libraries of your project (because the respective authors did not use Angular Builder for their projects), so you can always include those libraries in the build process as pre-built single-file sources, which do not need to be assembled by Angular Builder.

If, for some reason, your project's source files are not being built correctly due to the use of non-angular module imports/declarations, you can take full control of the build process and make the builder track that kind of file dependencies using script references.

You shouldn't define multiple modules in a single file.

Summary

You can split a module into as many files as needed, but you should't mix modules in the same file.
Although you can do it, it is not recommended, as it hampers the builder's ability to optimize the source code.

Explanation

When multiple modules are intertwined in a single file, there is usually some code that is common to several modules and it would be very hard for the builder to find out which code belongs to each module and split it when and where necessary.

As such, when one of the modules declared in the same file is required by the application, all the remaining modules will be declared too, as it is not feasible to split the file.

This will cause the inclusion in the build of declarations that will not be used by the application, therefore reducing the effectiveness of the building process.

In some cases, the build may even fail.

Note

Some library authors (ex: ui-router) like to declare all modules in a single file and then add definitions to them in additional files.

Many of these libraries can be built successfully, but it is best if you avoid doing that in your own code.

You shouldn't try to build pre-built concatenated library files.

Summary

Don't include *.min.js files in your build process. Use the original source files instead, if possible. Otherwise, read below.

Explanation

If you are trying to include a single-file library into your build process, chances are it is a release-optimized file that is already built by some other means.

Possible solutions:

1. Use the library's original source code files (the non-minified, non-concatenated ones).

2. Exclude it from the build process, mark it as an external module and either load it separately into your application (ex. using a script tag) or use an additional Grunt task to concatenate (and/or minify) it into the final build file.

3. Have angular-builder include it in the build as a black-box script file, by using:

   1. the #require directive,
   2. the require configuration option, or
   3. the forceInclude extra file group property.

   Angular-builder will include the file before your application's code, but will not try to parse it.

The builder can't build AngularJS itself!

Summary

Don't include angular.js or angular.min.js in your build.

Explanation

Angular-builder can't (and shouldn't) build the Angular framework. Load it independently before your app code or have the builder include it via one the options mentioned above.

Angular-builder is unable to parse files that are not written in standard javascript.

If you want to build code written in Coffeescript, Typescript, Dart or any other language that compiles to javascript, you must previously compile the files into a different folder and build from that folder (also put javascript third-party libraries there).

Write your code freely, but with some rules.

Summary

If Angular Builder starts complaining about your code, read writing build enabled code.

Explanation

You should have in mind that some javascript code is not "build friendly". It would be a major challenge for Angular Builder to support all the myriad ways code can be structured by other people.

Just like AMD or CommonJS require the developer to follow some rules, angular-builder also imposes some simple rules, so that it can efficiently parse your source code.

On the Wiki you'll find a page about writing build enabled code.
As long as you follow those rules, your application or library will build just fine.

Some third-party libraries may be incompatible with the builder.

Read Compatible libraries.