Need help with javascript-externs-generator?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

jmmk
131 Stars 9 Forks ISC License 123 Commits 7 Opened issues

Description

Generate externs for use with Google Closure Compiler

Services available

!
?

Need anything else?

Contributors list

# 295,746
Clojure...
elixir-...
capture...
Babel
114 commits

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.