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 am not actively using or maintaining this.

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

If you only call a few functions from the library, write the extern by hand
Check out David Nolen's work on "Externs Inference":
Check out shadow-cljs's externs generation
- Externs: The Bane of every Release Build

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:

Evaluate the code - we want to inspect the runtime representation of the object
Recursively walk through the properties of the object and build a tree of all its properties and metadata about those properties
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 <library>.js -n <library-name> -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/

License

jmmk/javascript-externs-generator

ErrorLooks like something went wrong!

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

Error
Looks like something went wrong!

Packages