3.6 goog.require and goog.requireType statements

Imports are done with goog.require and goog.requireType statements. Thenames imported by a goog.require statement may be used both in code and intype annotations, while those imported by a goog.requireType may be usedin type annotations only.

The goog.require and goog.requireType statements form a contiguous blockwith no empty lines. This block follows the goog.module declaration separatedby a single empty line. The entire argument togoog.require or goog.requireType is a namespace defined by a goog.modulein a separate file. goog.require and goog.requireType statements may notappear anywhere else in the file.

Each goog.require or goog.requireType is assigned to a single constantalias, or else destructured into several constant aliases. These aliases are theonly acceptable way to refer to dependencies in type annotations or code. Fullyqualified namespaces must not be used anywhere, except as an argument togoog.require or goog.requireType.

Exception: Types, variables, and functions declared in externs files have touse their fully qualified name in type annotations and code.

Aliases must match the final dot-separated component of the imported module'snamespace.

Exception: In certain cases, additional components of the namespace can beused to form a longer alias. The resulting alias must retain the originalidentifier's casing such that it still correctly identifies its type. Longeraliases may be used to disambiguate otherwise identical aliases, or if itsignificantly improves readability. In addition, a longer alias must be used toprevent masking native types such as Element, Event, Error, Map, andPromise (for a more complete list, see Standard Built-in Objects and WebAPIs at MDN). When renaming destructured aliases, a space must follow the colonas required in ??.

A file should not contain both a goog.require and a goog.requireTypestatement for the same namespace. If the imported name is used both in code andin type annotations, it should be imported by a single goog.require statement.

If a module is imported only for its side effects, the call must be agoog.require (not a goog.requireType) and assignment may be omitted. Acomment is required to explain why this is needed and suppress a compilerwarning.

The lines are sorted according to the following rules: All requires with a nameon the left hand side come first, sorted alphabetically by those names. Thendestructuring requires, again sorted by the names on the left hand side.Finally, any require calls that are standalone (generally these are for modulesimported just for their side effects).

Tip: There’s no need to memorize this order and enforce it manually. You canrely on your IDE to report requiresthat are not sorted correctly.

If a long alias or module name would cause a line to exceed the 80-column limit,it must not be wrapped: require lines are an exception to the 80-columnlimit.

Example:

// Standard alias style.
const MyClass = goog.require('some.package.MyClass');
const MyType = goog.requireType('some.package.MyType');
// Namespace-based alias used to disambiguate.
const NsMyClass = goog.require('other.ns.MyClass');
// Namespace-based alias used to prevent masking native type.
const RendererElement = goog.require('web.renderer.Element');
// Out of sequence namespace-based aliases used to improve readability.
// Also, require lines longer than 80 columns must not be wrapped.
const SomeDataStructureModel = goog.requireType('identical.package.identifiers.models.SomeDataStructure');
const SomeDataStructureProto = goog.require('proto.identical.package.identifiers.SomeDataStructure');
// Standard alias style.
const asserts = goog.require('goog.asserts');
// Namespace-based alias used to disambiguate.
const testingAsserts = goog.require('goog.testing.asserts');
// Standard destructuring into aliases.
const {clear, clone} = goog.require('goog.array');
const {Rgb} = goog.require('goog.color');
// Namespace-based destructuring into aliases in order to disambiguate.
const {SomeType: FooSomeType} = goog.requireType('foo.types');
const {clear: objectClear, clone: objectClone} = goog.require('goog.object');
// goog.require without an alias in order to trigger side effects.
/** @suppress {extraRequire} Initializes MyFramework. */
goog.require('my.framework.initialization');

Discouraged:

// If necessary to disambiguate, prefer PackageClass over SomeClass as it is
// closer to the format of the module name.
const SomeClass = goog.require('some.package.Class');

Disallowed:

// Extra terms must come from the namespace.
const MyClassForBizzing = goog.require('some.package.MyClass');
// Alias must include the entire final namespace component.
const MyClass = goog.require('some.package.MyClassForBizzing');
// Alias must not mask native type (should be `const JspbMap` here).
const Map = goog.require('jspb.Map');
// Don't break goog.require lines over 80 columns.
const SomeDataStructure =
    goog.require('proto.identical.package.identifiers.SomeDataStructure');
// Alias must be based on the namespace.
const randomName = goog.require('something.else');
// Missing a space after the colon.
const {Foo:FooProto} = goog.require('some.package.proto.Foo');
// goog.requireType without an alias.
goog.requireType('some.package.with.a.Type');
/**
 * @param {!some.unimported.Dependency} param All external types used in JSDoc
 *     annotations must be goog.require'd, unless declared in externs.
 */
function someFunction(param) {
  // goog.require lines must be at the top level before any other code.
  const alias = goog.require('my.long.name.alias');
  // ...
}