Generate Externs from Typescript definitions

Generates externs for closure compiler from the TypeScript declarations of libraries listed in a given libraries definition file.

Installation

# yarn
yarn add -D @canva/closure-compiler-externs-generator

# npm
npm install --save-dev @canva/closure-compiler-externs-generator

Usage

CLI

# To generate externs from specific declaration files
npx @canva/closure-compiler-externs-generator declarations googlepay declarations/googlepay.d.ts

# To automatically discover declaration files for installed packages and generate externs for them
npx @canva/closure-compiler-externs-generator packages react react-dnd

To include symbol source information in the output add the --debug flag to the execution, paths will be relative to current working directory.

API

If in a CommonJS context:

const CCEG = require('@canva/closure-compiler-externs-generator');
const fs = require('node:fs');

If in a ES module context (NodeJS v12 and up):

import CCEG from '@canva/closure-compiler-externs-generator';
import fs from 'node:fs';
import { dirname } from 'node:path';
import { fileURLToPath } from 'node:url';

Then use as follows:

CCEG.generateExternsForPackages({
  // Where externs will be written
  outPath: './my_externs',
  packages: [
    // declaration files will be read from
    // 'node_modules/react/**/*.d.ts' and
    // 'node_modules/@typesreact/**/*.d.ts'
    { name: 'react' },
    {
      name: 'some_module',
      // manually override the declaration globs
      declarationGlobs: ['declarations/some_module.d.t.s'],
    },
  ],
});

CCEG.generateExterns({
  // Where externs will be written
  outPath: './my_externs',
  // The name of the output files, googlepay.js
  identifier: 'googlepay',
  // The declarations to generate from.
  declarations: ['declarations/googlepage.d.ts'],
});

Why Externs?

Closure compiler minifies symbols such as property names and variables. When calling libraries that are not closure compiled from code that is the symbols will be incorrect, for example:

import * as React from 'react';
React.createElement('div', { className: 'foo' });

Would become:

import * as a from 'react';
a.b('div', { c: 'foo' });

To avoid this, closure compiler must be made aware of all symbols not must not be minimised, e.g. in the above example, createElement and className must not be minimised.

Closure compiler has the concept of externs which have a similar role to TypeScript declaration files. They declare the types of an external library that will be included in the closure compilation. Closure uses those types to do both type checking, and to avoid minifying any symbol names used by the libraries.

However, as we use TypeScript for type checking our generated externs only need to include the symbol names and not the type information.

How it works

Most libraries we use now include TypeScript declaration files, which include all the symbols used by a library. So this tool generates externs for a library in 4 steps:

1. Search for declaration files under the globs specified in your library definition, usually node_modules/<library name>/**/*.d.ts and node_modules/@types/<library name>/**/*.d.ts.
2. Parse and traverse the declaration files for symbols that must not be minified, e.g. property names, class names. For a full list see findSymbolNames in get_external_symbols.ts.
3. Recurse into any imported declaration files.
4. Write the found symbols into <out>/<libary name>.js.

Caveats

• The generated externs only contain symbol data, no type information.
• Only main imports are supported. Imports like require('foo/bar') will have unpredictable results.

Releasing

• Bump the version of package.json to a meaningful version for the changes since the last release (we follow semver).
• To do a dry-run of the release and what would go out in the package you can manually execute the npm-publish workflow on the main branch. It will do a dry-run publish (not actually publish the new version).
• Draft a new release in the github project - please use a tag named vX.X.X (where X.X.X is the new to-be-releases semver of the package - please add as many detail as possible to the release description.
• Once you're ready, Publish the release. Publishing will trigger the npm-publish workflow on the tag and do the actual publish to npm.