javascript-externs-generator

by jmmk

Generate externs for use with Google Closure Compiler

130 Stars 9 Forks Last release: Not found ISC License 123 Commits 0 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

javascript-externs-generator

Try it out: http://jmmk.github.io/javascript-externs-generator/

Note from the developer: The externs generator works pretty well for a wide selection of JS libraries, but there are many exceptions (see the issues for examples). I try to respond to and diagnose issues and I am glad to accept Pull Requests, but I am not actively using or maintaining this.

If you find that it couldn't properly generate externs, I would advise:

  1. If you only call a few functions from the library, write the extern by hand
  2. Check out David Nolen's work on "Externs Inference":
  3. Check out shadow-cljs's externs generation

What is it?

This is a tool that generates an extern file detailing an object's properties, methods, and prototype. It's specifically meant for use with the Google Closure Compiler, which needs any variables defined outside of your code to be declared so that it won't rename or remove them.

For a more in-depth explanation of Google Closure Compiler advanced compilation and externs, see the Google Documentation.

How to use it

Web UI (Recommended)

  • Go to http://jmmk.github.io/javascript-externs-generator/
  • Load one or more JS files
  • Enter the main namespace to extern
  • Generate the extern

Node CLI (For scripting/automation)

Install the cli script:

npm install -g externs-generator
Basic Usage
  • Make sure the JS library you want to extern is available locally:
    curl http://code.jquery.com/jquery-1.9.1.js -o jquery.js
  • Run the script:
    generate-extern -f jquery.js -n jQuery -o jquery-extern.js
Advanced Usage - Load multiple files
  • Make sure all JS libraries are available locally:
    • curl -O https://cdnjs.cloudflare.com/ajax/libs/react/15.0.2/react.js
    • curl -O https://cdnjs.cloudflare.com/ajax/libs/react/15.0.2/react-dom.js
    • curl -O http://cdn.jsdelivr.net/webjars/org.webjars.npm/react-relay/0.8.0/dist/relay.js
  • Run the script:
    generate-extern -f react.js,react-dom.js,relay.js -n Relay -o relay-extern.js
Known Issues
  • Some libraries may not be externed properly from the command line - possibly due to differences in jsdom and a real browser environment. The only example I've found is PIXI.js, but it's likely there are more.

How does it work?

The strategy can be broken into three steps:

  1. Evaluate the code - we want to inspect the runtime representation of the object
  2. Recursively walk through the properties of the object and build a tree of all its properties and metadata about those properties
  3. Recursively walk through the tree and build a string representation of each property

Development

Web UI

  • lein figwheel dev
  • open index.html in your browser
  • develop

Node CLI

  • npm install
  • lein cljsbuild auto cli
  • develop
  • test:
    ./bin/extern -f .js -n  -o extern.js
  • If you ever clean/remove ./bin/extern, you will need to run
    chmod +x ./bin/extern
    when it is recreated

Run Unit Tests

  • Make sure phantomjs is installed (follow instructions at https://github.com/bensu/doo#setting-up-environments)
  • lein doo phantom test

Test out externs with the Closure Compiler

Install Closure Compiler

With homebrew, this is as simple as

brew install closure-compiler
. For other options, see the Closure Compiler docs

Run the compiler in advanced mode

closure-compiler --compilation_level ADVANCED [--externs externs.js,] --js file.js[,] [--js_output_file output.js]

Ideally, it should run successfully and the generated output should not mangle any symbols you are using from the library

Issues

Please report any issues to https://github.com/jmmk/javascript-externs-generator/issues

Credits

Based on http://www.dotnetwise.com/Code/Externs/

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.