Not a Package Manager

    @canva/closure-compiler-externs-generator
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.1 • Public • Published

    Generate Externs from Typescript definitions

    build npm

    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.

    Keywords

    none

    Install

    npm i @canva/closure-compiler-externs-generator

    DownloadsWeekly Downloads

    19,653

    Version

    2.0.1

    License

    MIT

    Unpacked Size

    29.2 kB

    Total Files

    13

    Last publish

    Collaborators

    • canva-opensource
    • canva-dev