gwt-api-exporter/README.md

Export a JavaScript API from GWT

# gwt-api-exporter

[![NPM version][npm-image]][npm-url]
[![npm download][download-image]][download-url]

Export a JavaScript API from a GWT bundle.

## Installation

`npm i gwt-api-exporter`

If you want to use the CLI, install globally:

`npm i -g gwt-api-exporter`

:warning: This project uses `Promise`, which is only available since Node.js 0.12

## What can be converted

The exporter is designed to work with files generated by the `xsiframe` linker, which is
the default in GWT 2.7. It can handle both obfuscated and pretty files.  
You will need to provide as input the file named `XYZ.cache.js` (name starting with MD5 hash).

To export the JS bindings, you need to use the JSInterop features available from GWT version 2.7.  
Export all your names in the same object of `$wnd` and use the `exports` option to specify the name you chose.  
Example: for the `@JsNamespace("$wnd.example")` annotation, exports would be `example`.  
A simple example project made with Eclipse is available here: https://github.com/targos/gwt-js-example

## Usage as a module

Only one method is exported and returns a Promise.
If no output option is provided, the promise will resolve with the generated code. Otherwise, it will write the output
file and resolve with `true`.

```js
var exporter = require('gwt-api-exporter');
exporter({
  input: 'xxx.cache.js',
  output: 'lib.js',
  exports: 'my.namespace',
  package: {
    name: 'my-lib',
    description: 'my awesome library',
    version: '1.0.0'
  },
}).catch(function(e) {
  console.error(e);
});
```

`package` option can be the path to a package.json file or directly an object with the package data.

## Usage as a CLI

`gwt-api-exporter -i xxx.cache.js -e my.namespace`

### Options

- `-i, --input`: Path to the file generated by GWT (supports only xsiframe linker)
- `-o, --output`: Path for the output file (default: lib.js)
- `-e, --exports`: Exported namespace of the API (without \$wnd)
- `-p, --package`: Path to a package.json file (default: null). If a valid file is provided, the generated lib will contain a header with some metadata like the name, description, version number...
- `-f, --no-fake`: Do not use fakeWindow in browser. This is particularly useful if methods from the main window need to be called (for example \$wnd.addEventListener). Care must be taken not to pollute the global object when this option is on.

## License

[MIT](./LICENSE)

[npm-image]: https://img.shields.io/npm/v/gwt-api-exporter.svg?style=flat-square
[npm-url]: https://npmjs.org/package/gwt-api-exporter
[download-image]: https://img.shields.io/npm/dm/gwt-api-exporter.svg?style=flat-square
[download-url]: https://npmjs.org/package/gwt-api-exporter