Externals

Non-modular libraries or standalone applications that cannot be bundled normally can be included in a Dojo application by providing an implementation of require or define when needed, and some configuration in the project’s .dojorc file.

Configuration for external dependencies can be provided under the externals property of the build-app config. externals is an object with two allowed properties:

  • outputPath: An optional property specifying an output path to which files should be copied.
  • dependencies: A required array that defines which modules should be loaded via the external loader, and what files should be included in the build. Each entry can be one of two types:
    • A string that indicates that this path, and any children of this path, should be loaded via the external loader.
    • An object that provides additional configuration for dependencies that need to be copied into the built application. This object has the following properties:
PropertyTypeOptionalDescription
fromstringNoA path relative to the root of the project specifying the location of the files or folders to copy into the build application.
tostringYesA path that replaces from as the location to copy this dependency to. By default, dependencies will be copied to ${externalsOutputPath}/${to} or ${externalsOutputPath}/${from} if to is not specified. If there are any . characters in the path and it is a directory, it needs to end with a forward slash.
namestringYesEither the module id or the name of the global variable referenced in the application source.
injectstring, string[], or booleanYesThis property indicates that this dependency defines, or includes, scripts or stylesheets that should be loaded on the page. If inject is set to true, then the file at the location specified by to or from will be loaded on the page. If this dependency is a folder, then inject can be set to a string or array of strings to define one or more files to inject. Each path in inject should be relative to ${externalsOutputPath}/${to} or ${externalsOutputPath}/${from} depending on whether to was provided.
type‘root’ or ‘umd’ or ‘amd’ or ‘commonjs’ or ‘commonjs2’YesForce this module to a specific method of resolution. For AMD style require use umd or amd. For node style require use commonjs, and to access the object as a global use root

As an example the following configuration will inject src/legacy/layer.js into the application page, inject the file that defines the MyGlobal global variable, declare that modules a and b are external and should be delegated to the external layer, and then copy the folder node_modules/legacy-dep, from which several files are injected. All of these files will be copied into the externals folder, which could be overridden by specifying the outputPath property in the externals configuration.

  1. {
  2.     "build-app": {
  3.         "externals": {
  4.             "dependencies": [
  5.                 "a",
  6.                 "b",
  7.                 {
  8.                     "from": "node_modules/GlobalLibrary.js",
  9.                     "to": "GlobalLibrary.js",
  10.                     "name": "MyGlobal",
  11.                     "inject": true
  12.                 },
  13.                 { "from": "src/legacy/layer.js", "to": "legacy/layer.js", "inject": true },
  14.                 {
  15.                     "from": "node_modules/legacy-dep",
  16.                     "to": "legacy-dep/",
  17.                     "inject": ["moduleA/layer.js", "moduleA/layer.css", "moduleB/layer.js"]
  18.                 }
  19.             ]
  20.         }
  21.     }
  22. }

Types for any dependencies included in externals can be installed in node_modules/@types, like any other dependency.

Because these files are external to the main build, no versioning or hashing will be performed on files in a production build, with the exception of the links to any injected assets. The to property can be used to specify a versioned directory to copy dependencies to in order to avoid different versions of files being cached.