1 | Transpiles JavaScript modules from one format to another.
|
2 |
|
3 | It supports from:
|
4 |
|
5 | - es6,
|
6 | - cjs,
|
7 | - amd,
|
8 | - steal
|
9 |
|
10 | to
|
11 |
|
12 | - amd,
|
13 | - steal,
|
14 | - cjs.
|
15 |
|
16 | Currently, it can not transpile to ES6 module syntax.
|
17 |
|
18 | ## Install
|
19 |
|
20 | > npm install transpile --save-dev
|
21 |
|
22 | ## Use
|
23 |
|
24 | `transpile.to` transpiles from one format to another format. `transpile.able`
|
25 | lets you know if a transpile is possible.
|
26 |
|
27 | ### Formats
|
28 |
|
29 | Formats are specified by strings like:
|
30 |
|
31 | - "es6" - ES6 Module syntax like `import Point from "math";`
|
32 | - "cjs" - CommonJS syntax like `var _ = require('underscore');`
|
33 | - "amd" - [Asynchronous Module Definition](https://github.com/amdjs/amdjs-api/wiki/AMD)
|
34 | syntax like `define(['jquery'],function($){});`
|
35 | - "steal" - steal syntax like `steal('jquery', function($){})`
|
36 |
|
37 |
|
38 | ### `transpile.to(load, format, options) -> transpiledResult`
|
39 |
|
40 | Transpiles from the `load`'s format to the specified format. If
|
41 | the `load` does not specify a format, `"es6"` modules are assumed. Returns
|
42 | an object containing the transpiled source and sourceMap (if sourceMap option provided).
|
43 |
|
44 | Example:
|
45 |
|
46 | ```js
|
47 | var transpile = require('transpile');
|
48 | var res = transpile.to({
|
49 | name: "my/module",
|
50 | source: "var foo = require('foo')",
|
51 | metadata: {format: "cjs"}
|
52 | }, "amd")
|
53 |
|
54 | res.code //-> "define("my/module", function(require, exports, module) { ... "
|
55 | ```
|
56 |
|
57 | A load is an object in the shape of
|
58 | an [ES6 Load Record](https://people.mozilla.org/~jorendorff/es6-draft.html#sec-load-records-and-loadrequest-objects) like:
|
59 |
|
60 | ```js
|
61 | {
|
62 | name: "moduleName",
|
63 | source: "source code",
|
64 | metadata: {format: "formatName"}
|
65 | }
|
66 | ```
|
67 |
|
68 | #### NOTE
|
69 |
|
70 | Previously `transpile.to` returned a string containing the transpiled source. To accomodate Source Maps support the API has changed and now returns an object that looks like:
|
71 |
|
72 | ```js
|
73 | {
|
74 | code: "define(...", // The transpiled source,
|
75 | map: {}, // A source map, if sourceMaps option is provided.
|
76 | ast: {} // A Mozilla Parser API compatible AST, created by Esprima
|
77 | }
|
78 | ```
|
79 |
|
80 | #### options
|
81 |
|
82 | - __normalizeMap__ `Object<moduleName,moduleName>` - A mapping module names that will
|
83 | be used to replace dependency names in the transpiled result.
|
84 | - __normalize__ `function(name, currentName, address) -> String` - A function
|
85 | that can be used to change moduleNames that are written in the transpiled result.
|
86 | - __namedDefines__ `Boolean=false` - Set to true to insert named defines.
|
87 | - __transpiler__ `String=traceur` - Set which ES6 transpiler to use. Valid options are `traceur` or `6to5` with `traceur` being the default.
|
88 | - __transpile__ `function(source, compileOptions, options) -> Object` - If you want to handle tranpiling yourself and not use the built-in options, this is a function that will be given the source and is expected to return an object containing a `code` string.
|
89 | - __sourceMaps__ `Boolean=false` - Set to true to return a `map` and `ast` object along with the result.
|
90 | - __sourceMapsContent__ `Boolean=false` - If `sourceMaps` is set to true, this option will include the original source contents with the source maps.
|
91 |
|
92 | ### `transpile.able(fromFormat, toFormat) -> transpiledPath`
|
93 |
|
94 | Returns the path used to transpile
|
95 | from `fromFormat` to `toFormat`. If transpiling is not possible, `null` will be
|
96 | returned.
|
97 |
|
98 | Example:
|
99 |
|
100 | ```js
|
101 | var res = transpile.able("steal","cjs");
|
102 | res //-> ["steal","amd"];
|
103 | ```
|
104 |
|
105 | This means that a module will be converted from "steal" to "amd" and then
|
106 | to "cjs".
|
107 |
|
108 |
|
109 | ## Test
|
110 |
|
111 | > npm test
|