Workbox Types

Under /docs/workbox/reference/, we publish information about the current Workbox types.

This data is generated by parsing an external TypeScript Definitions file (".d.ts") file as part of the External data step. We parse the definitions file with TypeDoc, although we don't use TypeDoc's rendering code—we're just interested in its intermediary format which can be passed around and manipulated to help us render the types ourselves.

Workbox Types are generated similarly to Chrome Types. To get a better idea of how types are generated checkout the Chrome Types wiki page.

Ingestion & Processing

• The "external/build/workbox-types.js" script (and its library "external/build/lib/dts-parse.js") installs a list of Workbox packages from NPM and then parses the definitions files.
  • We check where the type definitions is stored in the NPM package. If the index.d.ts is not at the top level of the package then we move it and all of the related files to the top level. This is because the link to the package on /docs/workbox/reference/ will be the PACKAGE_NAME/FULL_PATH_TO_INDEX.D.TS.
• TypeDoc generates a tree of nodes for declarations within the project, which themselves represent methods, types, properties and so on
• We simplify and flatten these declarations slightly by converting them to a type called ExtendedDeclaration (defined in "types.d.ts" within our project)
• This is rendered by "render-type.njk" and friends

Flat Declarations

Feature Information

Many nodes in the definition file contain @-tags describing behavior or expectations of the data. For example, the GeneratePartial interface has:

export interface GeneratePartial {
  /**
   * @default ["chrome >= 56"]
   */
  babelPresetEnvTargets?: Array<string>;
}

Rather than traversing through @-tags when rendering, each node has an FeatureInfo added under the "_feature" property.

This contains notes parsed from these tags.

Rendering Code

(i.e., "namespace-reference.njk" and "render-type.njk".)

These files are somewhat long but hopefully self-explanatory. Each namespace page renders a number of groups of types (e.g., Events, Properties) as first a summary section (for navigation), and then as their whole contents.

We walk the tree of our flattened types to render top-level versions and nest into things like their method parameters (under "_method") or object properties (under "_type"). There's a number of methods to render e.g., short hint versions of types to be used in function signatures and so on.