Including foreign scripts in the build

What are "foreign scripts"?

Foreign scripts are files containing javascript source code that is not based on (makes no use of) the AngularJS framework.
These are usually source code files for additional libraries/frameworks used by your application (ex. jQuery).
As this kind of javascript code is not structured around Angular modules, dependency resolution must be performed by some other means.

Angular Builder is not able to process CommonJS, AMD or ES6 module references. You must use script references if you want the builder to track this kind of files.

Why is foreign scripts processing included in the builder?

So that you can include in your build only the non-angular-based javascript library files that are actually required by your application (i.e. scripts referenced from unused modules are not included).

Requiring scripts

To declare a dependency between your module and one or more javascript libraries, include one (or more) require build-directives in your application's javascript source files (NOT on the libraries themselves).

A single script:

//# require ("script/path/and/filename.js")

You can use any extension you want for foreign scripts (ex: .js, .es6).

Multiple scripts

//# require ("path1/filename1.js", "../path2/filename2.js")

You can also use multiple require references.

Glob patterns

//# require ('path/**/*.js')

How it works

Whenever a module is included in a build, all require build-directives present in any of the files that comprise the module are processed and the required script paths are recorded.

This means that each individual source file may specify its script requirements.

Duplicate require directives are ignored, so each script is included only once.

The specified path should be a relative path (not starting with /); it will be relative to the file containing the directive.

Handling the required scrips

All required script paths are appended to a list of "forcibly included" scripts (see also the require Grunt task configuration option). These files will be included in the build output before angular-based script files.

If any of those scripts is not pure javascript code (ex. CoffeeScript, TypeScript, etc.) the build-directive must reference the compiled javascript file, not the original source code file.

You may compile non-javascript source files in a task that runs before the Angular Builder's task.

The list of scripts is sorted by the order in which they are required and takes into consideration the interconnected dependencies of your source code.

Scrips that are required by scripts that are not included in the build (i.e. not part of the dependency graph of your application) will be ignored.

Examples

See Configuration Examples.