diff --git a/docs/Markup.html b/docs/Markup.html
index 11a2be6..b161310 100644
--- a/docs/Markup.html
+++ b/docs/Markup.html
@@ -386,7 +386,7 @@ <h5>Parameters:</h5>
 		<ul class="dummy">
 			<li>
 				<a href="Markup.js.html">Markup.js</a>,
-				 <a href="Markup.js.html#sunlight-1-line-149">line 149</a>
+				 <a href="Markup.js.html#sunlight-1-line-171">line 171</a>
 			</li>
 		</ul>
 	</dd>
@@ -574,7 +574,7 @@ <h5>Parameters:</h5>
 		<ul class="dummy">
 			<li>
 				<a href="Markup.js.html">Markup.js</a>,
-				 <a href="Markup.js.html#sunlight-1-line-189">line 189</a>
+				 <a href="Markup.js.html#sunlight-1-line-211">line 211</a>
 			</li>
 		</ul>
 	</dd>
@@ -762,7 +762,7 @@ <h5>Parameters:</h5>
 		<ul class="dummy">
 			<li>
 				<a href="Markup.js.html">Markup.js</a>,
-				 <a href="Markup.js.html#sunlight-1-line-205">line 205</a>
+				 <a href="Markup.js.html#sunlight-1-line-227">line 227</a>
 			</li>
 		</ul>
 	</dd>
@@ -950,7 +950,7 @@ <h5>Parameters:</h5>
 		<ul class="dummy">
 			<li>
 				<a href="Markup.js.html">Markup.js</a>,
-				 <a href="Markup.js.html#sunlight-1-line-221">line 221</a>
+				 <a href="Markup.js.html#sunlight-1-line-243">line 243</a>
 			</li>
 		</ul>
 	</dd>
diff --git a/docs/Markup.js.html b/docs/Markup.js.html
index b108260..4041f8c 100644
--- a/docs/Markup.js.html
+++ b/docs/Markup.js.html
@@ -223,6 +223,28 @@ <h1 class="page-title">Source: Markup.js</h1>
     return map(reject(children, ['type', 'comment']), (c, i) => 'text' === c.type ? c.data : Markup.childToJSX(c, i));
   }
 
+  /**
+   * If a simple single line string is passed to the Markdown parser it thinks that it's a paragraph (it sort of
+   * technically is) and unnecessarily wraps it into `&lt;p>&lt;/p>`, which most often is not the desired behavior.
+   *
+   * This function converts Markdown to HTML and then removes the wrapping paragraph if it is the only top level tag
+   * unwrapping its contents.
+   *
+   * @memberof Markup
+   * @static
+   * @private
+   * @method markdownToUnwrappedHTML
+   * @param {string} markdown - an arbitrary Markdown string
+   * @return {string} an HTML string
+   */
+  static markdownToUnwrappedHTML(markdown: string): string {
+    const html = trim(marked(markdown)),
+        dom = load(html),
+        {children} = dom.root().toArray()[0];
+
+    return 1 === children.length &amp;&amp; 'tag' === children[0].type &amp;&amp; 'p' === children[0].name ? dom('p').html() : html;
+  }
+
   /**
    * Recursively flattens `args` and combines string values.
    *
@@ -292,7 +314,7 @@ <h1 class="page-title">Source: Markup.js</h1>
    */
   markdownToHTML(markdown: string = ''): string {
     markdown = trim(markdown);
-    return markdown ? trim(this.transform(marked(markdown))) : '';
+    return markdown ? trim(this.transform(Markup.markdownToUnwrappedHTML(markdown))) : '';
   }
 
   /**
@@ -308,7 +330,7 @@ <h1 class="page-title">Source: Markup.js</h1>
    */
   markdownToJSX(markdown: string = ''): Array&lt;any> {
     markdown = trim(markdown);
-    return markdown ? this.htmlToJSX(marked(markdown)) : [];
+    return markdown ? this.htmlToJSX(Markup.markdownToUnwrappedHTML(markdown)) : [];
   }
 
 }
diff --git a/docs/quicksearch.html b/docs/quicksearch.html
index 9cfc1af..757fcf2 100644
--- a/docs/quicksearch.html
+++ b/docs/quicksearch.html
@@ -7,7 +7,7 @@
     <script src="scripts/fulltext-search.js"></script>
 
     <script type="text/x-docstrap-searchdb">
-    {"typedef.js.html":{"id":"typedef.js.html","title":"Source: typedef.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: typedef.js /* @flow */ /** * Processed application code with source maps * * @typedef {Object} ProgramData * @property {string} code - program code * @property {string} map - source map json string */ export type ProgramData = {code: string, map: string}; /** * The JavaScript linting error object * * @typedef {Object} JSLintError * @property {string} message - the error message * @property {string} [ruleId] - the relative linting rule * @property {string} filePath - the path to a file * @property {number} line - the offending line number * @property {number} column - the offending column number */ export type JSLintError = {message: string, ruleId?: string, filePath: string, line: number, column: number}; /** * A dumbed down representation of a DOM Node * * @typedef {Object} CheerioNode * @property {string} type - either &quot;comment&quot;, &quot;text&quot; or &quot;tag&quot; */ export type CheerioNode = {type: string}; /** * A dumbed down representation of a DOM Element * * @typedef {Object} CheerioElement * @property {string} type - &quot;tag&quot; * @property {string} name - the tag name (e.g. &quot;div&quot;) * @property {Object} attribs - the tag attributes (e.g. {style: 'min-width:50px'}) * @property {Array&lt;CheerioNode&gt;} [children] - an array of child nodes * @property {CheerioNode} [next] - the next sibling node * @property {CheerioNode} [prev] - the previous sibling node * @property {CheerioElement} [parent] - the parent element */ export type CheerioElement = {type: string, name: string, attribs: Object, children?: Array&lt;CheerioNode&gt;, next: ?CheerioNode, prev: ?CheerioNode, parent: ?CheerioElement}; /** * A dumbed down representation of a DOM Text or a Comment Nodes * * @typedef {Object} CheerioText * @property {string} type - either &quot;text&quot; or &quot;comment&quot; * @property {string} data - the textual content of the node * @property {CheerioNode} [next] - the next sibling node * @property {CheerioNode} [prev] - the previous sibling node * @property {CheerioElement} [parent] - the parent element */ export type CheerioText = {type: string, data: string, next: ?CheerioNode, prev: ?CheerioNode, parent: ?CheerioElement}; /** * Documentation generator configuration object * * @typedef {Object} DocumentationConfig * @property {string} [inputDir=&quot;src&quot;] - the input application code directory * @property {string} [outputDir=&quot;docs&quot;] - the output directory for the generated documentation * @property {string} [readMe=&quot;README.md&quot;] - the documentation &quot;homepage&quot; (README.md file) * @property {string} [template=&quot;node_modules/ink-docstrap/template&quot;] - a full system path to a valid JSDoc3 * template directory * @property {string} [jsdocConfig=&quot;&lt;webcompiler root&gt;/config/jsdoc.json&quot;] - a full system path to a JSDoc3 * configuration file */ /** * @callback ProgramDataCallback * @param {ProgramData} data - the program data */ export type ProgramDataCallback = (data: ProgramData) =&gt; void; /** * @callback FileCallback * @param {string} file - a full system path to a file */ export type FileCallback = (file: string) =&gt; void; /** * @callback NullableFileCallback * @param {string} [file] - a full system path to a file */ export type NullableFileCallback = (file: ?string) =&gt; void; /** * @callback JSLintCallback * @param {Array&lt;JSLintError&gt;} [errors] - a collection of error objects */ export type JSLintCallback = (errors: ?Array&lt;JSLintError&gt;) =&gt; void; /** * @callback NativeProcessCallback * @param {string} [stderr] - an error message * @param {string} stdout - the process output */ export type NativeProcessCallback = (stderr: ?string, stdout: string) =&gt; void; /** * @callback ObjectOrErrorCallback * @param {string} [error] - an error message * @param {Object} result - the resulting object */ export type ObjectOrErrorCallback = (error: ?string, result: Object) =&gt; void; /** * Must be a pure function, always return the same value given the same input, must be side-effect free and not depend * on other replacers executing before it. * * If provided with a result of its own previous execution, must return it unchanged. * * @callback Transformer * @param {string} input - a transformed string * @return {string} transformed output */ export type Transformer = (input: string) =&gt; string; × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"Compiler.js.html":{"id":"Compiler.js.html","title":"Source: Compiler.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: Compiler.js /* @flow */ import type {ProgramData, ProgramDataCallback} from './typedef'; import mkdirp from 'mkdirp'; import {dirname} from 'path'; import {writeFile} from 'fs'; import {gzip} from 'zlib'; let i = 0; /** * The base compiler class * * @class Compiler * @abstract * @param {boolean} [compress=true] - if true `Compiler#optimize` will gzip compress the data in production mode */ export class Compiler { /** * True if the NODE_ENV environment variable is equal to `production`. * * Caution: modifying it's value directly may lead to unexpected results * * @member {boolean} isProduction * @memberof Compiler * @readOnly * @instance */ isProduction: boolean; /** * if true `Compiler#optimize` will gzip compress the data * * @member {boolean} compress * @memberof Compiler * @private * @instance */ compress: boolean; constructor(compress: boolean = true) { this.isProduction = 'production' === process.env.NODE_ENV; this.compress = this.isProduction &amp;&amp; compress; } /** * Executed when the compilation is complete * * @memberOf Compiler * @static * @method done * @param {string} inPath - the input path * @param {Function} callback - a callback function * @example * Compiler.done('/path/to/an/input/file', callback); */ static done(inPath: string, callback: () =&gt; void) { console.log('\\x1b[32m%s. Compiled %s\\x1b[0m', ++i, inPath); callback(); } /** * Writes the data to disk and then calls `done`. * * @memberOf Compiler * @static * @private * @method writeAndCallDone * @param {string} inPath - the input path * @param {string} outPath - the output path * @param {ProgramData} data - processed application code with source maps * @param {Function} callback - a callback function * @example * Compiler.writeAndCallDone('/path/to/an/input/file', '/path/to/the/output/file', data, callback); */ static writeAndCallDone(inPath: string, outPath: string, data: ProgramData, callback: () =&gt; void) { Compiler.fsWrite(outPath, data, () =&gt; { Compiler.done(inPath, callback); }); } /** * Writes the data to disk * * @memberOf Compiler * @static * @method fsWrite * @param {string} path - the output path * @param {ProgramData} data - the data to write * @param {Function} callback - a callback function * @example * Compiler.fsWrite('/path/to/an/output/file', data, callback); */ static fsWrite(path: string, data: ProgramData, callback: () =&gt; void) { Compiler.mkdir(path, () =&gt; { writeFile(path, data.code, scriptErr =&gt; { if (scriptErr) { return console.error(scriptErr); } if (!data.map) { return callback(); } writeFile(`${path}.map`, data.map, mapErr =&gt; { if (mapErr) { return console.error(mapErr); } callback(); }); }); }); } /** * Recursively creates a directory containing a file specified by `path`. * * @memberOf Compiler * @static * @method mkdir * @param {string} path - a path to a file * @param {Function} callback - a callback function * @example * Compiler.mkdir('/path/to/a/file', callback); */ static mkdir(path: string, callback: () =&gt; void) { mkdirp(dirname(path), mkdirpErr =&gt; { if (mkdirpErr) { return console.error(mkdirpErr); } callback(); }); } /** * G-zips the compiled code * * @memberOf Compiler * @static * @method gzip * @param {ProgramData} data - the actual program data to auto-prefix * @param {ProgramDataCallback} callback - a callback function * @example * Compiler.gzip(data, callback); */ static gzip(data: ProgramData, callback: ProgramDataCallback) { gzip(data.code, (err, code) =&gt; { if (err) { return console.error(err); } callback({code, map: data.map}); }); } /** * G-zips the program if necessary and writes the results to disk. * * @memberOf Compiler * @instance * @protected * @method optimize * @param {string} inPath - the input path * @param {string} outPath - the output path * @param {ProgramData} data - processed application code with source maps * @param {Function} callback - a callback function * @example * compiler.optimize('/path/to/an/input/file', '/path/to/the/output/file', data, callback); */ optimize(inPath: string, outPath: string, data: ProgramData, callback: () =&gt; void) { if (!this.compress) { Compiler.writeAndCallDone(inPath, outPath, data, callback); return; } Compiler.gzip(data, result =&gt; { Compiler.writeAndCallDone(inPath, outPath, result, callback); }); } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"DevServer.js.html":{"id":"DevServer.js.html","title":"Source: DevServer.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: DevServer.js /* @flow */ import {SASSCompiler} from './SASSCompiler'; import {watch} from './watch'; import tinylr from 'tiny-lr'; import WebpackDevServer from 'webpack-dev-server'; import webpack from 'webpack'; import {join} from 'path'; const LIVERELOAD_PORT = 35729, WEB_PORT = 3000; /** * A lightweight development server that rapidly recompiles the JavaScript and SASS files when they are edited and * updates the page. * * Utilizes the Webpack development server. * * Includes react hot loader to further optimize the development process of the React applications. * * Please install and enable the LiveReload browser extension for the CSS reloading to work. * * @class DevServer * @param {string} script - a full system path to a JavaScript file * @param {string} style - a full system path to a SASS file * @param {string} devDir - a full system path to a directory in which to put any compiled development resources * @param {number} [port=3000] - a port at which to start the dev server * @param {boolean} [react=true] - false to disable the react hot loader plugin * @see {@link http://webpack.github.io/docs/webpack-dev-server.html webpack-dev-server} * @see {@link http://gaearon.github.io/react-hot-loader/ React Hot Loader} * @example * import {DevServer} from 'webcompiler'; * import {join} from 'path'; * * const rootDir = join(__dirname, '..'), * devDir = join(rootDir, 'development'), * server = new DevServer(join(devDir, 'script.js'), join(devDir, 'app.scss'), devDir); * * server.run(rootDir); * // now navigate to http://localhost:3000 using your favorite browser ( preferably Chrome :) ) */ export class DevServer { /** * a port at which to start the dev server * * @member {number} port * @memberof DevServer * @private * @instance */ port: number; /** * a LiveReload server * * @member {tinylr.Server} lr * @memberof DevServer * @private * @instance */ lr: tinylr.Server; /** * recompiles SASS and notifies LiveReload * * @method compileSASS * @memberof DevServer * @private * @instance */ compileSASS: () =&gt; void; /** * the Webpack development server * * @member {WebpackDevServer} server * @memberof DevServer * @private * @instance */ server: WebpackDevServer; constructor(script: string, style: string, devDir: string, port: number = WEB_PORT, react: boolean = true) { const sass = new SASSCompiler(), loaders = []; if (react) { loaders.push('react-hot'); } loaders.push('babel'); this.port = port; this.lr = tinylr(); this.compileSASS = sass.fe.bind(sass, style, join(devDir, 'style.css'), () =&gt; { this.lr.changed({body: {files: ['style.css']}}); }); this.server = new WebpackDevServer(webpack({ cache: {}, debug: true, devtool: 'eval-source-map', entry: [ `webpack-dev-server/client?http://localhost:${this.port}`, 'webpack/hot/only-dev-server', script ], output: { path: devDir, filename: 'script.js', publicPath: '/' }, plugins: [ new webpack.HotModuleReplacementPlugin(), new webpack.NoErrorsPlugin() ], module: { loaders: [{ test: /\\.js$/, exclude: /node_modules/, loaders }] } }), { contentBase: devDir, publicPath: '/', hot: true, historyApiFallback: true }); this.server.app.get('*', (req, res) =&gt; { res.send(`&lt;!DOCTYPE html&gt; &lt;html lang=&quot;en&quot;&gt; &lt;head&gt; &lt;meta charset=&quot;utf-8&quot;&gt; &lt;meta http-equiv=&quot;X-UA-Compatible&quot; content=&quot;IE=edge&quot;&gt; &lt;meta name=&quot;viewport&quot; content=&quot;width=device-width, initial-scale=1&quot;&gt; &lt;title&gt;Development server - Webcompiler&lt;/title&gt; &lt;link href=&quot;/style.css&quot; rel=&quot;stylesheet&quot;&gt; &lt;/head&gt; &lt;body&gt; &lt;div id=&quot;app&quot;&gt;&lt;/div&gt; &lt;script src=&quot;/script.js&quot; async defer&gt;&lt;/script&gt; &lt;/body&gt; &lt;/html&gt;`); }); } /** * Compile SASS and start watching for file changes * * @memberof DevServer * @instance * @method watchSASS * @param {string} watchDir - the directory in which to watch for the changes in the SASS files * @example * server.watchSASS('/path/to/some/directory'); */ watchSASS(watchDir: string) { this.lr.listen(LIVERELOAD_PORT); this.compileSASS(); watch(watchDir, 'scss', this.compileSASS); } /** * Starts the Webpack development server * * @memberof DevServer * @instance * @method watchJS * @example * server.watchJS(); */ watchJS() { const port = this.port; this.server.listen(port, '0.0.0.0', error =&gt; { if (error) { return console.error(error); } console.log(`Started the development server at localhost:${port}`); }); } /** * Starts the Webpack development server, compiles SASS and starts watching for file changes * * @memberof DevServer * @instance * @method run * @param {string} watchDir - the directory in which to watch for the changes in the SASS files * @example * server.run('/path/to/some/directory'); */ run(watchDir: string) { this.watchJS(); this.watchSASS(watchDir); } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"Documentation.js.html":{"id":"Documentation.js.html","title":"Source: Documentation.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: Documentation.js /* @flow */ import type {FileCallback, NullableFileCallback} from './typedef'; import {NativeProcess} from './NativeProcess'; import {stat} from 'fs'; import {join} from 'path'; import noop from 'lodash/noop'; const npm = new NativeProcess('npm'), cwd = process.cwd(), defaultOptions = { inputDir: join(cwd, 'src'), outputDir: join(cwd, 'docs'), readMe: join(cwd, 'README.md'), template: join(cwd, 'node_modules', 'ink-docstrap', 'template'), jsdocConfig: join(__dirname, '..', 'config', 'jsdoc.json') }; /** * Generates API documentation * * The default JSDoc plugin specified in `jsdocConfig` strips out all of the code from a file while retaining newlines * (unlike the built in `commentsOnly` plugin that ships with JSDoc3). * * That way: * 1. line numbers are preserved in the source view * 2. you don't need to use a pre-compiler, you will always see the same code as you wrote in the docs source view * 3. since JSDoc only sees comments you can use any code syntax you like - ES2015, ES7, JSX, it doesn't even have to be * JavaScript. * * The markdown plugin is also included by default. * * @class Documentation * @param {DocumentationConfig} [config={}] - a configuration object * @example * import {Documentation} from 'webcompiler'; * * const docs = new Documentation(); */ export class Documentation { /** * JSDoc3 * * @member {NativeProcess} jsdoc * @memberof Documentation * @private * @instance */ jsdoc: ?NativeProcess; /** * documentation generator configuration object * * @member {DocumentationConfig} options * @memberof Documentation * @private * @instance */ options: Object; constructor(options: Object = {}) { this.options = {...defaultOptions, ...options}; } /** * Finds a path to the JSDoc3 executable * * @memberof Documentation * @static * @private * @method findExecutable * @param {FileCallback} callback - a callback function * @example * Documentation.findExecutable(file =&gt; { * // the jsdoc file is found * }); */ static findExecutable(callback: FileCallback) { Documentation.checkBin(localFile =&gt; { if (localFile) { return callback(localFile); } Documentation.checkBin(globalFile =&gt; { if (globalFile) { return callback(globalFile); } console.error('Failed to locate the jsdoc executable'); }, true); }); } /** * Checks the NPM bin directories to see if they contain a file named jsdoc * * @memberof Documentation * @static * @private * @method checkBin * @param {NullableFileCallback} callback - a callback function * @param {globalPackage} [boolean=false] - if true checks the global NPM bin directory (contains the npm * executable itself) * @example * Documentation.checkBin(file =&gt; { * if (file) { * // the jsdoc file is found * } * }); */ static checkBin(callback: NullableFileCallback, globalPackage: boolean = false) { const args = ['bin']; if (globalPackage) { args.push('-g'); } npm.run((stderr, stdout) =&gt; { if (stderr) { console.error(stderr); return callback(null); } const path = join(stdout.replace(/\\n$/, ''), 'jsdoc'); stat(path, err =&gt; { callback(err ? null : path); }); }, args); } /** * Generate the documentation * * @memberof Documentation * @instance * @method run * @param {Function} [callback=function () {}] - a callback function * @return {void} * @example * docs.run(() =&gt; { * // generated the API documentation * }); */ run(callback: () =&gt; void = noop) { if (this.jsdoc) { return this.doRun(this.jsdoc, callback); } Documentation.findExecutable(file =&gt; { this.jsdoc = new NativeProcess(file); this.doRun(this.jsdoc, callback); }); } /** * Given a JSDoc3 executable, generate the documentation * * @memberof Documentation * @instance * @private * @method doRun * @param {NativeProcess} jsdoc - JSDoc3 * @param {Function} callback - a callback function * @example * docs.doRun(jsdoc, () =&gt; { * // generated the API documentation * }); */ doRun(jsdoc: NativeProcess, callback: () =&gt; void) { const {inputDir, outputDir, readMe, template, jsdocConfig} = this.options; jsdoc.run(stderr =&gt; { if (stderr) { return console.error(stderr); } callback(); }, [inputDir, '-d', outputDir, '-R', readMe, '-c', jsdocConfig, '-t', template]); } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"JS.js.html":{"id":"JS.js.html","title":"Source: JS.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: JS.js /* @flow */ import {JSCompiler} from './JSCompiler'; import {NativeProcess} from './NativeProcess'; import {JSLint} from './JSLint'; import forEach from 'lodash/forEach'; import noop from 'lodash/noop'; /** * JavaScript compilation tools * * @class JS * @param {boolean} [compress=true] - if true `Compiler#optimize` will gzip compress the data * @param {Object} [babelOptions={}] - allows to override the default Babel options * @param {Object} [lintRules={}] - allows to override the default linting rules * @example * import {JS} from 'webcompiler'; * * const js = new JS(); */ export class JS { /** * JavaScript compiler * * @member {JSCompiler} compiler * @memberof JS * @private * @instance */ compiler: JSCompiler; /** * flow static analyzer * * @member {NativeProcess} flow * @memberof JS * @private * @instance */ flow: NativeProcess; /** * JavaScript linter * * @member {JSLint} linter * @memberof JS * @private * @instance */ linter: JSLint; constructor(compress: boolean = true, babelOptions: Object = {}, lintRules: Object = {}) { this.compiler = new JSCompiler(compress, babelOptions); this.flow = new NativeProcess('flow'); this.linter = new JSLint(lintRules); } /** * Performs static analysis * * @memberof JS * @instance * @method typecheck * @param {Function} callback - a callback function, invoked only when successfully typechecked * @example * js.typecheck(() =&gt; { * // successfully typechecked * }); */ typecheck(callback: () =&gt; void) { this.flow.run((flowErr, stdout) =&gt; { if (flowErr) { return console.error(flowErr); } if (!JSON.parse(stdout).passed) { return this.flow.run(noop, [], {stdio: 'inherit'}); } callback(); }, ['--json']); } /** * Performs linting * * @memberof JS * @instance * @method lint * @param {Array&lt;string&gt;} paths - an array of paths to files/directories to lint * @param {Function} callback - a callback function, invoked only when successfully linted * @example * js.lint(['/path/to/the/input/file.js', '/lint/this/directory/too'], () =&gt; { * // successfully linted * }); */ lint(paths: Array&lt;string&gt;, callback: () =&gt; void) { this.linter.run(paths, linterErr =&gt; { if (!linterErr) { return callback(); } forEach(linterErr, e =&gt; { console.log( '\\x1b[41mESLint error\\x1b[0m &quot;\\x1b[33m%s%s\\x1b[0m&quot; in \\x1b[36m%s\\x1b[0m on \\x1b[35m%s:%s\\x1b[0m', e.message, e.ruleId ? ` (${e.ruleId})` : '', e.filePath, e.line, e.column); }); console.log('JavaScript linting errors: %s', linterErr.length); }); } /** * Performs static analysis and linting * * @memberof JS * @instance * @private * @method validate * @param {string} inPath - the input file (will also be linted) * @param {Array&lt;string&gt;} lintPaths - an array of paths to files/directories to lint * @param {Function} callback - a callback function, invoked only when successfully validated * @example * js.validate('/path/to/the/input/file.js', ['/lint/this/directory/too'], () =&gt; { * // successfully validated * }); */ validate(inPath: string, lintPaths: Array&lt;string&gt;, callback: () =&gt; void) { this.typecheck(() =&gt; { this.lint(lintPaths.concat([inPath]), callback); }); } /** * Wraps {@link JSCompiler#be} to add static analysis and linting * * @memberOf JS * @instance * @method be * @param {string} inPath - the input path * @param {string} outPath - the output path * @param {Array&lt;string&gt;} [lintPaths=[]] - an array of paths to files/directories to lint * @param {Function} [callback=function () {}] - a callback function * @return {void} * @example * compiler.be('/path/to/an/input/file.js', '/path/to/the/output/file.js', ['/lint/this/directory/too'], () =&gt; { * // the code has passed all the checks and has been compiled successfully * }); */ be(inPath: string, outPath: string, lintPaths: Array&lt;string&gt; = [], callback: () =&gt; void = noop) { this.validate(inPath, lintPaths, () =&gt; { this.compiler.be(inPath, outPath, callback); }); } /** * Wraps {@link JSCompiler#fe} to add static analysis and linting * * @memberOf JS * @instance * @method fe * @param {string} inPath - the input path * @param {string} outPath - the output path * @param {Array&lt;string&gt;} [lintPaths=[]] - an array of paths to files/directories to lint * @param {Function} [callback=function () {}] - a callback function * @return {void} * @example * compiler.fe('/path/to/an/input/file.js', '/path/to/the/output/file.js', ['/lint/this/directory/too'], () =&gt; { * // the code has passed all the checks and has been compiled successfully * }); */ fe(inPath: string, outPath: string, lintPaths: Array&lt;string&gt; = [], callback: () =&gt; void = noop) { this.validate(inPath, lintPaths, () =&gt; { this.compiler.fe(inPath, outPath, callback); }); } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"JSCompiler.js.html":{"id":"JSCompiler.js.html","title":"Source: JSCompiler.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: JSCompiler.js /* @flow */ import {Compiler} from './Compiler'; import {join, extname, dirname, basename} from 'path'; import {readdir, stat, createReadStream, createWriteStream, readFileSync} from 'fs'; import {transformFile} from 'babel-core'; import webpack from 'webpack'; import MemoryFS from 'memory-fs'; import forEach from 'lodash/forEach'; import noop from 'lodash/noop'; import assignWith from 'lodash/assignWith'; import get from 'lodash/get'; import isArray from 'lodash/isArray'; import uniq from 'lodash/uniq'; /* eslint-disable no-sync */ const config = JSON.parse(readFileSync(join(__dirname, '..', '.babelrc'), 'utf8')), cache = {}, fakeFS = new MemoryFS(), {DedupePlugin, UglifyJsPlugin} = webpack.optimize, productionPlugins = [new DedupePlugin(), new UglifyJsPlugin()]; /** * A JavaScript compiler * * @class JSCompiler * @extends Compiler * @param {boolean} [compress=true] - if true `Compiler#optimize` will gzip compress the data * @param {Object} [options={}] - allows to override the default Babel options * @example * import {JSCompiler} from 'webcompiler'; * * const compiler = new JSCompiler(); */ export class JSCompiler extends Compiler { /** * Babel options * * @member {Object} options * @memberOf JSCompiler * @private * @instance */ options: Object; /** * The number of files being compiled at the moment * * @member {number} processing * @memberOf JSCompiler * @private * @instance */ processing: number; constructor(compress: boolean = true, options: Object = {}) { super(compress); this.configure(options); this.processing = 0; } /** * Merges Babel configuration options * * @memberOf JSCompiler * @instance * @private * @method configure * @param {Object} options - allows to override the default Babel options * @example * compiler.configure(options); */ configure(options: Object) { this.options = assignWith({}, config, get(config, ['env', process.env.NODE_ENV || 'development']), options, (objValue, srcValue) =&gt; { if (!isArray(srcValue)) { return srcValue; } if (!isArray(objValue)) { return uniq(srcValue); } return uniq(srcValue.concat(objValue)); }); delete this.options.env; } /** * Compiles a directory of files for the back end * * @memberOf JSCompiler * @instance * @private * @method beDir * @param {string} inPath - the input path * @param {string} outPath - the output path * @param {Function} callback - a callback function * @example * compiler.beDir('/path/to/an/input/directory', '/path/to/the/output/directory', callback); */ beDir(inPath: string, outPath: string, callback: () =&gt; void) { readdir(inPath, (readdirErr, files) =&gt; { if (readdirErr) { return console.error(readdirErr); } forEach(files, file =&gt; { this.beTraverse(join(inPath, file), join(outPath, file), callback); }); }); } /** * Compiles a JavaScript file for the back end * * @memberOf JSCompiler * @instance * @private * @method beFile * @param {string} inPath - the input path * @param {string} outPath - the output path * @param {Function} callback - a callback function * @example * compiler.beFile('/path/to/an/input/file.js', '/path/to/the/output/file.js', callback); */ beFile(inPath: string, outPath: string, callback: () =&gt; void) { ++this.processing; transformFile(inPath, this.options, (transformFileErr, result) =&gt; { if (transformFileErr) { return console.error(transformFileErr); } Compiler.fsWrite(outPath, result, callback); }); } /** * Copies a file * * @memberOf JSCompiler * @instance * @private * @method copyFile * @param {string} inPath - the input path * @param {string} outPath - the output path * @param {Function} callback - a callback function * @example * compiler.copyFile('/path/to/an/input/file', '/path/to/the/output/file', callback); */ copyFile(inPath: string, outPath: string, callback: () =&gt; void) { ++this.processing; Compiler.mkdir(outPath, () =&gt; { createReadStream(inPath).pipe(createWriteStream(outPath)); callback(); }); } /** * Compiles a JavaScript file for the back end or recursively traverses a directory, looking for the JavaScript files * to compile. Non-JavaScript files are simply copied over. * * @memberOf JSCompiler * @instance * @private * @method beTraverse * @param {string} inPath - the input path * @param {string} outPath - the output path * @param {Function} callback - a callback function * @example * compiler.beTraverse('/path/to/an/input/file.js', '/path/to/the/output/file.js', callback); */ beTraverse(inPath: string, outPath: string, callback: () =&gt; void) { stat(inPath, (statErr, stats) =&gt; { if (statErr) { return console.error(statErr); } if (stats.isDirectory()) { this.beDir(inPath, outPath, callback); } else if ('.js' === extname(inPath)) { this.beFile(inPath, outPath, callback); } else { this.copyFile(inPath, outPath, callback); } }); } /** * Compiles a JavaScript file or a directory for the back end. Non-JavaScript files are simply copied over. * * @memberOf JSCompiler * @instance * @method be * @param {string} inPath - the input path * @param {string} outPath - the output path * @param {Function} [callback=function () {}] - a callback function * @return {void} * @example * compiler.be('/path/to/an/input/file.js', '/path/to/the/output/file.js', callback); */ be(inPath: string, outPath: string, callback: () =&gt; void = noop) { if (this.processing) { return console.error('Still working...'); } this.beTraverse(inPath, outPath, () =&gt; { if (!(--this.processing)) { Compiler.done(inPath, callback); } }); } /** * Compiles, bundles (in production mode also minifies and g-zips) a JavaScript file for the front end. * * @memberOf JSCompiler * @instance * @method fe * @param {string} inPath - the input path * @param {string} outPath - the output path * @param {Function} [callback=function () {}] - a callback function * @example * compiler.fe('/path/to/an/input/file.js', '/path/to/the/output/file.js', callback); */ fe(inPath: string, outPath: string, callback: () =&gt; void = noop) { const compiler = webpack({ cache, debug: true, devtool: 'source-map', entry: inPath, output: {path: dirname(outPath), filename: basename(outPath)}, plugins: this.isProduction ? productionPlugins : [], module: { loaders: [{ test: /\\.js$/, exclude: /node_modules/, loader: 'babel-loader', query: {cacheDirectory: true, ...this.options} }, { test: /\\.json$/, loader: 'json' }] } }); compiler.outputFileSystem = fakeFS; compiler.run((err, stats) =&gt; { if (err) { return console.error(err); } const {warnings, errors} = stats.toJson(); forEach(warnings, warning =&gt; { console.log('\\x1b[33m%s\\x1b[0m', warning); }); if (errors.length) { return forEach(errors, error =&gt; { console.error(error); }); } this.optimize(inPath, outPath, { code: fakeFS.readFileSync(outPath, 'utf8'), map: fakeFS.readFileSync(`${outPath}.map`, 'utf8') }, callback); }); } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"JSLint.js.html":{"id":"JSLint.js.html","title":"Source: JSLint.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: JSLint.js /* @flow */ import type {JSLintCallback} from './typedef'; import {CLIEngine} from 'eslint'; import {join} from 'path'; import forEach from 'lodash/forEach'; const configFile = join(__dirname, '..', 'config', 'eslint.yml'); /** * A JavaScript linter * * @class JSLint * @param {Object} [rules={}] - an object that lets you override default linting rules * @example * import {JSLint} from 'webcompiler'; * import {join} from 'path'; * * const linter = new JSLint(); */ export class JSLint { /** * an internal linter instance * * @member {CLIEngine} linter * @memberof JSLint * @private * @instance */ linter: CLIEngine; constructor(rules: Object = {}) { this.linter = new CLIEngine({configFile, rules}); } /** * Execute the linter * * @memberof JSLint * @instance * @method run * @param {Array&lt;string&gt;} paths - an array of paths to files/directories to lint * @param {JSLintCallback} callback - a callback function, accepts 1 argument: an array of error objects or null * @example * // lint &quot;index.js&quot; as well as the entire contents of the &quot;src&quot; directory * linter.run([join(__dirname, 'index.js'), join(__dirname, 'src')], function (err) { * if (err) { * return e.forEach(e =&gt; { * console.log('\\x1b[41mESLint error\\x1b[0m &quot;\\x1b[33m%s%s\\x1b[0m&quot; in \\x1b[36m%s\\x1b[0m on \\x1b[35m%s:%s\\x1b[0m', * e.message, e.ruleId ? ` (${e.ruleId})` : '', e.filePath, e.line, e.column); * }); * } * // there were no linting errors * }); */ run(paths: Array&lt;string&gt;, callback: JSLintCallback) { const report = this.linter.executeOnFiles(paths), errors = []; forEach(report.results, f =&gt; { forEach(f.messages, e =&gt; { e.filePath = f.filePath; errors.push(e); }); }); callback(errors.length ? errors : null); } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"Markup.js.html":{"id":"Markup.js.html","title":"Source: Markup.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: Markup.js /* @flow */ import type {CheerioNode, CheerioElement, Transformer} from './typedef'; import {load} from 'cheerio'; import {createElement} from 'react'; import marked from 'marked'; import reject from 'lodash/reject'; import map from 'lodash/map'; import transform from 'lodash/transform'; import has from 'lodash/has'; import reduce from 'lodash/reduce'; import flattenDeep from 'lodash/flattenDeep'; import isString from 'lodash/isString'; import trim from 'lodash/trim'; /* eslint-disable no-arrow-condition */ /** * Allows to easily and efficiently convert text from Markdown to HTML and from HTML to a collection of React Elements * that can be used directly in a JSX expression. * * Whenever an HTML string is involved, runs it through an array of Transformer functions. * * @class Markup * @param {...Transformer} transformers - transformers to initialize with * @example * import {Markup} from 'webcompiler'; * * const mark = new Markup(); */ export class Markup { /** * an array of Transformer functions * * @member {Array&lt;Transformer&gt;} transformers * @memberof Markup * @private * @instance */ transformers: Array&lt;Transformer&gt;; constructor(...transformers: Array&lt;Transformer&gt;) { this.transformers = transformers; } /** * Convert the CSS style key to a JSX style key * * @memberof Markup * @static * @private * @method toJSXKey * @param {string} key - CSS style key * @return {string} JSX style key * @example * Markup.toJSXKey('min-width'); // minWidth */ static toJSXKey(key: string): string { return (/^-ms-/.test(key) ? key.substr(1) : key).replace(/-(.)/g, (match, chr) =&gt; chr.toUpperCase()); } /** * Parse the specified inline style attribute value * * @memberof Markup * @static * @private * @method transformStyle * @param {Object} object - the object to perform replacements on */ static transformStyle(object: Object) { if (has(object, 'style')) { object.style = transform(object.style.split(';'), (result, style) =&gt; { const firstColon = style.indexOf(':'), key = style.substr(0, firstColon).trim(); if (key) { result[Markup.toJSXKey(key.toLowerCase())] = style.substr(firstColon + 1).trim(); } }, {}); } } /** * Renames specified attributes if present * * @memberof Markup * @static * @private * @method rename * @param {Object} object - the object to perform replacements on * @param {string} fromKey - a key to look for * @param {string} toKey - a key to rename to */ static rename(object: Object, fromKey: string, toKey: string) { if (has(object, fromKey)) { object[toKey] = object[fromKey]; delete object[fromKey]; } } /** * Converts a DOM Element to a React Element * * @memberof Markup * @static * @private * @method childToJSX * @param {CheerioElement} child - the DOM Element to convert to a React Element * @param {number} i - positional index of the element * @return {ReactElement} React Element */ static childToJSX(child: CheerioElement, i: number): any { const {name, attribs, children} = child; attribs.key = i; Markup.transformStyle(attribs); Markup.rename(attribs, 'for', 'htmlFor'); Markup.rename(attribs, 'class', 'className'); if ('input' === name) { Markup.rename(attribs, 'checked', 'defaultChecked'); Markup.rename(attribs, 'value', 'defaultValue'); } let childComponents = Markup.childrenToJSX(children); if ('textarea' === name &amp;&amp; childComponents.length) { attribs.defaultValue = childComponents[0]; childComponents = []; } return createElement(name, attribs, ...childComponents); } /** * Converts an array of DOM Elements to an array of React Elements * * @memberof Markup * @static * @private * @method childrenToJSX * @param {Array&lt;CheerioNode&gt;} children - the DOM Element to convert to a React element * @return {Array&lt;ReactElement&gt;} an array of React Elements */ static childrenToJSX(children: Array&lt;CheerioNode&gt; = []): Array&lt;any&gt; { return map(reject(children, ['type', 'comment']), (c, i) =&gt; 'text' === c.type ? c.data : Markup.childToJSX(c, i)); } /** * Recursively flattens `args` and combines string values. * * Can be used as a simple optimization step on the JSX children-to-be to simplify the resulting DOM structure by * joining adjacent text nodes together. * * @memberof Markup * @static * @method flatten * @param {...*} args - the input array * @return {Array&lt;*&gt;} the flattened result * @example * Markup.flatten('lorem ', ['ipsum ', ['dolor ', ['sit ', ['amet']]]]); // [&quot;lorem ipsum dolor sit amet&quot;] */ static flatten(...args: Array&lt;any&gt;): Array&lt;any&gt; { return transform(flattenDeep(args), (accumulator, value) =&gt; { const lastIndex = accumulator.length - 1; if (isString(value) &amp;&amp; isString(accumulator[lastIndex])) { accumulator[lastIndex] += value; } else { accumulator.push(value); } }, []); } /** * Runs the html string through an array of Transformer functions * * @memberof Markup * @instance * @private * @method transform * @param {string} html - an arbitrary HTML string * @return {string} a transformed string */ transform(html: string): string { return reduce(this.transformers, (result, transformer) =&gt; transformer(result), html); } /** * Converts an arbitrary HTML string to an array of React Elements * * @memberof Markup * @instance * @method htmlToJSX * @param {string} [html=&quot;&quot;] - an arbitrary HTML string * @return {Array&lt;ReactElement&gt;} an array of React Elements * @example * &lt;div&gt;{mark.htmlToJSX('Hello &lt;span&gt;world!&lt;/span&gt;')}&lt;/div&gt; */ htmlToJSX(html: string = ''): Array&lt;any&gt; { html = trim(html); return html ? Markup.childrenToJSX(load(this.transform(html)).root().toArray()[0].children) : []; } /** * Converts an arbitrary Markdown string to an HTML string * * @memberof Markup * @instance * @method markdownToHTML * @param {string} [markdown=&quot;&quot;] - an arbitrary Markdown string * @return {string} an HTML string * @example * mark.markdownToHTML('# Hello world!'); // &lt;h1&gt;Hello world!&lt;/h1&gt; */ markdownToHTML(markdown: string = ''): string { markdown = trim(markdown); return markdown ? trim(this.transform(marked(markdown))) : ''; } /** * Converts an arbitrary Markdown string to an array of React Elements * * @memberof Markup * @instance * @method markdownToJSX * @param {string} [markdown=&quot;&quot;] - an arbitrary Markdown string * @return {Array&lt;ReactElement&gt;} an array of React Elements * @example * &lt;div&gt;{mark.markdownToJSX('# Hello world!')}&lt;/div&gt; */ markdownToJSX(markdown: string = ''): Array&lt;any&gt; { markdown = trim(markdown); return markdown ? this.htmlToJSX(marked(markdown)) : []; } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"NativeProcess.js.html":{"id":"NativeProcess.js.html","title":"Source: NativeProcess.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: NativeProcess.js /* @flow */ import type {NativeProcessCallback} from './typedef'; import {spawn} from 'child_process'; import noop from 'lodash/noop'; /** * Encapsulates a {@link https://nodejs.org/api/child_process.html#child_process_class_childprocess ChildProcess} * instance of a `task` * * @class NativeProcess * @param {string} task - a process name * @example * import {NativeProcess} from 'webcompiler'; * * const mkdir = new NativeProcess('mkdir'); */ export class NativeProcess { /** * a process name * * @member {string} task * @memberof NativeProcess * @private * @instance */ task: string; /** * a ChildProcess instance * * @member {ChildProcess} proc * @memberof NativeProcess * @private * @instance */ proc: any; constructor(task: string) { this.task = task; } /** * Execute the command * * @memberof NativeProcess * @instance * @method run * @param {NativeProcessCallback} [callback=function () {}] - a callback function * @param {Array&lt;string&gt;} [args=[]] - an array of arguments to pass to the process * @param {Object} [opts={}] - a configuration object for the process * @return {void} * @example * mkdir.run(error =&gt; { * if (error) { * return console.error(error); * } * // created a directory named &quot;example&quot; in cwd * }, ['example']); */ run(callback: NativeProcessCallback = noop, args: Array&lt;string&gt; = [], opts: Object = {}) { if (this.proc) { return callback('Still working...', ''); } this.proc = spawn(this.task, args, opts); let stdout = '', stderr = ''; if (this.proc.stdout) { this.proc.stdout.on('data', data =&gt; { stdout += data; }); } if (this.proc.stderr) { this.proc.stderr.on('data', data =&gt; { stderr += data; }); } this.proc.on('error', error =&gt; { stderr += error.toString(); }); this.proc.on('close', code =&gt; { this.proc = null; callback(code ? stderr : null, stdout); }); } /** * Kills the process if any is running * * @memberof NativeProcess * @instance * @method kill * @example * someEpensiveProcess.kill(); */ kill() { if (this.proc) { this.proc.kill(); this.proc = null; } } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"SASS.js.html":{"id":"SASS.js.html","title":"Source: SASS.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: SASS.js /* @flow */ import {SASSCompiler} from './SASSCompiler'; import {SASSLint} from './SASSLint'; import noop from 'lodash/noop'; /** * SASS compilation tools * * @class SASS * @param {boolean} [compress=true] - if true `Compiler#optimize` will gzip compress the data * @param {Array&lt;string&gt;} [includePaths=[]] - an array of additional include paths * @param {Array&lt;string&gt;} [excludeLinter=[]] - names of linters to exclude * @param {Object} [importOnceOptions={}] - an object that lets you override default importOnce resolver * configuration * @example * import {SASS} from 'webcompiler'; * * const sass = new SASS(); */ export class SASS { /** * SCSS compiler * * @member {SASSCompiler} compiler * @memberof SASS * @private * @instance */ compiler: SASSCompiler; /** * SCSS linter * * @member {SASSLint} linter * @memberof SASS * @private * @instance */ linter: SASSLint; constructor(compress: boolean = true, includePaths: Array&lt;string&gt; = [], excludeLinter: Array&lt;string&gt; = [], importOnceOptions: Object = {}) { this.compiler = new SASSCompiler(compress, includePaths, importOnceOptions); this.linter = new SASSLint(...excludeLinter); } /** * Performs linting * * @memberof SASS * @instance * @method lint * @param {Array&lt;string&gt;} paths - an array of paths to lint * @param {Function} callback - a callback function * @example * sass.lint(['/path/to/the/input/file.scss', '/lint/this/directory/too'], () =&gt; { * // successfully linted * }); */ lint(paths: Array&lt;string&gt;, callback: () =&gt; void) { this.linter.run(paths, linterErr =&gt; { if (linterErr) { return console.error(linterErr); } callback(); }); } /** * Wraps {@link SASSCompiler#fe} to add linting * * @memberof SASS * @instance * @method fe * @param {string} inPath - the input path * @param {string} outPath - the output path * @param {Array&lt;string&gt;} [lintPaths=[]] - an array of paths to files/directories to lint * @param {Function} [callback=function () {}] - a callback function * @return {void} * @example * compiler.fe('/path/to/an/input/file.js', '/path/to/the/output/file.js', ['/lint/this/directory/too'], () =&gt; { * // the code has passed all the checks and has been compiled successfully * }); */ fe(inPath: string, outPath: string, lintPaths: Array&lt;string&gt; = [], callback: () =&gt; void = noop) { this.lint(lintPaths.concat([inPath]), () =&gt; { this.compiler.fe(inPath, outPath, callback); }); } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"SASSCompiler.js.html":{"id":"SASSCompiler.js.html","title":"Source: SASSCompiler.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: SASSCompiler.js /* @flow */ import type {ProgramData, ProgramDataCallback} from './typedef'; import {Compiler} from './Compiler'; import {render} from 'node-sass'; import importer from 'node-sass-import-once'; import postcss from 'postcss'; import autoprefixer from 'autoprefixer'; import forEach from 'lodash/forEach'; import noop from 'lodash/noop'; const precision = 8, importOnceDefaults = {index: true, css: false, bower: false}, defaultIncludePaths = ['node_modules/bootstrap-sass/assets/stylesheets', 'node_modules']; /** * A SASS compiler * * @class SASSCompiler * @extends Compiler * @param {boolean} [compress=true] - if true `Compiler#optimize` will gzip compress the data * @param {Array&lt;string&gt;} [includePaths=[]] - an array of additional include paths * @param {Object} [importOnceOptions={}] - an object that lets you override default importOnce resolver * configuration * @example * import {SASSCompiler} from 'webcompiler'; * * const compiler = new SASSCompiler(); */ export class SASSCompiler extends Compiler { /** * an array of paths to search for an scss file in if it's not found in cwd * * @member {Array&lt;string&gt;} includePaths * @memberof SASSCompiler * @private * @instance */ includePaths: Array&lt;string&gt;; /** * importOnce resolver configuration * * @member {Object} importOnce * @memberof SASSCompiler * @private * @instance */ importOnce: Object; constructor(compress: boolean = true, includePaths: Array&lt;string&gt; = [], importOnceOptions: Object = {}) { super(compress); this.includePaths = defaultIncludePaths.concat(includePaths); this.importOnce = {...importOnceDefaults, ...importOnceOptions}; } /** * Auto-prefixes the compiled code * * @memberOf SASSCompiler * @static * @method autoprefix * @param {string} path - a path to the file * @param {ProgramData} data - the actual program data to auto-prefix * @param {ProgramDataCallback} callback - a callback function * @example * SASSCompiler.autoprefix('/path/to/the/output/file.css', data, result =&gt; { * // successfully added the vendor prefixes * }); */ static autoprefix(path: string, data: ProgramData, callback: ProgramDataCallback) { postcss([autoprefixer]).process(data.code, { from: path, to: path, map: {prev: data.map} }).then(result =&gt; { const warnings = result.warnings(); if (warnings.length) { return forEach(warnings, warning =&gt; { console.error(warning.toString()); }); } callback({code: result.css, map: JSON.stringify(result.map)}); }); } /** * Compiles, auto-prefixes and optionally minifies and g-zips in the production mode * * @memberof SASSCompiler * @instance * @method fe * @param {string} inPath - a full system path to the input file * @param {string} outPath - a full system path to the output file * @param {Function} [callback=function () {}] - a callback function * @example * compiler.fe('/path/to/the/input/file.scss', '/path/to/the/output/file.css', () =&gt; { * // compiled successfully * }); */ fe(inPath: string, outPath: string, callback: () =&gt; void = noop) { render({ file: inPath, outFile: outPath, importer, precision, importOnce: this.importOnce, includePaths: this.includePaths, sourceMap: true, sourceMapContents: true, outputStyle: this.isProduction ? 'compressed' : 'nested' }, (error, result) =&gt; { if (error) { return console.log( '\\x1b[41mSASS error\\x1b[0m &quot;\\x1b[33m%s\\x1b[0m&quot; in \\x1b[36m%s\\x1b[0m on \\x1b[35m%s:%s\\x1b[0m', error.message, error.file, error.line, error.column); } SASSCompiler.autoprefix(outPath, {code: result.css, map: result.map.toString()}, data =&gt; { this.optimize(inPath, outPath, data, callback); }); }); } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"SASSLint.js.html":{"id":"SASSLint.js.html","title":"Source: SASSLint.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: SASSLint.js /* @flow */ import type {NativeProcessCallback} from './typedef'; import {NativeProcess} from './NativeProcess'; import {join} from 'path'; const config = join(__dirname, '..', 'config', 'scsslint.yml'); /** * A SASS linter * * @class SASSLint * @param {...string} excludeLinter - names of linters to exclude * @example * import {SASSLint} from 'webcompiler'; * import {join} from 'path'; * * const linter = new SASSLint(); */ export class SASSLint { /** * a comma-separated list of linter names to exclude from execution * * @member {string} excludeLinter * @memberof SASSLint * @private * @instance */ excludeLinter: string; /** * a NativeProcess instance for scss-lint * * @member {NativeProcess} proc * @memberof SASSLint * @private * @instance */ proc: NativeProcess; constructor(...excludeLinter: Array&lt;string&gt;) { this.excludeLinter = excludeLinter.join(','); this.proc = new NativeProcess('scss-lint'); } /** * Execute the linter * * @memberof SASSLint * @instance * @method run * @param {Array&lt;string&gt;} paths - an array of paths to files/directories to lint * @param {Function} callback - a callback function, accepts 1 argument: an error message or null * @example * // lint &quot;style.scss&quot; as well as the entire contents of the &quot;sass&quot; directory * linter.run([join(__dirname, 'style.scss'), join(__dirname, 'sass')], error =&gt; { * if (error) { * return console.error(error); * } * // there were no linting errors * }); */ run(paths: Array&lt;string&gt;, callback: NativeProcessCallback) { const args = paths.concat(['-c', config]); if (this.excludeLinter) { args.push('-x', this.excludeLinter); } this.proc.run(callback, args); } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"watch.js.html":{"id":"watch.js.html","title":"Source: watch.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: watch.js /* @flow */ import {Client} from 'fb-watchman'; const client = new Client(), ALPHANUMERIC_BASE = 36; /** * Using the Facebook Watchman, watches the directory `dir` for changes of files with extension `type` and runs * `callback` when a change is detected. * * This watcher's only goal is performance, hence the simplicity. * * @function watch * @param {string} dir - a full system path to a directory to watch * @param {string} type - a file extension * @param {Function} callback - a callback function * @see {@link https://facebook.github.io/watchman/ Watchman} * @example * import {watch} from 'webcompiler'; * import {join} from 'path'; * * watch(join(__dirname, 'src'), 'js', someFunction); */ export function watch(dir: string, type: string, callback: () =&gt; void) { const subscription = Date.now().toString(ALPHANUMERIC_BASE); client.capabilityCheck({}, capabilityErr =&gt; { if (capabilityErr) { console.error(capabilityErr); return; } client.command(['watch-project', dir], (watchErr, watchResp) =&gt; { const watcher = watchResp.watch; if (watchErr) { console.error('Error initiating watch:', watchErr); return; } if (watchResp.warning) { console.log('warning: ', watchResp.warning); } client.command(['clock', watcher], (clockErr, clockResp) =&gt; { if (clockErr) { console.error('Failed to query clock:', clockErr); return; } client.command(['subscribe', watcher, subscription, { expression: ['suffix', type], since: clockResp.clock }], subscribeErr =&gt; { if (subscribeErr) { console.error('failed to subscribe: ', subscribeErr); } }); client.on('subscription', subscriptionResp =&gt; { if (subscription === subscriptionResp.subscription) { callback(); } }); }); }); }); } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"yaml.js.html":{"id":"yaml.js.html","title":"Source: yaml.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: yaml.js /* @flow */ import type {ObjectOrErrorCallback} from './typedef'; import {safeLoad} from 'js-yaml'; import {readFileSync} from 'fs'; /** * Read the contents of a YAML file * * @function yaml * @param {string} filename - the full system path to a YAML file * @param {ObjectOrErrorCallback} callback - a callback function * @example * import {yaml} from 'webcompiler'; * import {join} from 'path'; * * yaml(join(__dirname, 'config', 'config.yml'), (error, data) =&gt; { * if (error) { * return console.error(error); * } * // the parsed config object * }); */ export function yaml(filename: string, callback: ObjectOrErrorCallback) { try { const yamlString: string = readFileSync(filename, 'utf8'); callback(null, safeLoad(yamlString, {filename})); } catch (e) { callback(e.toString(), {}); } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"global.html":{"id":"global.html","title":"Global","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Global Methods watch(dir, type, callback) Using the Facebook Watchman, watches the directory dir for changes of files with extension type and runs callback when a change is detected. This watcher's only goal is performance, hence the simplicity. Parameters: Name Type Description dir string a full system path to a directory to watch type string a file extension callback function a callback function Source: watch.js, line 8 See: Watchman Example import {watch} from 'webcompiler'; import {join} from 'path'; watch(join(__dirname, 'src'), 'js', someFunction); yaml(filename, callback) Read the contents of a YAML file Parameters: Name Type Description filename string the full system path to a YAML file callback ObjectOrErrorCallback a callback function Source: yaml.js, line 7 Example import {yaml} from 'webcompiler'; import {join} from 'path'; yaml(join(__dirname, 'config', 'config.yml'), (error, data) =&gt; { if (error) { return console.error(error); } // the parsed config object }); Type Definitions CheerioElement A dumbed down representation of a DOM Element Type: Object Properties: Name Type Argument Description type string &quot;tag&quot; name string the tag name (e.g. &quot;div&quot;) attribs Object the tag attributes (e.g. {style: 'min-width:50px'}) children Array.&lt;CheerioNode&gt; &lt;optional&gt; an array of child nodes next CheerioNode &lt;optional&gt; the next sibling node prev CheerioNode &lt;optional&gt; the previous sibling node parent CheerioElement &lt;optional&gt; the parent element Source: typedef.js, line 32 CheerioNode A dumbed down representation of a DOM Node Type: Object Properties: Name Type Description type string either &quot;comment&quot;, &quot;text&quot; or &quot;tag&quot; Source: typedef.js, line 24 CheerioText A dumbed down representation of a DOM Text or a Comment Nodes Type: Object Properties: Name Type Argument Description type string either &quot;text&quot; or &quot;comment&quot; data string the textual content of the node next CheerioNode &lt;optional&gt; the next sibling node prev CheerioNode &lt;optional&gt; the previous sibling node parent CheerioElement &lt;optional&gt; the parent element Source: typedef.js, line 47 DocumentationConfig Documentation generator configuration object Type: Object Properties: Name Type Argument Default Description inputDir string &lt;optional&gt; &quot;src&quot; the input application code directory outputDir string &lt;optional&gt; &quot;docs&quot; the output directory for the generated documentation readMe string &lt;optional&gt; &quot;README.md&quot; the documentation &quot;homepage&quot; (README.md file) template string &lt;optional&gt; &quot;node_modules/ink-docstrap/template&quot; a full system path to a valid JSDoc3 template directory jsdocConfig string &lt;optional&gt; &quot;&lt;webcompiler root&gt;/config/jsdoc.json&quot; a full system path to a JSDoc3 configuration file Source: typedef.js, line 59 FileCallback(file) Parameters: Name Type Description file string a full system path to a file Source: typedef.js, line 78 JSLintCallback(errors) Parameters: Name Type Argument Description errors Array.&lt;JSLintError&gt; &lt;optional&gt; a collection of error objects Source: typedef.js, line 90 JSLintError The JavaScript linting error object Type: Object Properties: Name Type Argument Description message string the error message ruleId string &lt;optional&gt; the relative linting rule filePath string the path to a file line number the offending line number column number the offending column number Source: typedef.js, line 12 NativeProcessCallback(stderr, stdout) Parameters: Name Type Argument Description stderr string &lt;optional&gt; an error message stdout string the process output Source: typedef.js, line 96 NullableFileCallback(file) Parameters: Name Type Argument Description file string &lt;optional&gt; a full system path to a file Source: typedef.js, line 84 ObjectOrErrorCallback(error, result) Parameters: Name Type Argument Description error string &lt;optional&gt; an error message result Object the resulting object Source: typedef.js, line 103 ProgramData Processed application code with source maps Type: Object Properties: Name Type Description code string program code map string source map json string Source: typedef.js, line 3 ProgramDataCallback(data) Parameters: Name Type Description data ProgramData the program data Source: typedef.js, line 72 Transformer(input) Must be a pure function, always return the same value given the same input, must be side-effect free and not depend on other replacers executing before it. If provided with a result of its own previous execution, must return it unchanged. Parameters: Name Type Description input string a transformed string Source: typedef.js, line 110 Returns: transformed output Type string × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"classes.list.html":{"id":"classes.list.html","title":"Classes","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Classes Classes Compiler DevServer Documentation JS JSCompiler JSLint Markup NativeProcess SASS SASSCompiler SASSLint × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"index.html":{"id":"index.html","title":"Index","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml webcompilerLint, type-check, compile, package and gzip JavaScript (ES6 + Flow static types + JSX), for the browser as well as NodeJS; lint, compile, auto-prefix, minify and gzip SASS. Project Home | API Docs | Discord Webpack is an amazing tool, however it requires a lot of boilerplate to properly setup and configure, especially when you use it on more than one project. ESLint is constantly updated, new rules are added, APIs are changed. Properly configuring it is a routine and time consuming task, which is completely impractical to perform on each project separately. APIs are sometimes changed without any change in functionality (e.g. Babel 5 vs Babel 6). This project aims to abstract all of those problems out of the development of applications. Prerequisites Facebook Flow SCSS-Lint Watchman A note about Facebook FlowFacebook Flow is a static analysis tool used to check your JavaScript code for possible errors at compile time. It is very smart at understanding your program code, however you should not rely on it being smart enough to just understand your external dependencies too. It can do that, the problem is that a typical NodeJS project can contain hundreds NPM modules, with thousands of JavaScript files. It is a very complicated task, even for a tool that smart, to parse all of them and stay performant enough to not only be usable but useful as well. Which is why it must not be allowed to even try to understand any files that reside in a node_modules directory. Interface Files must be used instead. You can find examples of such interface files, as well as the interface file for the tool itself, in the interfaces directory. Installationnpm i webcompiler --save-devProduction buildsBy default all compilation is done in development mode. If you wish to compile for production just set the NODE_ENV environment variable to &quot;production&quot;, the following additional actions will be performed by the compiler: advanced compilation time optimizations minification (only fe in production mode) g-zip compression (only fe in production mode) Important!The resulting JavaScript and CSS files from fe in production mode are gzip compressed for performance (see Gzip Components), so make sure to provide a &quot;Content-Encoding&quot; header to the browser (e.g. res.setHeader('Content-Encoding', 'gzip');). × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"Compiler.html":{"id":"Compiler.html","title":"Class: Compiler","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Class: Compiler Compiler &lt;abstract&gt; new Compiler(compress) The base compiler class Parameters: Name Type Argument Default Description compress boolean &lt;optional&gt; true if true Compiler#optimize will gzip compress the data in production mode Source: Compiler.js, line 11 Members &lt;readonly&gt; isProduction :boolean True if the NODE_ENV environment variable is equal to production. Caution: modifying it's value directly may lead to unexpected results Type: boolean Source: Compiler.js, line 19 Methods &lt;static&gt; done(inPath, callback) Executed when the compilation is complete Parameters: Name Type Description inPath string the input path callback function a callback function Source: Compiler.js, line 46 Example Compiler.done('/path/to/an/input/file', callback); &lt;static&gt; fsWrite(path, data, callback) Writes the data to disk Parameters: Name Type Description path string the output path data ProgramData the data to write callback function a callback function Source: Compiler.js, line 82 Example Compiler.fsWrite('/path/to/an/output/file', data, callback); &lt;static&gt; gzip(data, callback) G-zips the compiled code Parameters: Name Type Description data ProgramData the actual program data to auto-prefix callback ProgramDataCallback a callback function Source: Compiler.js, line 133 Example Compiler.gzip(data, callback); &lt;static&gt; mkdir(path, callback) Recursively creates a directory containing a file specified by path. Parameters: Name Type Description path string a path to a file callback function a callback function Source: Compiler.js, line 113 Example Compiler.mkdir('/path/to/a/file', callback); &lt;protected&gt; optimize(inPath, outPath, data, callback) G-zips the program if necessary and writes the results to disk. Parameters: Name Type Description inPath string the input path outPath string the output path data ProgramData processed application code with source maps callback function a callback function Source: Compiler.js, line 153 Example compiler.optimize('/path/to/an/input/file', '/path/to/the/output/file', data, callback); × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"DevServer.html":{"id":"DevServer.html","title":"Class: DevServer","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Class: DevServer DevServer new DevServer(script, style, devDir, port, react) A lightweight development server that rapidly recompiles the JavaScript and SASS files when they are edited and updates the page. Utilizes the Webpack development server. Includes react hot loader to further optimize the development process of the React applications. Please install and enable the LiveReload browser extension for the CSS reloading to work. Parameters: Name Type Argument Default Description script string a full system path to a JavaScript file style string a full system path to a SASS file devDir string a full system path to a directory in which to put any compiled development resources port number &lt;optional&gt; 3000 a port at which to start the dev server react boolean &lt;optional&gt; true false to disable the react hot loader plugin Source: DevServer.js, line 13 See: webpack-dev-server React Hot Loader Example import {DevServer} from 'webcompiler'; import {join} from 'path'; const rootDir = join(__dirname, '..'), devDir = join(rootDir, 'development'), server = new DevServer(join(devDir, 'script.js'), join(devDir, 'app.scss'), devDir); server.run(rootDir); // now navigate to http://localhost:3000 using your favorite browser ( preferably Chrome :) ) Methods run(watchDir) Starts the Webpack development server, compiles SASS and starts watching for file changes Parameters: Name Type Description watchDir string the directory in which to watch for the changes in the SASS files Source: DevServer.js, line 182 Example server.run('/path/to/some/directory'); watchJS() Starts the Webpack development server Source: DevServer.js, line 162 Example server.watchJS(); watchSASS(watchDir) Compile SASS and start watching for file changes Parameters: Name Type Description watchDir string the directory in which to watch for the changes in the SASS files Source: DevServer.js, line 146 Example server.watchSASS('/path/to/some/directory'); × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"Documentation.html":{"id":"Documentation.html","title":"Class: Documentation","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Class: Documentation Documentation new Documentation(config) Generates API documentation The default JSDoc plugin specified in jsdocConfig strips out all of the code from a file while retaining newlines (unlike the built in commentsOnly plugin that ships with JSDoc3). That way: line numbers are preserved in the source view you don't need to use a pre-compiler, you will always see the same code as you wrote in the docs source view since JSDoc only sees comments you can use any code syntax you like - ES2015, ES7, JSX, it doesn't even have to be JavaScript. The markdown plugin is also included by default. Parameters: Name Type Argument Default Description config DocumentationConfig &lt;optional&gt; {} a configuration object Source: Documentation.js, line 19 Example import {Documentation} from 'webcompiler'; const docs = new Documentation(); Methods run(callback) Generate the documentation Parameters: Name Type Argument Default Description callback function &lt;optional&gt; function () {} a callback function Source: Documentation.js, line 128 Returns: Type void Example docs.run(() =&gt; { // generated the API documentation }); × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"JS.html":{"id":"JS.html","title":"Class: JS","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Class: JS JS new JS(compress, babelOptions, lintRules) JavaScript compilation tools Parameters: Name Type Argument Default Description compress boolean &lt;optional&gt; true if true Compiler#optimize will gzip compress the data babelOptions Object &lt;optional&gt; {} allows to override the default Babel options lintRules Object &lt;optional&gt; {} allows to override the default linting rules Source: JS.js, line 9 Example import {JS} from 'webcompiler'; const js = new JS(); Methods be(inPath, outPath, lintPaths, callback) Wraps JSCompiler#be to add static analysis and linting Parameters: Name Type Argument Default Description inPath string the input path outPath string the output path lintPaths Array.&lt;string&gt; &lt;optional&gt; [] an array of paths to files/directories to lint callback function &lt;optional&gt; function () {} a callback function Source: JS.js, line 130 Returns: Type void Example compiler.be('/path/to/an/input/file.js', '/path/to/the/output/file.js', ['/lint/this/directory/too'], () =&gt; { // the code has passed all the checks and has been compiled successfully }); fe(inPath, outPath, lintPaths, callback) Wraps JSCompiler#fe to add static analysis and linting Parameters: Name Type Argument Default Description inPath string the input path outPath string the output path lintPaths Array.&lt;string&gt; &lt;optional&gt; [] an array of paths to files/directories to lint callback function &lt;optional&gt; function () {} a callback function Source: JS.js, line 152 Returns: Type void Example compiler.fe('/path/to/an/input/file.js', '/path/to/the/output/file.js', ['/lint/this/directory/too'], () =&gt; { // the code has passed all the checks and has been compiled successfully }); lint(paths, callback) Performs linting Parameters: Name Type Description paths Array.&lt;string&gt; an array of paths to files/directories to lint callback function a callback function, invoked only when successfully linted Source: JS.js, line 82 Example js.lint(['/path/to/the/input/file.js', '/lint/this/directory/too'], () =&gt; { // successfully linted }); typecheck(callback) Performs static analysis Parameters: Name Type Description callback function a callback function, invoked only when successfully typechecked Source: JS.js, line 58 Example js.typecheck(() =&gt; { // successfully typechecked }); × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"JSCompiler.html":{"id":"JSCompiler.html","title":"Class: JSCompiler","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Class: JSCompiler JSCompiler new JSCompiler(compress, options) A JavaScript compiler Parameters: Name Type Argument Default Description compress boolean &lt;optional&gt; true if true Compiler#optimize will gzip compress the data options Object &lt;optional&gt; {} allows to override the default Babel options Source: JSCompiler.js, line 24 Example import {JSCompiler} from 'webcompiler'; const compiler = new JSCompiler(); Extends Compiler Members &lt;readonly&gt; isProduction :boolean True if the NODE_ENV environment variable is equal to production. Caution: modifying it's value directly may lead to unexpected results Type: boolean Inherited From: Compiler#isProduction Source: Compiler.js, line 19 Methods be(inPath, outPath, callback) Compiles a JavaScript file or a directory for the back end. Non-JavaScript files are simply copied over. Parameters: Name Type Argument Default Description inPath string the input path outPath string the output path callback function &lt;optional&gt; function () {} a callback function Source: JSCompiler.js, line 185 Returns: Type void Example compiler.be('/path/to/an/input/file.js', '/path/to/the/output/file.js', callback); fe(inPath, outPath, callback) Compiles, bundles (in production mode also minifies and g-zips) a JavaScript file for the front end. Parameters: Name Type Argument Default Description inPath string the input path outPath string the output path callback function &lt;optional&gt; function () {} a callback function Source: JSCompiler.js, line 209 Example compiler.fe('/path/to/an/input/file.js', '/path/to/the/output/file.js', callback); &lt;protected&gt; optimize(inPath, outPath, data, callback) G-zips the program if necessary and writes the results to disk. Parameters: Name Type Description inPath string the input path outPath string the output path data ProgramData processed application code with source maps callback function a callback function Inherited From: Compiler#optimize Source: Compiler.js, line 153 Example compiler.optimize('/path/to/an/input/file', '/path/to/the/output/file', data, callback); × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"JSLint.html":{"id":"JSLint.html","title":"Class: JSLint","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Class: JSLint JSLint new JSLint(rules) A JavaScript linter Parameters: Name Type Argument Default Description rules Object &lt;optional&gt; {} an object that lets you override default linting rules Source: JSLint.js, line 10 Example import {JSLint} from 'webcompiler'; import {join} from 'path'; const linter = new JSLint(); Methods run(paths, callback) Execute the linter Parameters: Name Type Description paths Array.&lt;string&gt; an array of paths to files/directories to lint callback JSLintCallback a callback function, accepts 1 argument: an array of error objects or null Source: JSLint.js, line 36 Example // lint &quot;index.js&quot; as well as the entire contents of the &quot;src&quot; directory linter.run([join(__dirname, 'index.js'), join(__dirname, 'src')], function (err) { if (err) { return e.forEach(e =&gt; { console.log('\\x1b[41mESLint error\\x1b[0m &quot;\\x1b[33m%s%s\\x1b[0m&quot; in \\x1b[36m%s\\x1b[0m on \\x1b[35m%s:%s\\x1b[0m', e.message, e.ruleId ? ` (${e.ruleId})` : '', e.filePath, e.line, e.column); }); } // there were no linting errors }); × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"Markup.html":{"id":"Markup.html","title":"Class: Markup","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Class: Markup Markup new Markup(transformers) Allows to easily and efficiently convert text from Markdown to HTML and from HTML to a collection of React Elements that can be used directly in a JSX expression. Whenever an HTML string is involved, runs it through an array of Transformer functions. Parameters: Name Type Argument Description transformers Transformer &lt;repeatable&gt; transformers to initialize with Source: Markup.js, line 18 Example import {Markup} from 'webcompiler'; const mark = new Markup(); Methods &lt;static&gt; flatten(args) Recursively flattens args and combines string values. Can be used as a simple optimization step on the JSX children-to-be to simplify the resulting DOM structure by joining adjacent text nodes together. Parameters: Name Type Argument Description args * &lt;repeatable&gt; the input array Source: Markup.js, line 149 Returns: the flattened result Type Array.&lt;*&gt; Example Markup.flatten('lorem ', ['ipsum ', ['dolor ', ['sit ', ['amet']]]]); // [&quot;lorem ipsum dolor sit amet&quot;] htmlToJSX(html) Converts an arbitrary HTML string to an array of React Elements Parameters: Name Type Argument Default Description html string &lt;optional&gt; &quot;&quot; an arbitrary HTML string Source: Markup.js, line 189 Returns: an array of React Elements Type Array.&lt;ReactElement&gt; Example &lt;div&gt;{mark.htmlToJSX('Hello &lt;span&gt;world!&lt;/span&gt;')}&lt;/div&gt; markdownToHTML(markdown) Converts an arbitrary Markdown string to an HTML string Parameters: Name Type Argument Default Description markdown string &lt;optional&gt; &quot;&quot; an arbitrary Markdown string Source: Markup.js, line 205 Returns: an HTML string Type string Example mark.markdownToHTML('# Hello world!'); // &lt;h1&gt;Hello world!&lt;/h1&gt; markdownToJSX(markdown) Converts an arbitrary Markdown string to an array of React Elements Parameters: Name Type Argument Default Description markdown string &lt;optional&gt; &quot;&quot; an arbitrary Markdown string Source: Markup.js, line 221 Returns: an array of React Elements Type Array.&lt;ReactElement&gt; Example &lt;div&gt;{mark.markdownToJSX('# Hello world!')}&lt;/div&gt; × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"NativeProcess.html":{"id":"NativeProcess.html","title":"Class: NativeProcess","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Class: NativeProcess NativeProcess new NativeProcess(task) Encapsulates a ChildProcess instance of a task Parameters: Name Type Description task string a process name Source: NativeProcess.js, line 7 Example import {NativeProcess} from 'webcompiler'; const mkdir = new NativeProcess('mkdir'); Methods kill() Kills the process if any is running Source: NativeProcess.js, line 88 Example someEpensiveProcess.kill(); run(callback, args, opts) Execute the command Parameters: Name Type Argument Default Description callback NativeProcessCallback &lt;optional&gt; function () {} a callback function args Array.&lt;string&gt; &lt;optional&gt; [] an array of arguments to pass to the process opts Object &lt;optional&gt; {} a configuration object for the process Source: NativeProcess.js, line 43 Returns: Type void Example mkdir.run(error =&gt; { if (error) { return console.error(error); } // created a directory named &quot;example&quot; in cwd }, ['example']); × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"SASS.html":{"id":"SASS.html","title":"Class: SASS","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Class: SASS SASS new SASS(compress, includePaths, excludeLinter, importOnceOptions) SASS compilation tools Parameters: Name Type Argument Default Description compress boolean &lt;optional&gt; true if true Compiler#optimize will gzip compress the data includePaths Array.&lt;string&gt; &lt;optional&gt; [] an array of additional include paths excludeLinter Array.&lt;string&gt; &lt;optional&gt; [] names of linters to exclude importOnceOptions Object &lt;optional&gt; {} an object that lets you override default importOnce resolver configuration Source: SASS.js, line 7 Example import {SASS} from 'webcompiler'; const sass = new SASS(); Methods fe(inPath, outPath, lintPaths, callback) Wraps SASSCompiler#fe to add linting Parameters: Name Type Argument Default Description inPath string the input path outPath string the output path lintPaths Array.&lt;string&gt; &lt;optional&gt; [] an array of paths to files/directories to lint callback function &lt;optional&gt; function () {} a callback function Source: SASS.js, line 70 Returns: Type void Example compiler.fe('/path/to/an/input/file.js', '/path/to/the/output/file.js', ['/lint/this/directory/too'], () =&gt; { // the code has passed all the checks and has been compiled successfully }); lint(paths, callback) Performs linting Parameters: Name Type Description paths Array.&lt;string&gt; an array of paths to lint callback function a callback function Source: SASS.js, line 48 Example sass.lint(['/path/to/the/input/file.scss', '/lint/this/directory/too'], () =&gt; { // successfully linted }); × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"SASSCompiler.html":{"id":"SASSCompiler.html","title":"Class: SASSCompiler","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Class: SASSCompiler SASSCompiler new SASSCompiler(compress, includePaths, importOnceOptions) A SASS compiler Parameters: Name Type Argument Default Description compress boolean &lt;optional&gt; true if true Compiler#optimize will gzip compress the data includePaths Array.&lt;string&gt; &lt;optional&gt; [] an array of additional include paths importOnceOptions Object &lt;optional&gt; {} an object that lets you override default importOnce resolver configuration Source: SASSCompiler.js, line 16 Example import {SASSCompiler} from 'webcompiler'; const compiler = new SASSCompiler(); Extends Compiler Members &lt;readonly&gt; isProduction :boolean True if the NODE_ENV environment variable is equal to production. Caution: modifying it's value directly may lead to unexpected results Type: boolean Inherited From: Compiler#isProduction Source: Compiler.js, line 19 Methods &lt;static&gt; autoprefix(path, data, callback) Auto-prefixes the compiled code Parameters: Name Type Description path string a path to the file data ProgramData the actual program data to auto-prefix callback ProgramDataCallback a callback function Source: SASSCompiler.js, line 57 Example SASSCompiler.autoprefix('/path/to/the/output/file.css', data, result =&gt; { // successfully added the vendor prefixes }); fe(inPath, outPath, callback) Compiles, auto-prefixes and optionally minifies and g-zips in the production mode Parameters: Name Type Argument Default Description inPath string a full system path to the input file outPath string a full system path to the output file callback function &lt;optional&gt; function () {} a callback function Source: SASSCompiler.js, line 88 Example compiler.fe('/path/to/the/input/file.scss', '/path/to/the/output/file.css', () =&gt; { // compiled successfully }); &lt;protected&gt; optimize(inPath, outPath, data, callback) G-zips the program if necessary and writes the results to disk. Parameters: Name Type Description inPath string the input path outPath string the output path data ProgramData processed application code with source maps callback function a callback function Inherited From: Compiler#optimize Source: Compiler.js, line 153 Example compiler.optimize('/path/to/an/input/file', '/path/to/the/output/file', data, callback); × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"SASSLint.html":{"id":"SASSLint.html","title":"Class: SASSLint","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Class: SASSLint SASSLint new SASSLint(excludeLinter) A SASS linter Parameters: Name Type Argument Description excludeLinter string &lt;repeatable&gt; names of linters to exclude Source: SASSLint.js, line 9 Example import {SASSLint} from 'webcompiler'; import {join} from 'path'; const linter = new SASSLint(); Methods run(paths, callback) Execute the linter Parameters: Name Type Description paths Array.&lt;string&gt; an array of paths to files/directories to lint callback function a callback function, accepts 1 argument: an error message or null Source: SASSLint.js, line 46 Example // lint &quot;style.scss&quot; as well as the entire contents of the &quot;sass&quot; directory linter.run([join(__dirname, 'style.scss'), join(__dirname, 'sass')], error =&gt; { if (error) { return console.error(error); } // there were no linting errors }); × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "}}
+    {"typedef.js.html":{"id":"typedef.js.html","title":"Source: typedef.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: typedef.js /* @flow */ /** * Processed application code with source maps * * @typedef {Object} ProgramData * @property {string} code - program code * @property {string} map - source map json string */ export type ProgramData = {code: string, map: string}; /** * The JavaScript linting error object * * @typedef {Object} JSLintError * @property {string} message - the error message * @property {string} [ruleId] - the relative linting rule * @property {string} filePath - the path to a file * @property {number} line - the offending line number * @property {number} column - the offending column number */ export type JSLintError = {message: string, ruleId?: string, filePath: string, line: number, column: number}; /** * A dumbed down representation of a DOM Node * * @typedef {Object} CheerioNode * @property {string} type - either &quot;comment&quot;, &quot;text&quot; or &quot;tag&quot; */ export type CheerioNode = {type: string}; /** * A dumbed down representation of a DOM Element * * @typedef {Object} CheerioElement * @property {string} type - &quot;tag&quot; * @property {string} name - the tag name (e.g. &quot;div&quot;) * @property {Object} attribs - the tag attributes (e.g. {style: 'min-width:50px'}) * @property {Array&lt;CheerioNode&gt;} [children] - an array of child nodes * @property {CheerioNode} [next] - the next sibling node * @property {CheerioNode} [prev] - the previous sibling node * @property {CheerioElement} [parent] - the parent element */ export type CheerioElement = {type: string, name: string, attribs: Object, children?: Array&lt;CheerioNode&gt;, next: ?CheerioNode, prev: ?CheerioNode, parent: ?CheerioElement}; /** * A dumbed down representation of a DOM Text or a Comment Nodes * * @typedef {Object} CheerioText * @property {string} type - either &quot;text&quot; or &quot;comment&quot; * @property {string} data - the textual content of the node * @property {CheerioNode} [next] - the next sibling node * @property {CheerioNode} [prev] - the previous sibling node * @property {CheerioElement} [parent] - the parent element */ export type CheerioText = {type: string, data: string, next: ?CheerioNode, prev: ?CheerioNode, parent: ?CheerioElement}; /** * Documentation generator configuration object * * @typedef {Object} DocumentationConfig * @property {string} [inputDir=&quot;src&quot;] - the input application code directory * @property {string} [outputDir=&quot;docs&quot;] - the output directory for the generated documentation * @property {string} [readMe=&quot;README.md&quot;] - the documentation &quot;homepage&quot; (README.md file) * @property {string} [template=&quot;node_modules/ink-docstrap/template&quot;] - a full system path to a valid JSDoc3 * template directory * @property {string} [jsdocConfig=&quot;&lt;webcompiler root&gt;/config/jsdoc.json&quot;] - a full system path to a JSDoc3 * configuration file */ /** * @callback ProgramDataCallback * @param {ProgramData} data - the program data */ export type ProgramDataCallback = (data: ProgramData) =&gt; void; /** * @callback FileCallback * @param {string} file - a full system path to a file */ export type FileCallback = (file: string) =&gt; void; /** * @callback NullableFileCallback * @param {string} [file] - a full system path to a file */ export type NullableFileCallback = (file: ?string) =&gt; void; /** * @callback JSLintCallback * @param {Array&lt;JSLintError&gt;} [errors] - a collection of error objects */ export type JSLintCallback = (errors: ?Array&lt;JSLintError&gt;) =&gt; void; /** * @callback NativeProcessCallback * @param {string} [stderr] - an error message * @param {string} stdout - the process output */ export type NativeProcessCallback = (stderr: ?string, stdout: string) =&gt; void; /** * @callback ObjectOrErrorCallback * @param {string} [error] - an error message * @param {Object} result - the resulting object */ export type ObjectOrErrorCallback = (error: ?string, result: Object) =&gt; void; /** * Must be a pure function, always return the same value given the same input, must be side-effect free and not depend * on other replacers executing before it. * * If provided with a result of its own previous execution, must return it unchanged. * * @callback Transformer * @param {string} input - a transformed string * @return {string} transformed output */ export type Transformer = (input: string) =&gt; string; × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"Compiler.js.html":{"id":"Compiler.js.html","title":"Source: Compiler.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: Compiler.js /* @flow */ import type {ProgramData, ProgramDataCallback} from './typedef'; import mkdirp from 'mkdirp'; import {dirname} from 'path'; import {writeFile} from 'fs'; import {gzip} from 'zlib'; let i = 0; /** * The base compiler class * * @class Compiler * @abstract * @param {boolean} [compress=true] - if true `Compiler#optimize` will gzip compress the data in production mode */ export class Compiler { /** * True if the NODE_ENV environment variable is equal to `production`. * * Caution: modifying it's value directly may lead to unexpected results * * @member {boolean} isProduction * @memberof Compiler * @readOnly * @instance */ isProduction: boolean; /** * if true `Compiler#optimize` will gzip compress the data * * @member {boolean} compress * @memberof Compiler * @private * @instance */ compress: boolean; constructor(compress: boolean = true) { this.isProduction = 'production' === process.env.NODE_ENV; this.compress = this.isProduction &amp;&amp; compress; } /** * Executed when the compilation is complete * * @memberOf Compiler * @static * @method done * @param {string} inPath - the input path * @param {Function} callback - a callback function * @example * Compiler.done('/path/to/an/input/file', callback); */ static done(inPath: string, callback: () =&gt; void) { console.log('\\x1b[32m%s. Compiled %s\\x1b[0m', ++i, inPath); callback(); } /** * Writes the data to disk and then calls `done`. * * @memberOf Compiler * @static * @private * @method writeAndCallDone * @param {string} inPath - the input path * @param {string} outPath - the output path * @param {ProgramData} data - processed application code with source maps * @param {Function} callback - a callback function * @example * Compiler.writeAndCallDone('/path/to/an/input/file', '/path/to/the/output/file', data, callback); */ static writeAndCallDone(inPath: string, outPath: string, data: ProgramData, callback: () =&gt; void) { Compiler.fsWrite(outPath, data, () =&gt; { Compiler.done(inPath, callback); }); } /** * Writes the data to disk * * @memberOf Compiler * @static * @method fsWrite * @param {string} path - the output path * @param {ProgramData} data - the data to write * @param {Function} callback - a callback function * @example * Compiler.fsWrite('/path/to/an/output/file', data, callback); */ static fsWrite(path: string, data: ProgramData, callback: () =&gt; void) { Compiler.mkdir(path, () =&gt; { writeFile(path, data.code, scriptErr =&gt; { if (scriptErr) { return console.error(scriptErr); } if (!data.map) { return callback(); } writeFile(`${path}.map`, data.map, mapErr =&gt; { if (mapErr) { return console.error(mapErr); } callback(); }); }); }); } /** * Recursively creates a directory containing a file specified by `path`. * * @memberOf Compiler * @static * @method mkdir * @param {string} path - a path to a file * @param {Function} callback - a callback function * @example * Compiler.mkdir('/path/to/a/file', callback); */ static mkdir(path: string, callback: () =&gt; void) { mkdirp(dirname(path), mkdirpErr =&gt; { if (mkdirpErr) { return console.error(mkdirpErr); } callback(); }); } /** * G-zips the compiled code * * @memberOf Compiler * @static * @method gzip * @param {ProgramData} data - the actual program data to auto-prefix * @param {ProgramDataCallback} callback - a callback function * @example * Compiler.gzip(data, callback); */ static gzip(data: ProgramData, callback: ProgramDataCallback) { gzip(data.code, (err, code) =&gt; { if (err) { return console.error(err); } callback({code, map: data.map}); }); } /** * G-zips the program if necessary and writes the results to disk. * * @memberOf Compiler * @instance * @protected * @method optimize * @param {string} inPath - the input path * @param {string} outPath - the output path * @param {ProgramData} data - processed application code with source maps * @param {Function} callback - a callback function * @example * compiler.optimize('/path/to/an/input/file', '/path/to/the/output/file', data, callback); */ optimize(inPath: string, outPath: string, data: ProgramData, callback: () =&gt; void) { if (!this.compress) { Compiler.writeAndCallDone(inPath, outPath, data, callback); return; } Compiler.gzip(data, result =&gt; { Compiler.writeAndCallDone(inPath, outPath, result, callback); }); } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"DevServer.js.html":{"id":"DevServer.js.html","title":"Source: DevServer.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: DevServer.js /* @flow */ import {SASSCompiler} from './SASSCompiler'; import {watch} from './watch'; import tinylr from 'tiny-lr'; import WebpackDevServer from 'webpack-dev-server'; import webpack from 'webpack'; import {join} from 'path'; const LIVERELOAD_PORT = 35729, WEB_PORT = 3000; /** * A lightweight development server that rapidly recompiles the JavaScript and SASS files when they are edited and * updates the page. * * Utilizes the Webpack development server. * * Includes react hot loader to further optimize the development process of the React applications. * * Please install and enable the LiveReload browser extension for the CSS reloading to work. * * @class DevServer * @param {string} script - a full system path to a JavaScript file * @param {string} style - a full system path to a SASS file * @param {string} devDir - a full system path to a directory in which to put any compiled development resources * @param {number} [port=3000] - a port at which to start the dev server * @param {boolean} [react=true] - false to disable the react hot loader plugin * @see {@link http://webpack.github.io/docs/webpack-dev-server.html webpack-dev-server} * @see {@link http://gaearon.github.io/react-hot-loader/ React Hot Loader} * @example * import {DevServer} from 'webcompiler'; * import {join} from 'path'; * * const rootDir = join(__dirname, '..'), * devDir = join(rootDir, 'development'), * server = new DevServer(join(devDir, 'script.js'), join(devDir, 'app.scss'), devDir); * * server.run(rootDir); * // now navigate to http://localhost:3000 using your favorite browser ( preferably Chrome :) ) */ export class DevServer { /** * a port at which to start the dev server * * @member {number} port * @memberof DevServer * @private * @instance */ port: number; /** * a LiveReload server * * @member {tinylr.Server} lr * @memberof DevServer * @private * @instance */ lr: tinylr.Server; /** * recompiles SASS and notifies LiveReload * * @method compileSASS * @memberof DevServer * @private * @instance */ compileSASS: () =&gt; void; /** * the Webpack development server * * @member {WebpackDevServer} server * @memberof DevServer * @private * @instance */ server: WebpackDevServer; constructor(script: string, style: string, devDir: string, port: number = WEB_PORT, react: boolean = true) { const sass = new SASSCompiler(), loaders = []; if (react) { loaders.push('react-hot'); } loaders.push('babel'); this.port = port; this.lr = tinylr(); this.compileSASS = sass.fe.bind(sass, style, join(devDir, 'style.css'), () =&gt; { this.lr.changed({body: {files: ['style.css']}}); }); this.server = new WebpackDevServer(webpack({ cache: {}, debug: true, devtool: 'eval-source-map', entry: [ `webpack-dev-server/client?http://localhost:${this.port}`, 'webpack/hot/only-dev-server', script ], output: { path: devDir, filename: 'script.js', publicPath: '/' }, plugins: [ new webpack.HotModuleReplacementPlugin(), new webpack.NoErrorsPlugin() ], module: { loaders: [{ test: /\\.js$/, exclude: /node_modules/, loaders }] } }), { contentBase: devDir, publicPath: '/', hot: true, historyApiFallback: true }); this.server.app.get('*', (req, res) =&gt; { res.send(`&lt;!DOCTYPE html&gt; &lt;html lang=&quot;en&quot;&gt; &lt;head&gt; &lt;meta charset=&quot;utf-8&quot;&gt; &lt;meta http-equiv=&quot;X-UA-Compatible&quot; content=&quot;IE=edge&quot;&gt; &lt;meta name=&quot;viewport&quot; content=&quot;width=device-width, initial-scale=1&quot;&gt; &lt;title&gt;Development server - Webcompiler&lt;/title&gt; &lt;link href=&quot;/style.css&quot; rel=&quot;stylesheet&quot;&gt; &lt;/head&gt; &lt;body&gt; &lt;div id=&quot;app&quot;&gt;&lt;/div&gt; &lt;script src=&quot;/script.js&quot; async defer&gt;&lt;/script&gt; &lt;/body&gt; &lt;/html&gt;`); }); } /** * Compile SASS and start watching for file changes * * @memberof DevServer * @instance * @method watchSASS * @param {string} watchDir - the directory in which to watch for the changes in the SASS files * @example * server.watchSASS('/path/to/some/directory'); */ watchSASS(watchDir: string) { this.lr.listen(LIVERELOAD_PORT); this.compileSASS(); watch(watchDir, 'scss', this.compileSASS); } /** * Starts the Webpack development server * * @memberof DevServer * @instance * @method watchJS * @example * server.watchJS(); */ watchJS() { const port = this.port; this.server.listen(port, '0.0.0.0', error =&gt; { if (error) { return console.error(error); } console.log(`Started the development server at localhost:${port}`); }); } /** * Starts the Webpack development server, compiles SASS and starts watching for file changes * * @memberof DevServer * @instance * @method run * @param {string} watchDir - the directory in which to watch for the changes in the SASS files * @example * server.run('/path/to/some/directory'); */ run(watchDir: string) { this.watchJS(); this.watchSASS(watchDir); } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"Documentation.js.html":{"id":"Documentation.js.html","title":"Source: Documentation.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: Documentation.js /* @flow */ import type {FileCallback, NullableFileCallback} from './typedef'; import {NativeProcess} from './NativeProcess'; import {stat} from 'fs'; import {join} from 'path'; import noop from 'lodash/noop'; const npm = new NativeProcess('npm'), cwd = process.cwd(), defaultOptions = { inputDir: join(cwd, 'src'), outputDir: join(cwd, 'docs'), readMe: join(cwd, 'README.md'), template: join(cwd, 'node_modules', 'ink-docstrap', 'template'), jsdocConfig: join(__dirname, '..', 'config', 'jsdoc.json') }; /** * Generates API documentation * * The default JSDoc plugin specified in `jsdocConfig` strips out all of the code from a file while retaining newlines * (unlike the built in `commentsOnly` plugin that ships with JSDoc3). * * That way: * 1. line numbers are preserved in the source view * 2. you don't need to use a pre-compiler, you will always see the same code as you wrote in the docs source view * 3. since JSDoc only sees comments you can use any code syntax you like - ES2015, ES7, JSX, it doesn't even have to be * JavaScript. * * The markdown plugin is also included by default. * * @class Documentation * @param {DocumentationConfig} [config={}] - a configuration object * @example * import {Documentation} from 'webcompiler'; * * const docs = new Documentation(); */ export class Documentation { /** * JSDoc3 * * @member {NativeProcess} jsdoc * @memberof Documentation * @private * @instance */ jsdoc: ?NativeProcess; /** * documentation generator configuration object * * @member {DocumentationConfig} options * @memberof Documentation * @private * @instance */ options: Object; constructor(options: Object = {}) { this.options = {...defaultOptions, ...options}; } /** * Finds a path to the JSDoc3 executable * * @memberof Documentation * @static * @private * @method findExecutable * @param {FileCallback} callback - a callback function * @example * Documentation.findExecutable(file =&gt; { * // the jsdoc file is found * }); */ static findExecutable(callback: FileCallback) { Documentation.checkBin(localFile =&gt; { if (localFile) { return callback(localFile); } Documentation.checkBin(globalFile =&gt; { if (globalFile) { return callback(globalFile); } console.error('Failed to locate the jsdoc executable'); }, true); }); } /** * Checks the NPM bin directories to see if they contain a file named jsdoc * * @memberof Documentation * @static * @private * @method checkBin * @param {NullableFileCallback} callback - a callback function * @param {globalPackage} [boolean=false] - if true checks the global NPM bin directory (contains the npm * executable itself) * @example * Documentation.checkBin(file =&gt; { * if (file) { * // the jsdoc file is found * } * }); */ static checkBin(callback: NullableFileCallback, globalPackage: boolean = false) { const args = ['bin']; if (globalPackage) { args.push('-g'); } npm.run((stderr, stdout) =&gt; { if (stderr) { console.error(stderr); return callback(null); } const path = join(stdout.replace(/\\n$/, ''), 'jsdoc'); stat(path, err =&gt; { callback(err ? null : path); }); }, args); } /** * Generate the documentation * * @memberof Documentation * @instance * @method run * @param {Function} [callback=function () {}] - a callback function * @return {void} * @example * docs.run(() =&gt; { * // generated the API documentation * }); */ run(callback: () =&gt; void = noop) { if (this.jsdoc) { return this.doRun(this.jsdoc, callback); } Documentation.findExecutable(file =&gt; { this.jsdoc = new NativeProcess(file); this.doRun(this.jsdoc, callback); }); } /** * Given a JSDoc3 executable, generate the documentation * * @memberof Documentation * @instance * @private * @method doRun * @param {NativeProcess} jsdoc - JSDoc3 * @param {Function} callback - a callback function * @example * docs.doRun(jsdoc, () =&gt; { * // generated the API documentation * }); */ doRun(jsdoc: NativeProcess, callback: () =&gt; void) { const {inputDir, outputDir, readMe, template, jsdocConfig} = this.options; jsdoc.run(stderr =&gt; { if (stderr) { return console.error(stderr); } callback(); }, [inputDir, '-d', outputDir, '-R', readMe, '-c', jsdocConfig, '-t', template]); } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"JS.js.html":{"id":"JS.js.html","title":"Source: JS.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: JS.js /* @flow */ import {JSCompiler} from './JSCompiler'; import {NativeProcess} from './NativeProcess'; import {JSLint} from './JSLint'; import forEach from 'lodash/forEach'; import noop from 'lodash/noop'; /** * JavaScript compilation tools * * @class JS * @param {boolean} [compress=true] - if true `Compiler#optimize` will gzip compress the data * @param {Object} [babelOptions={}] - allows to override the default Babel options * @param {Object} [lintRules={}] - allows to override the default linting rules * @example * import {JS} from 'webcompiler'; * * const js = new JS(); */ export class JS { /** * JavaScript compiler * * @member {JSCompiler} compiler * @memberof JS * @private * @instance */ compiler: JSCompiler; /** * flow static analyzer * * @member {NativeProcess} flow * @memberof JS * @private * @instance */ flow: NativeProcess; /** * JavaScript linter * * @member {JSLint} linter * @memberof JS * @private * @instance */ linter: JSLint; constructor(compress: boolean = true, babelOptions: Object = {}, lintRules: Object = {}) { this.compiler = new JSCompiler(compress, babelOptions); this.flow = new NativeProcess('flow'); this.linter = new JSLint(lintRules); } /** * Performs static analysis * * @memberof JS * @instance * @method typecheck * @param {Function} callback - a callback function, invoked only when successfully typechecked * @example * js.typecheck(() =&gt; { * // successfully typechecked * }); */ typecheck(callback: () =&gt; void) { this.flow.run((flowErr, stdout) =&gt; { if (flowErr) { return console.error(flowErr); } if (!JSON.parse(stdout).passed) { return this.flow.run(noop, [], {stdio: 'inherit'}); } callback(); }, ['--json']); } /** * Performs linting * * @memberof JS * @instance * @method lint * @param {Array&lt;string&gt;} paths - an array of paths to files/directories to lint * @param {Function} callback - a callback function, invoked only when successfully linted * @example * js.lint(['/path/to/the/input/file.js', '/lint/this/directory/too'], () =&gt; { * // successfully linted * }); */ lint(paths: Array&lt;string&gt;, callback: () =&gt; void) { this.linter.run(paths, linterErr =&gt; { if (!linterErr) { return callback(); } forEach(linterErr, e =&gt; { console.log( '\\x1b[41mESLint error\\x1b[0m &quot;\\x1b[33m%s%s\\x1b[0m&quot; in \\x1b[36m%s\\x1b[0m on \\x1b[35m%s:%s\\x1b[0m', e.message, e.ruleId ? ` (${e.ruleId})` : '', e.filePath, e.line, e.column); }); console.log('JavaScript linting errors: %s', linterErr.length); }); } /** * Performs static analysis and linting * * @memberof JS * @instance * @private * @method validate * @param {string} inPath - the input file (will also be linted) * @param {Array&lt;string&gt;} lintPaths - an array of paths to files/directories to lint * @param {Function} callback - a callback function, invoked only when successfully validated * @example * js.validate('/path/to/the/input/file.js', ['/lint/this/directory/too'], () =&gt; { * // successfully validated * }); */ validate(inPath: string, lintPaths: Array&lt;string&gt;, callback: () =&gt; void) { this.typecheck(() =&gt; { this.lint(lintPaths.concat([inPath]), callback); }); } /** * Wraps {@link JSCompiler#be} to add static analysis and linting * * @memberOf JS * @instance * @method be * @param {string} inPath - the input path * @param {string} outPath - the output path * @param {Array&lt;string&gt;} [lintPaths=[]] - an array of paths to files/directories to lint * @param {Function} [callback=function () {}] - a callback function * @return {void} * @example * compiler.be('/path/to/an/input/file.js', '/path/to/the/output/file.js', ['/lint/this/directory/too'], () =&gt; { * // the code has passed all the checks and has been compiled successfully * }); */ be(inPath: string, outPath: string, lintPaths: Array&lt;string&gt; = [], callback: () =&gt; void = noop) { this.validate(inPath, lintPaths, () =&gt; { this.compiler.be(inPath, outPath, callback); }); } /** * Wraps {@link JSCompiler#fe} to add static analysis and linting * * @memberOf JS * @instance * @method fe * @param {string} inPath - the input path * @param {string} outPath - the output path * @param {Array&lt;string&gt;} [lintPaths=[]] - an array of paths to files/directories to lint * @param {Function} [callback=function () {}] - a callback function * @return {void} * @example * compiler.fe('/path/to/an/input/file.js', '/path/to/the/output/file.js', ['/lint/this/directory/too'], () =&gt; { * // the code has passed all the checks and has been compiled successfully * }); */ fe(inPath: string, outPath: string, lintPaths: Array&lt;string&gt; = [], callback: () =&gt; void = noop) { this.validate(inPath, lintPaths, () =&gt; { this.compiler.fe(inPath, outPath, callback); }); } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"JSCompiler.js.html":{"id":"JSCompiler.js.html","title":"Source: JSCompiler.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: JSCompiler.js /* @flow */ import {Compiler} from './Compiler'; import {join, extname, dirname, basename} from 'path'; import {readdir, stat, createReadStream, createWriteStream, readFileSync} from 'fs'; import {transformFile} from 'babel-core'; import webpack from 'webpack'; import MemoryFS from 'memory-fs'; import forEach from 'lodash/forEach'; import noop from 'lodash/noop'; import assignWith from 'lodash/assignWith'; import get from 'lodash/get'; import isArray from 'lodash/isArray'; import uniq from 'lodash/uniq'; /* eslint-disable no-sync */ const config = JSON.parse(readFileSync(join(__dirname, '..', '.babelrc'), 'utf8')), cache = {}, fakeFS = new MemoryFS(), {DedupePlugin, UglifyJsPlugin} = webpack.optimize, productionPlugins = [new DedupePlugin(), new UglifyJsPlugin()]; /** * A JavaScript compiler * * @class JSCompiler * @extends Compiler * @param {boolean} [compress=true] - if true `Compiler#optimize` will gzip compress the data * @param {Object} [options={}] - allows to override the default Babel options * @example * import {JSCompiler} from 'webcompiler'; * * const compiler = new JSCompiler(); */ export class JSCompiler extends Compiler { /** * Babel options * * @member {Object} options * @memberOf JSCompiler * @private * @instance */ options: Object; /** * The number of files being compiled at the moment * * @member {number} processing * @memberOf JSCompiler * @private * @instance */ processing: number; constructor(compress: boolean = true, options: Object = {}) { super(compress); this.configure(options); this.processing = 0; } /** * Merges Babel configuration options * * @memberOf JSCompiler * @instance * @private * @method configure * @param {Object} options - allows to override the default Babel options * @example * compiler.configure(options); */ configure(options: Object) { this.options = assignWith({}, config, get(config, ['env', process.env.NODE_ENV || 'development']), options, (objValue, srcValue) =&gt; { if (!isArray(srcValue)) { return srcValue; } if (!isArray(objValue)) { return uniq(srcValue); } return uniq(srcValue.concat(objValue)); }); delete this.options.env; } /** * Compiles a directory of files for the back end * * @memberOf JSCompiler * @instance * @private * @method beDir * @param {string} inPath - the input path * @param {string} outPath - the output path * @param {Function} callback - a callback function * @example * compiler.beDir('/path/to/an/input/directory', '/path/to/the/output/directory', callback); */ beDir(inPath: string, outPath: string, callback: () =&gt; void) { readdir(inPath, (readdirErr, files) =&gt; { if (readdirErr) { return console.error(readdirErr); } forEach(files, file =&gt; { this.beTraverse(join(inPath, file), join(outPath, file), callback); }); }); } /** * Compiles a JavaScript file for the back end * * @memberOf JSCompiler * @instance * @private * @method beFile * @param {string} inPath - the input path * @param {string} outPath - the output path * @param {Function} callback - a callback function * @example * compiler.beFile('/path/to/an/input/file.js', '/path/to/the/output/file.js', callback); */ beFile(inPath: string, outPath: string, callback: () =&gt; void) { ++this.processing; transformFile(inPath, this.options, (transformFileErr, result) =&gt; { if (transformFileErr) { return console.error(transformFileErr); } Compiler.fsWrite(outPath, result, callback); }); } /** * Copies a file * * @memberOf JSCompiler * @instance * @private * @method copyFile * @param {string} inPath - the input path * @param {string} outPath - the output path * @param {Function} callback - a callback function * @example * compiler.copyFile('/path/to/an/input/file', '/path/to/the/output/file', callback); */ copyFile(inPath: string, outPath: string, callback: () =&gt; void) { ++this.processing; Compiler.mkdir(outPath, () =&gt; { createReadStream(inPath).pipe(createWriteStream(outPath)); callback(); }); } /** * Compiles a JavaScript file for the back end or recursively traverses a directory, looking for the JavaScript files * to compile. Non-JavaScript files are simply copied over. * * @memberOf JSCompiler * @instance * @private * @method beTraverse * @param {string} inPath - the input path * @param {string} outPath - the output path * @param {Function} callback - a callback function * @example * compiler.beTraverse('/path/to/an/input/file.js', '/path/to/the/output/file.js', callback); */ beTraverse(inPath: string, outPath: string, callback: () =&gt; void) { stat(inPath, (statErr, stats) =&gt; { if (statErr) { return console.error(statErr); } if (stats.isDirectory()) { this.beDir(inPath, outPath, callback); } else if ('.js' === extname(inPath)) { this.beFile(inPath, outPath, callback); } else { this.copyFile(inPath, outPath, callback); } }); } /** * Compiles a JavaScript file or a directory for the back end. Non-JavaScript files are simply copied over. * * @memberOf JSCompiler * @instance * @method be * @param {string} inPath - the input path * @param {string} outPath - the output path * @param {Function} [callback=function () {}] - a callback function * @return {void} * @example * compiler.be('/path/to/an/input/file.js', '/path/to/the/output/file.js', callback); */ be(inPath: string, outPath: string, callback: () =&gt; void = noop) { if (this.processing) { return console.error('Still working...'); } this.beTraverse(inPath, outPath, () =&gt; { if (!(--this.processing)) { Compiler.done(inPath, callback); } }); } /** * Compiles, bundles (in production mode also minifies and g-zips) a JavaScript file for the front end. * * @memberOf JSCompiler * @instance * @method fe * @param {string} inPath - the input path * @param {string} outPath - the output path * @param {Function} [callback=function () {}] - a callback function * @example * compiler.fe('/path/to/an/input/file.js', '/path/to/the/output/file.js', callback); */ fe(inPath: string, outPath: string, callback: () =&gt; void = noop) { const compiler = webpack({ cache, debug: true, devtool: 'source-map', entry: inPath, output: {path: dirname(outPath), filename: basename(outPath)}, plugins: this.isProduction ? productionPlugins : [], module: { loaders: [{ test: /\\.js$/, exclude: /node_modules/, loader: 'babel-loader', query: {cacheDirectory: true, ...this.options} }, { test: /\\.json$/, loader: 'json' }] } }); compiler.outputFileSystem = fakeFS; compiler.run((err, stats) =&gt; { if (err) { return console.error(err); } const {warnings, errors} = stats.toJson(); forEach(warnings, warning =&gt; { console.log('\\x1b[33m%s\\x1b[0m', warning); }); if (errors.length) { return forEach(errors, error =&gt; { console.error(error); }); } this.optimize(inPath, outPath, { code: fakeFS.readFileSync(outPath, 'utf8'), map: fakeFS.readFileSync(`${outPath}.map`, 'utf8') }, callback); }); } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"JSLint.js.html":{"id":"JSLint.js.html","title":"Source: JSLint.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: JSLint.js /* @flow */ import type {JSLintCallback} from './typedef'; import {CLIEngine} from 'eslint'; import {join} from 'path'; import forEach from 'lodash/forEach'; const configFile = join(__dirname, '..', 'config', 'eslint.yml'); /** * A JavaScript linter * * @class JSLint * @param {Object} [rules={}] - an object that lets you override default linting rules * @example * import {JSLint} from 'webcompiler'; * import {join} from 'path'; * * const linter = new JSLint(); */ export class JSLint { /** * an internal linter instance * * @member {CLIEngine} linter * @memberof JSLint * @private * @instance */ linter: CLIEngine; constructor(rules: Object = {}) { this.linter = new CLIEngine({configFile, rules}); } /** * Execute the linter * * @memberof JSLint * @instance * @method run * @param {Array&lt;string&gt;} paths - an array of paths to files/directories to lint * @param {JSLintCallback} callback - a callback function, accepts 1 argument: an array of error objects or null * @example * // lint &quot;index.js&quot; as well as the entire contents of the &quot;src&quot; directory * linter.run([join(__dirname, 'index.js'), join(__dirname, 'src')], function (err) { * if (err) { * return e.forEach(e =&gt; { * console.log('\\x1b[41mESLint error\\x1b[0m &quot;\\x1b[33m%s%s\\x1b[0m&quot; in \\x1b[36m%s\\x1b[0m on \\x1b[35m%s:%s\\x1b[0m', * e.message, e.ruleId ? ` (${e.ruleId})` : '', e.filePath, e.line, e.column); * }); * } * // there were no linting errors * }); */ run(paths: Array&lt;string&gt;, callback: JSLintCallback) { const report = this.linter.executeOnFiles(paths), errors = []; forEach(report.results, f =&gt; { forEach(f.messages, e =&gt; { e.filePath = f.filePath; errors.push(e); }); }); callback(errors.length ? errors : null); } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"Markup.js.html":{"id":"Markup.js.html","title":"Source: Markup.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: Markup.js /* @flow */ import type {CheerioNode, CheerioElement, Transformer} from './typedef'; import {load} from 'cheerio'; import {createElement} from 'react'; import marked from 'marked'; import reject from 'lodash/reject'; import map from 'lodash/map'; import transform from 'lodash/transform'; import has from 'lodash/has'; import reduce from 'lodash/reduce'; import flattenDeep from 'lodash/flattenDeep'; import isString from 'lodash/isString'; import trim from 'lodash/trim'; /* eslint-disable no-arrow-condition */ /** * Allows to easily and efficiently convert text from Markdown to HTML and from HTML to a collection of React Elements * that can be used directly in a JSX expression. * * Whenever an HTML string is involved, runs it through an array of Transformer functions. * * @class Markup * @param {...Transformer} transformers - transformers to initialize with * @example * import {Markup} from 'webcompiler'; * * const mark = new Markup(); */ export class Markup { /** * an array of Transformer functions * * @member {Array&lt;Transformer&gt;} transformers * @memberof Markup * @private * @instance */ transformers: Array&lt;Transformer&gt;; constructor(...transformers: Array&lt;Transformer&gt;) { this.transformers = transformers; } /** * Convert the CSS style key to a JSX style key * * @memberof Markup * @static * @private * @method toJSXKey * @param {string} key - CSS style key * @return {string} JSX style key * @example * Markup.toJSXKey('min-width'); // minWidth */ static toJSXKey(key: string): string { return (/^-ms-/.test(key) ? key.substr(1) : key).replace(/-(.)/g, (match, chr) =&gt; chr.toUpperCase()); } /** * Parse the specified inline style attribute value * * @memberof Markup * @static * @private * @method transformStyle * @param {Object} object - the object to perform replacements on */ static transformStyle(object: Object) { if (has(object, 'style')) { object.style = transform(object.style.split(';'), (result, style) =&gt; { const firstColon = style.indexOf(':'), key = style.substr(0, firstColon).trim(); if (key) { result[Markup.toJSXKey(key.toLowerCase())] = style.substr(firstColon + 1).trim(); } }, {}); } } /** * Renames specified attributes if present * * @memberof Markup * @static * @private * @method rename * @param {Object} object - the object to perform replacements on * @param {string} fromKey - a key to look for * @param {string} toKey - a key to rename to */ static rename(object: Object, fromKey: string, toKey: string) { if (has(object, fromKey)) { object[toKey] = object[fromKey]; delete object[fromKey]; } } /** * Converts a DOM Element to a React Element * * @memberof Markup * @static * @private * @method childToJSX * @param {CheerioElement} child - the DOM Element to convert to a React Element * @param {number} i - positional index of the element * @return {ReactElement} React Element */ static childToJSX(child: CheerioElement, i: number): any { const {name, attribs, children} = child; attribs.key = i; Markup.transformStyle(attribs); Markup.rename(attribs, 'for', 'htmlFor'); Markup.rename(attribs, 'class', 'className'); if ('input' === name) { Markup.rename(attribs, 'checked', 'defaultChecked'); Markup.rename(attribs, 'value', 'defaultValue'); } let childComponents = Markup.childrenToJSX(children); if ('textarea' === name &amp;&amp; childComponents.length) { attribs.defaultValue = childComponents[0]; childComponents = []; } return createElement(name, attribs, ...childComponents); } /** * Converts an array of DOM Elements to an array of React Elements * * @memberof Markup * @static * @private * @method childrenToJSX * @param {Array&lt;CheerioNode&gt;} children - the DOM Element to convert to a React element * @return {Array&lt;ReactElement&gt;} an array of React Elements */ static childrenToJSX(children: Array&lt;CheerioNode&gt; = []): Array&lt;any&gt; { return map(reject(children, ['type', 'comment']), (c, i) =&gt; 'text' === c.type ? c.data : Markup.childToJSX(c, i)); } /** * If a simple single line string is passed to the Markdown parser it thinks that it's a paragraph (it sort of * technically is) and unnecessarily wraps it into `&lt;p&gt;&lt;/p&gt;`, which most often is not the desired behavior. * * This function converts Markdown to HTML and then removes the wrapping paragraph if it is the only top level tag * unwrapping its contents. * * @memberof Markup * @static * @private * @method markdownToUnwrappedHTML * @param {string} markdown - an arbitrary Markdown string * @return {string} an HTML string */ static markdownToUnwrappedHTML(markdown: string): string { const html = trim(marked(markdown)), dom = load(html), {children} = dom.root().toArray()[0]; return 1 === children.length &amp;&amp; 'tag' === children[0].type &amp;&amp; 'p' === children[0].name ? dom('p').html() : html; } /** * Recursively flattens `args` and combines string values. * * Can be used as a simple optimization step on the JSX children-to-be to simplify the resulting DOM structure by * joining adjacent text nodes together. * * @memberof Markup * @static * @method flatten * @param {...*} args - the input array * @return {Array&lt;*&gt;} the flattened result * @example * Markup.flatten('lorem ', ['ipsum ', ['dolor ', ['sit ', ['amet']]]]); // [&quot;lorem ipsum dolor sit amet&quot;] */ static flatten(...args: Array&lt;any&gt;): Array&lt;any&gt; { return transform(flattenDeep(args), (accumulator, value) =&gt; { const lastIndex = accumulator.length - 1; if (isString(value) &amp;&amp; isString(accumulator[lastIndex])) { accumulator[lastIndex] += value; } else { accumulator.push(value); } }, []); } /** * Runs the html string through an array of Transformer functions * * @memberof Markup * @instance * @private * @method transform * @param {string} html - an arbitrary HTML string * @return {string} a transformed string */ transform(html: string): string { return reduce(this.transformers, (result, transformer) =&gt; transformer(result), html); } /** * Converts an arbitrary HTML string to an array of React Elements * * @memberof Markup * @instance * @method htmlToJSX * @param {string} [html=&quot;&quot;] - an arbitrary HTML string * @return {Array&lt;ReactElement&gt;} an array of React Elements * @example * &lt;div&gt;{mark.htmlToJSX('Hello &lt;span&gt;world!&lt;/span&gt;')}&lt;/div&gt; */ htmlToJSX(html: string = ''): Array&lt;any&gt; { html = trim(html); return html ? Markup.childrenToJSX(load(this.transform(html)).root().toArray()[0].children) : []; } /** * Converts an arbitrary Markdown string to an HTML string * * @memberof Markup * @instance * @method markdownToHTML * @param {string} [markdown=&quot;&quot;] - an arbitrary Markdown string * @return {string} an HTML string * @example * mark.markdownToHTML('# Hello world!'); // &lt;h1&gt;Hello world!&lt;/h1&gt; */ markdownToHTML(markdown: string = ''): string { markdown = trim(markdown); return markdown ? trim(this.transform(Markup.markdownToUnwrappedHTML(markdown))) : ''; } /** * Converts an arbitrary Markdown string to an array of React Elements * * @memberof Markup * @instance * @method markdownToJSX * @param {string} [markdown=&quot;&quot;] - an arbitrary Markdown string * @return {Array&lt;ReactElement&gt;} an array of React Elements * @example * &lt;div&gt;{mark.markdownToJSX('# Hello world!')}&lt;/div&gt; */ markdownToJSX(markdown: string = ''): Array&lt;any&gt; { markdown = trim(markdown); return markdown ? this.htmlToJSX(Markup.markdownToUnwrappedHTML(markdown)) : []; } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"NativeProcess.js.html":{"id":"NativeProcess.js.html","title":"Source: NativeProcess.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: NativeProcess.js /* @flow */ import type {NativeProcessCallback} from './typedef'; import {spawn} from 'child_process'; import noop from 'lodash/noop'; /** * Encapsulates a {@link https://nodejs.org/api/child_process.html#child_process_class_childprocess ChildProcess} * instance of a `task` * * @class NativeProcess * @param {string} task - a process name * @example * import {NativeProcess} from 'webcompiler'; * * const mkdir = new NativeProcess('mkdir'); */ export class NativeProcess { /** * a process name * * @member {string} task * @memberof NativeProcess * @private * @instance */ task: string; /** * a ChildProcess instance * * @member {ChildProcess} proc * @memberof NativeProcess * @private * @instance */ proc: any; constructor(task: string) { this.task = task; } /** * Execute the command * * @memberof NativeProcess * @instance * @method run * @param {NativeProcessCallback} [callback=function () {}] - a callback function * @param {Array&lt;string&gt;} [args=[]] - an array of arguments to pass to the process * @param {Object} [opts={}] - a configuration object for the process * @return {void} * @example * mkdir.run(error =&gt; { * if (error) { * return console.error(error); * } * // created a directory named &quot;example&quot; in cwd * }, ['example']); */ run(callback: NativeProcessCallback = noop, args: Array&lt;string&gt; = [], opts: Object = {}) { if (this.proc) { return callback('Still working...', ''); } this.proc = spawn(this.task, args, opts); let stdout = '', stderr = ''; if (this.proc.stdout) { this.proc.stdout.on('data', data =&gt; { stdout += data; }); } if (this.proc.stderr) { this.proc.stderr.on('data', data =&gt; { stderr += data; }); } this.proc.on('error', error =&gt; { stderr += error.toString(); }); this.proc.on('close', code =&gt; { this.proc = null; callback(code ? stderr : null, stdout); }); } /** * Kills the process if any is running * * @memberof NativeProcess * @instance * @method kill * @example * someEpensiveProcess.kill(); */ kill() { if (this.proc) { this.proc.kill(); this.proc = null; } } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"SASS.js.html":{"id":"SASS.js.html","title":"Source: SASS.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: SASS.js /* @flow */ import {SASSCompiler} from './SASSCompiler'; import {SASSLint} from './SASSLint'; import noop from 'lodash/noop'; /** * SASS compilation tools * * @class SASS * @param {boolean} [compress=true] - if true `Compiler#optimize` will gzip compress the data * @param {Array&lt;string&gt;} [includePaths=[]] - an array of additional include paths * @param {Array&lt;string&gt;} [excludeLinter=[]] - names of linters to exclude * @param {Object} [importOnceOptions={}] - an object that lets you override default importOnce resolver * configuration * @example * import {SASS} from 'webcompiler'; * * const sass = new SASS(); */ export class SASS { /** * SCSS compiler * * @member {SASSCompiler} compiler * @memberof SASS * @private * @instance */ compiler: SASSCompiler; /** * SCSS linter * * @member {SASSLint} linter * @memberof SASS * @private * @instance */ linter: SASSLint; constructor(compress: boolean = true, includePaths: Array&lt;string&gt; = [], excludeLinter: Array&lt;string&gt; = [], importOnceOptions: Object = {}) { this.compiler = new SASSCompiler(compress, includePaths, importOnceOptions); this.linter = new SASSLint(...excludeLinter); } /** * Performs linting * * @memberof SASS * @instance * @method lint * @param {Array&lt;string&gt;} paths - an array of paths to lint * @param {Function} callback - a callback function * @example * sass.lint(['/path/to/the/input/file.scss', '/lint/this/directory/too'], () =&gt; { * // successfully linted * }); */ lint(paths: Array&lt;string&gt;, callback: () =&gt; void) { this.linter.run(paths, linterErr =&gt; { if (linterErr) { return console.error(linterErr); } callback(); }); } /** * Wraps {@link SASSCompiler#fe} to add linting * * @memberof SASS * @instance * @method fe * @param {string} inPath - the input path * @param {string} outPath - the output path * @param {Array&lt;string&gt;} [lintPaths=[]] - an array of paths to files/directories to lint * @param {Function} [callback=function () {}] - a callback function * @return {void} * @example * compiler.fe('/path/to/an/input/file.js', '/path/to/the/output/file.js', ['/lint/this/directory/too'], () =&gt; { * // the code has passed all the checks and has been compiled successfully * }); */ fe(inPath: string, outPath: string, lintPaths: Array&lt;string&gt; = [], callback: () =&gt; void = noop) { this.lint(lintPaths.concat([inPath]), () =&gt; { this.compiler.fe(inPath, outPath, callback); }); } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"SASSCompiler.js.html":{"id":"SASSCompiler.js.html","title":"Source: SASSCompiler.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: SASSCompiler.js /* @flow */ import type {ProgramData, ProgramDataCallback} from './typedef'; import {Compiler} from './Compiler'; import {render} from 'node-sass'; import importer from 'node-sass-import-once'; import postcss from 'postcss'; import autoprefixer from 'autoprefixer'; import forEach from 'lodash/forEach'; import noop from 'lodash/noop'; const precision = 8, importOnceDefaults = {index: true, css: false, bower: false}, defaultIncludePaths = ['node_modules/bootstrap-sass/assets/stylesheets', 'node_modules']; /** * A SASS compiler * * @class SASSCompiler * @extends Compiler * @param {boolean} [compress=true] - if true `Compiler#optimize` will gzip compress the data * @param {Array&lt;string&gt;} [includePaths=[]] - an array of additional include paths * @param {Object} [importOnceOptions={}] - an object that lets you override default importOnce resolver * configuration * @example * import {SASSCompiler} from 'webcompiler'; * * const compiler = new SASSCompiler(); */ export class SASSCompiler extends Compiler { /** * an array of paths to search for an scss file in if it's not found in cwd * * @member {Array&lt;string&gt;} includePaths * @memberof SASSCompiler * @private * @instance */ includePaths: Array&lt;string&gt;; /** * importOnce resolver configuration * * @member {Object} importOnce * @memberof SASSCompiler * @private * @instance */ importOnce: Object; constructor(compress: boolean = true, includePaths: Array&lt;string&gt; = [], importOnceOptions: Object = {}) { super(compress); this.includePaths = defaultIncludePaths.concat(includePaths); this.importOnce = {...importOnceDefaults, ...importOnceOptions}; } /** * Auto-prefixes the compiled code * * @memberOf SASSCompiler * @static * @method autoprefix * @param {string} path - a path to the file * @param {ProgramData} data - the actual program data to auto-prefix * @param {ProgramDataCallback} callback - a callback function * @example * SASSCompiler.autoprefix('/path/to/the/output/file.css', data, result =&gt; { * // successfully added the vendor prefixes * }); */ static autoprefix(path: string, data: ProgramData, callback: ProgramDataCallback) { postcss([autoprefixer]).process(data.code, { from: path, to: path, map: {prev: data.map} }).then(result =&gt; { const warnings = result.warnings(); if (warnings.length) { return forEach(warnings, warning =&gt; { console.error(warning.toString()); }); } callback({code: result.css, map: JSON.stringify(result.map)}); }); } /** * Compiles, auto-prefixes and optionally minifies and g-zips in the production mode * * @memberof SASSCompiler * @instance * @method fe * @param {string} inPath - a full system path to the input file * @param {string} outPath - a full system path to the output file * @param {Function} [callback=function () {}] - a callback function * @example * compiler.fe('/path/to/the/input/file.scss', '/path/to/the/output/file.css', () =&gt; { * // compiled successfully * }); */ fe(inPath: string, outPath: string, callback: () =&gt; void = noop) { render({ file: inPath, outFile: outPath, importer, precision, importOnce: this.importOnce, includePaths: this.includePaths, sourceMap: true, sourceMapContents: true, outputStyle: this.isProduction ? 'compressed' : 'nested' }, (error, result) =&gt; { if (error) { return console.log( '\\x1b[41mSASS error\\x1b[0m &quot;\\x1b[33m%s\\x1b[0m&quot; in \\x1b[36m%s\\x1b[0m on \\x1b[35m%s:%s\\x1b[0m', error.message, error.file, error.line, error.column); } SASSCompiler.autoprefix(outPath, {code: result.css, map: result.map.toString()}, data =&gt; { this.optimize(inPath, outPath, data, callback); }); }); } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"SASSLint.js.html":{"id":"SASSLint.js.html","title":"Source: SASSLint.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: SASSLint.js /* @flow */ import type {NativeProcessCallback} from './typedef'; import {NativeProcess} from './NativeProcess'; import {join} from 'path'; const config = join(__dirname, '..', 'config', 'scsslint.yml'); /** * A SASS linter * * @class SASSLint * @param {...string} excludeLinter - names of linters to exclude * @example * import {SASSLint} from 'webcompiler'; * import {join} from 'path'; * * const linter = new SASSLint(); */ export class SASSLint { /** * a comma-separated list of linter names to exclude from execution * * @member {string} excludeLinter * @memberof SASSLint * @private * @instance */ excludeLinter: string; /** * a NativeProcess instance for scss-lint * * @member {NativeProcess} proc * @memberof SASSLint * @private * @instance */ proc: NativeProcess; constructor(...excludeLinter: Array&lt;string&gt;) { this.excludeLinter = excludeLinter.join(','); this.proc = new NativeProcess('scss-lint'); } /** * Execute the linter * * @memberof SASSLint * @instance * @method run * @param {Array&lt;string&gt;} paths - an array of paths to files/directories to lint * @param {Function} callback - a callback function, accepts 1 argument: an error message or null * @example * // lint &quot;style.scss&quot; as well as the entire contents of the &quot;sass&quot; directory * linter.run([join(__dirname, 'style.scss'), join(__dirname, 'sass')], error =&gt; { * if (error) { * return console.error(error); * } * // there were no linting errors * }); */ run(paths: Array&lt;string&gt;, callback: NativeProcessCallback) { const args = paths.concat(['-c', config]); if (this.excludeLinter) { args.push('-x', this.excludeLinter); } this.proc.run(callback, args); } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"watch.js.html":{"id":"watch.js.html","title":"Source: watch.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: watch.js /* @flow */ import {Client} from 'fb-watchman'; const client = new Client(), ALPHANUMERIC_BASE = 36; /** * Using the Facebook Watchman, watches the directory `dir` for changes of files with extension `type` and runs * `callback` when a change is detected. * * This watcher's only goal is performance, hence the simplicity. * * @function watch * @param {string} dir - a full system path to a directory to watch * @param {string} type - a file extension * @param {Function} callback - a callback function * @see {@link https://facebook.github.io/watchman/ Watchman} * @example * import {watch} from 'webcompiler'; * import {join} from 'path'; * * watch(join(__dirname, 'src'), 'js', someFunction); */ export function watch(dir: string, type: string, callback: () =&gt; void) { const subscription = Date.now().toString(ALPHANUMERIC_BASE); client.capabilityCheck({}, capabilityErr =&gt; { if (capabilityErr) { console.error(capabilityErr); return; } client.command(['watch-project', dir], (watchErr, watchResp) =&gt; { const watcher = watchResp.watch; if (watchErr) { console.error('Error initiating watch:', watchErr); return; } if (watchResp.warning) { console.log('warning: ', watchResp.warning); } client.command(['clock', watcher], (clockErr, clockResp) =&gt; { if (clockErr) { console.error('Failed to query clock:', clockErr); return; } client.command(['subscribe', watcher, subscription, { expression: ['suffix', type], since: clockResp.clock }], subscribeErr =&gt; { if (subscribeErr) { console.error('failed to subscribe: ', subscribeErr); } }); client.on('subscription', subscriptionResp =&gt; { if (subscription === subscriptionResp.subscription) { callback(); } }); }); }); }); } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"yaml.js.html":{"id":"yaml.js.html","title":"Source: yaml.js","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Source: yaml.js /* @flow */ import type {ObjectOrErrorCallback} from './typedef'; import {safeLoad} from 'js-yaml'; import {readFileSync} from 'fs'; /** * Read the contents of a YAML file * * @function yaml * @param {string} filename - the full system path to a YAML file * @param {ObjectOrErrorCallback} callback - a callback function * @example * import {yaml} from 'webcompiler'; * import {join} from 'path'; * * yaml(join(__dirname, 'config', 'config.yml'), (error, data) =&gt; { * if (error) { * return console.error(error); * } * // the parsed config object * }); */ export function yaml(filename: string, callback: ObjectOrErrorCallback) { try { const yamlString: string = readFileSync(filename, 'utf8'); callback(null, safeLoad(yamlString, {filename})); } catch (e) { callback(e.toString(), {}); } } × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"global.html":{"id":"global.html","title":"Global","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Global Methods watch(dir, type, callback) Using the Facebook Watchman, watches the directory dir for changes of files with extension type and runs callback when a change is detected. This watcher's only goal is performance, hence the simplicity. Parameters: Name Type Description dir string a full system path to a directory to watch type string a file extension callback function a callback function Source: watch.js, line 8 See: Watchman Example import {watch} from 'webcompiler'; import {join} from 'path'; watch(join(__dirname, 'src'), 'js', someFunction); yaml(filename, callback) Read the contents of a YAML file Parameters: Name Type Description filename string the full system path to a YAML file callback ObjectOrErrorCallback a callback function Source: yaml.js, line 7 Example import {yaml} from 'webcompiler'; import {join} from 'path'; yaml(join(__dirname, 'config', 'config.yml'), (error, data) =&gt; { if (error) { return console.error(error); } // the parsed config object }); Type Definitions CheerioElement A dumbed down representation of a DOM Element Type: Object Properties: Name Type Argument Description type string &quot;tag&quot; name string the tag name (e.g. &quot;div&quot;) attribs Object the tag attributes (e.g. {style: 'min-width:50px'}) children Array.&lt;CheerioNode&gt; &lt;optional&gt; an array of child nodes next CheerioNode &lt;optional&gt; the next sibling node prev CheerioNode &lt;optional&gt; the previous sibling node parent CheerioElement &lt;optional&gt; the parent element Source: typedef.js, line 32 CheerioNode A dumbed down representation of a DOM Node Type: Object Properties: Name Type Description type string either &quot;comment&quot;, &quot;text&quot; or &quot;tag&quot; Source: typedef.js, line 24 CheerioText A dumbed down representation of a DOM Text or a Comment Nodes Type: Object Properties: Name Type Argument Description type string either &quot;text&quot; or &quot;comment&quot; data string the textual content of the node next CheerioNode &lt;optional&gt; the next sibling node prev CheerioNode &lt;optional&gt; the previous sibling node parent CheerioElement &lt;optional&gt; the parent element Source: typedef.js, line 47 DocumentationConfig Documentation generator configuration object Type: Object Properties: Name Type Argument Default Description inputDir string &lt;optional&gt; &quot;src&quot; the input application code directory outputDir string &lt;optional&gt; &quot;docs&quot; the output directory for the generated documentation readMe string &lt;optional&gt; &quot;README.md&quot; the documentation &quot;homepage&quot; (README.md file) template string &lt;optional&gt; &quot;node_modules/ink-docstrap/template&quot; a full system path to a valid JSDoc3 template directory jsdocConfig string &lt;optional&gt; &quot;&lt;webcompiler root&gt;/config/jsdoc.json&quot; a full system path to a JSDoc3 configuration file Source: typedef.js, line 59 FileCallback(file) Parameters: Name Type Description file string a full system path to a file Source: typedef.js, line 78 JSLintCallback(errors) Parameters: Name Type Argument Description errors Array.&lt;JSLintError&gt; &lt;optional&gt; a collection of error objects Source: typedef.js, line 90 JSLintError The JavaScript linting error object Type: Object Properties: Name Type Argument Description message string the error message ruleId string &lt;optional&gt; the relative linting rule filePath string the path to a file line number the offending line number column number the offending column number Source: typedef.js, line 12 NativeProcessCallback(stderr, stdout) Parameters: Name Type Argument Description stderr string &lt;optional&gt; an error message stdout string the process output Source: typedef.js, line 96 NullableFileCallback(file) Parameters: Name Type Argument Description file string &lt;optional&gt; a full system path to a file Source: typedef.js, line 84 ObjectOrErrorCallback(error, result) Parameters: Name Type Argument Description error string &lt;optional&gt; an error message result Object the resulting object Source: typedef.js, line 103 ProgramData Processed application code with source maps Type: Object Properties: Name Type Description code string program code map string source map json string Source: typedef.js, line 3 ProgramDataCallback(data) Parameters: Name Type Description data ProgramData the program data Source: typedef.js, line 72 Transformer(input) Must be a pure function, always return the same value given the same input, must be side-effect free and not depend on other replacers executing before it. If provided with a result of its own previous execution, must return it unchanged. Parameters: Name Type Description input string a transformed string Source: typedef.js, line 110 Returns: transformed output Type string × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"classes.list.html":{"id":"classes.list.html","title":"Classes","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Classes Classes Compiler DevServer Documentation JS JSCompiler JSLint Markup NativeProcess SASS SASSCompiler SASSLint × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"index.html":{"id":"index.html","title":"Index","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml webcompilerLint, type-check, compile, package and gzip JavaScript (ES6 + Flow static types + JSX), for the browser as well as NodeJS; lint, compile, auto-prefix, minify and gzip SASS. Project Home | API Docs | Discord Webpack is an amazing tool, however it requires a lot of boilerplate to properly setup and configure, especially when you use it on more than one project. ESLint is constantly updated, new rules are added, APIs are changed. Properly configuring it is a routine and time consuming task, which is completely impractical to perform on each project separately. APIs are sometimes changed without any change in functionality (e.g. Babel 5 vs Babel 6). This project aims to abstract all of those problems out of the development of applications. Prerequisites Facebook Flow SCSS-Lint Watchman A note about Facebook FlowFacebook Flow is a static analysis tool used to check your JavaScript code for possible errors at compile time. It is very smart at understanding your program code, however you should not rely on it being smart enough to just understand your external dependencies too. It can do that, the problem is that a typical NodeJS project can contain hundreds NPM modules, with thousands of JavaScript files. It is a very complicated task, even for a tool that smart, to parse all of them and stay performant enough to not only be usable but useful as well. Which is why it must not be allowed to even try to understand any files that reside in a node_modules directory. Interface Files must be used instead. You can find examples of such interface files, as well as the interface file for the tool itself, in the interfaces directory. Installationnpm i webcompiler --save-devProduction buildsBy default all compilation is done in development mode. If you wish to compile for production just set the NODE_ENV environment variable to &quot;production&quot;, the following additional actions will be performed by the compiler: advanced compilation time optimizations minification (only fe in production mode) g-zip compression (only fe in production mode) Important!The resulting JavaScript and CSS files from fe in production mode are gzip compressed for performance (see Gzip Components), so make sure to provide a &quot;Content-Encoding&quot; header to the browser (e.g. res.setHeader('Content-Encoding', 'gzip');). × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"Compiler.html":{"id":"Compiler.html","title":"Class: Compiler","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Class: Compiler Compiler &lt;abstract&gt; new Compiler(compress) The base compiler class Parameters: Name Type Argument Default Description compress boolean &lt;optional&gt; true if true Compiler#optimize will gzip compress the data in production mode Source: Compiler.js, line 11 Members &lt;readonly&gt; isProduction :boolean True if the NODE_ENV environment variable is equal to production. Caution: modifying it's value directly may lead to unexpected results Type: boolean Source: Compiler.js, line 19 Methods &lt;static&gt; done(inPath, callback) Executed when the compilation is complete Parameters: Name Type Description inPath string the input path callback function a callback function Source: Compiler.js, line 46 Example Compiler.done('/path/to/an/input/file', callback); &lt;static&gt; fsWrite(path, data, callback) Writes the data to disk Parameters: Name Type Description path string the output path data ProgramData the data to write callback function a callback function Source: Compiler.js, line 82 Example Compiler.fsWrite('/path/to/an/output/file', data, callback); &lt;static&gt; gzip(data, callback) G-zips the compiled code Parameters: Name Type Description data ProgramData the actual program data to auto-prefix callback ProgramDataCallback a callback function Source: Compiler.js, line 133 Example Compiler.gzip(data, callback); &lt;static&gt; mkdir(path, callback) Recursively creates a directory containing a file specified by path. Parameters: Name Type Description path string a path to a file callback function a callback function Source: Compiler.js, line 113 Example Compiler.mkdir('/path/to/a/file', callback); &lt;protected&gt; optimize(inPath, outPath, data, callback) G-zips the program if necessary and writes the results to disk. Parameters: Name Type Description inPath string the input path outPath string the output path data ProgramData processed application code with source maps callback function a callback function Source: Compiler.js, line 153 Example compiler.optimize('/path/to/an/input/file', '/path/to/the/output/file', data, callback); × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"DevServer.html":{"id":"DevServer.html","title":"Class: DevServer","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Class: DevServer DevServer new DevServer(script, style, devDir, port, react) A lightweight development server that rapidly recompiles the JavaScript and SASS files when they are edited and updates the page. Utilizes the Webpack development server. Includes react hot loader to further optimize the development process of the React applications. Please install and enable the LiveReload browser extension for the CSS reloading to work. Parameters: Name Type Argument Default Description script string a full system path to a JavaScript file style string a full system path to a SASS file devDir string a full system path to a directory in which to put any compiled development resources port number &lt;optional&gt; 3000 a port at which to start the dev server react boolean &lt;optional&gt; true false to disable the react hot loader plugin Source: DevServer.js, line 13 See: webpack-dev-server React Hot Loader Example import {DevServer} from 'webcompiler'; import {join} from 'path'; const rootDir = join(__dirname, '..'), devDir = join(rootDir, 'development'), server = new DevServer(join(devDir, 'script.js'), join(devDir, 'app.scss'), devDir); server.run(rootDir); // now navigate to http://localhost:3000 using your favorite browser ( preferably Chrome :) ) Methods run(watchDir) Starts the Webpack development server, compiles SASS and starts watching for file changes Parameters: Name Type Description watchDir string the directory in which to watch for the changes in the SASS files Source: DevServer.js, line 182 Example server.run('/path/to/some/directory'); watchJS() Starts the Webpack development server Source: DevServer.js, line 162 Example server.watchJS(); watchSASS(watchDir) Compile SASS and start watching for file changes Parameters: Name Type Description watchDir string the directory in which to watch for the changes in the SASS files Source: DevServer.js, line 146 Example server.watchSASS('/path/to/some/directory'); × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"Documentation.html":{"id":"Documentation.html","title":"Class: Documentation","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Class: Documentation Documentation new Documentation(config) Generates API documentation The default JSDoc plugin specified in jsdocConfig strips out all of the code from a file while retaining newlines (unlike the built in commentsOnly plugin that ships with JSDoc3). That way: line numbers are preserved in the source view you don't need to use a pre-compiler, you will always see the same code as you wrote in the docs source view since JSDoc only sees comments you can use any code syntax you like - ES2015, ES7, JSX, it doesn't even have to be JavaScript. The markdown plugin is also included by default. Parameters: Name Type Argument Default Description config DocumentationConfig &lt;optional&gt; {} a configuration object Source: Documentation.js, line 19 Example import {Documentation} from 'webcompiler'; const docs = new Documentation(); Methods run(callback) Generate the documentation Parameters: Name Type Argument Default Description callback function &lt;optional&gt; function () {} a callback function Source: Documentation.js, line 128 Returns: Type void Example docs.run(() =&gt; { // generated the API documentation }); × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"JS.html":{"id":"JS.html","title":"Class: JS","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Class: JS JS new JS(compress, babelOptions, lintRules) JavaScript compilation tools Parameters: Name Type Argument Default Description compress boolean &lt;optional&gt; true if true Compiler#optimize will gzip compress the data babelOptions Object &lt;optional&gt; {} allows to override the default Babel options lintRules Object &lt;optional&gt; {} allows to override the default linting rules Source: JS.js, line 9 Example import {JS} from 'webcompiler'; const js = new JS(); Methods be(inPath, outPath, lintPaths, callback) Wraps JSCompiler#be to add static analysis and linting Parameters: Name Type Argument Default Description inPath string the input path outPath string the output path lintPaths Array.&lt;string&gt; &lt;optional&gt; [] an array of paths to files/directories to lint callback function &lt;optional&gt; function () {} a callback function Source: JS.js, line 130 Returns: Type void Example compiler.be('/path/to/an/input/file.js', '/path/to/the/output/file.js', ['/lint/this/directory/too'], () =&gt; { // the code has passed all the checks and has been compiled successfully }); fe(inPath, outPath, lintPaths, callback) Wraps JSCompiler#fe to add static analysis and linting Parameters: Name Type Argument Default Description inPath string the input path outPath string the output path lintPaths Array.&lt;string&gt; &lt;optional&gt; [] an array of paths to files/directories to lint callback function &lt;optional&gt; function () {} a callback function Source: JS.js, line 152 Returns: Type void Example compiler.fe('/path/to/an/input/file.js', '/path/to/the/output/file.js', ['/lint/this/directory/too'], () =&gt; { // the code has passed all the checks and has been compiled successfully }); lint(paths, callback) Performs linting Parameters: Name Type Description paths Array.&lt;string&gt; an array of paths to files/directories to lint callback function a callback function, invoked only when successfully linted Source: JS.js, line 82 Example js.lint(['/path/to/the/input/file.js', '/lint/this/directory/too'], () =&gt; { // successfully linted }); typecheck(callback) Performs static analysis Parameters: Name Type Description callback function a callback function, invoked only when successfully typechecked Source: JS.js, line 58 Example js.typecheck(() =&gt; { // successfully typechecked }); × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"JSCompiler.html":{"id":"JSCompiler.html","title":"Class: JSCompiler","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Class: JSCompiler JSCompiler new JSCompiler(compress, options) A JavaScript compiler Parameters: Name Type Argument Default Description compress boolean &lt;optional&gt; true if true Compiler#optimize will gzip compress the data options Object &lt;optional&gt; {} allows to override the default Babel options Source: JSCompiler.js, line 24 Example import {JSCompiler} from 'webcompiler'; const compiler = new JSCompiler(); Extends Compiler Members &lt;readonly&gt; isProduction :boolean True if the NODE_ENV environment variable is equal to production. Caution: modifying it's value directly may lead to unexpected results Type: boolean Inherited From: Compiler#isProduction Source: Compiler.js, line 19 Methods be(inPath, outPath, callback) Compiles a JavaScript file or a directory for the back end. Non-JavaScript files are simply copied over. Parameters: Name Type Argument Default Description inPath string the input path outPath string the output path callback function &lt;optional&gt; function () {} a callback function Source: JSCompiler.js, line 185 Returns: Type void Example compiler.be('/path/to/an/input/file.js', '/path/to/the/output/file.js', callback); fe(inPath, outPath, callback) Compiles, bundles (in production mode also minifies and g-zips) a JavaScript file for the front end. Parameters: Name Type Argument Default Description inPath string the input path outPath string the output path callback function &lt;optional&gt; function () {} a callback function Source: JSCompiler.js, line 209 Example compiler.fe('/path/to/an/input/file.js', '/path/to/the/output/file.js', callback); &lt;protected&gt; optimize(inPath, outPath, data, callback) G-zips the program if necessary and writes the results to disk. Parameters: Name Type Description inPath string the input path outPath string the output path data ProgramData processed application code with source maps callback function a callback function Inherited From: Compiler#optimize Source: Compiler.js, line 153 Example compiler.optimize('/path/to/an/input/file', '/path/to/the/output/file', data, callback); × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"JSLint.html":{"id":"JSLint.html","title":"Class: JSLint","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Class: JSLint JSLint new JSLint(rules) A JavaScript linter Parameters: Name Type Argument Default Description rules Object &lt;optional&gt; {} an object that lets you override default linting rules Source: JSLint.js, line 10 Example import {JSLint} from 'webcompiler'; import {join} from 'path'; const linter = new JSLint(); Methods run(paths, callback) Execute the linter Parameters: Name Type Description paths Array.&lt;string&gt; an array of paths to files/directories to lint callback JSLintCallback a callback function, accepts 1 argument: an array of error objects or null Source: JSLint.js, line 36 Example // lint &quot;index.js&quot; as well as the entire contents of the &quot;src&quot; directory linter.run([join(__dirname, 'index.js'), join(__dirname, 'src')], function (err) { if (err) { return e.forEach(e =&gt; { console.log('\\x1b[41mESLint error\\x1b[0m &quot;\\x1b[33m%s%s\\x1b[0m&quot; in \\x1b[36m%s\\x1b[0m on \\x1b[35m%s:%s\\x1b[0m', e.message, e.ruleId ? ` (${e.ruleId})` : '', e.filePath, e.line, e.column); }); } // there were no linting errors }); × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"Markup.html":{"id":"Markup.html","title":"Class: Markup","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Class: Markup Markup new Markup(transformers) Allows to easily and efficiently convert text from Markdown to HTML and from HTML to a collection of React Elements that can be used directly in a JSX expression. Whenever an HTML string is involved, runs it through an array of Transformer functions. Parameters: Name Type Argument Description transformers Transformer &lt;repeatable&gt; transformers to initialize with Source: Markup.js, line 18 Example import {Markup} from 'webcompiler'; const mark = new Markup(); Methods &lt;static&gt; flatten(args) Recursively flattens args and combines string values. Can be used as a simple optimization step on the JSX children-to-be to simplify the resulting DOM structure by joining adjacent text nodes together. Parameters: Name Type Argument Description args * &lt;repeatable&gt; the input array Source: Markup.js, line 171 Returns: the flattened result Type Array.&lt;*&gt; Example Markup.flatten('lorem ', ['ipsum ', ['dolor ', ['sit ', ['amet']]]]); // [&quot;lorem ipsum dolor sit amet&quot;] htmlToJSX(html) Converts an arbitrary HTML string to an array of React Elements Parameters: Name Type Argument Default Description html string &lt;optional&gt; &quot;&quot; an arbitrary HTML string Source: Markup.js, line 211 Returns: an array of React Elements Type Array.&lt;ReactElement&gt; Example &lt;div&gt;{mark.htmlToJSX('Hello &lt;span&gt;world!&lt;/span&gt;')}&lt;/div&gt; markdownToHTML(markdown) Converts an arbitrary Markdown string to an HTML string Parameters: Name Type Argument Default Description markdown string &lt;optional&gt; &quot;&quot; an arbitrary Markdown string Source: Markup.js, line 227 Returns: an HTML string Type string Example mark.markdownToHTML('# Hello world!'); // &lt;h1&gt;Hello world!&lt;/h1&gt; markdownToJSX(markdown) Converts an arbitrary Markdown string to an array of React Elements Parameters: Name Type Argument Default Description markdown string &lt;optional&gt; &quot;&quot; an arbitrary Markdown string Source: Markup.js, line 243 Returns: an array of React Elements Type Array.&lt;ReactElement&gt; Example &lt;div&gt;{mark.markdownToJSX('# Hello world!')}&lt;/div&gt; × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"NativeProcess.html":{"id":"NativeProcess.html","title":"Class: NativeProcess","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Class: NativeProcess NativeProcess new NativeProcess(task) Encapsulates a ChildProcess instance of a task Parameters: Name Type Description task string a process name Source: NativeProcess.js, line 7 Example import {NativeProcess} from 'webcompiler'; const mkdir = new NativeProcess('mkdir'); Methods kill() Kills the process if any is running Source: NativeProcess.js, line 88 Example someEpensiveProcess.kill(); run(callback, args, opts) Execute the command Parameters: Name Type Argument Default Description callback NativeProcessCallback &lt;optional&gt; function () {} a callback function args Array.&lt;string&gt; &lt;optional&gt; [] an array of arguments to pass to the process opts Object &lt;optional&gt; {} a configuration object for the process Source: NativeProcess.js, line 43 Returns: Type void Example mkdir.run(error =&gt; { if (error) { return console.error(error); } // created a directory named &quot;example&quot; in cwd }, ['example']); × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"SASS.html":{"id":"SASS.html","title":"Class: SASS","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Class: SASS SASS new SASS(compress, includePaths, excludeLinter, importOnceOptions) SASS compilation tools Parameters: Name Type Argument Default Description compress boolean &lt;optional&gt; true if true Compiler#optimize will gzip compress the data includePaths Array.&lt;string&gt; &lt;optional&gt; [] an array of additional include paths excludeLinter Array.&lt;string&gt; &lt;optional&gt; [] names of linters to exclude importOnceOptions Object &lt;optional&gt; {} an object that lets you override default importOnce resolver configuration Source: SASS.js, line 7 Example import {SASS} from 'webcompiler'; const sass = new SASS(); Methods fe(inPath, outPath, lintPaths, callback) Wraps SASSCompiler#fe to add linting Parameters: Name Type Argument Default Description inPath string the input path outPath string the output path lintPaths Array.&lt;string&gt; &lt;optional&gt; [] an array of paths to files/directories to lint callback function &lt;optional&gt; function () {} a callback function Source: SASS.js, line 70 Returns: Type void Example compiler.fe('/path/to/an/input/file.js', '/path/to/the/output/file.js', ['/lint/this/directory/too'], () =&gt; { // the code has passed all the checks and has been compiled successfully }); lint(paths, callback) Performs linting Parameters: Name Type Description paths Array.&lt;string&gt; an array of paths to lint callback function a callback function Source: SASS.js, line 48 Example sass.lint(['/path/to/the/input/file.scss', '/lint/this/directory/too'], () =&gt; { // successfully linted }); × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"SASSCompiler.html":{"id":"SASSCompiler.html","title":"Class: SASSCompiler","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Class: SASSCompiler SASSCompiler new SASSCompiler(compress, includePaths, importOnceOptions) A SASS compiler Parameters: Name Type Argument Default Description compress boolean &lt;optional&gt; true if true Compiler#optimize will gzip compress the data includePaths Array.&lt;string&gt; &lt;optional&gt; [] an array of additional include paths importOnceOptions Object &lt;optional&gt; {} an object that lets you override default importOnce resolver configuration Source: SASSCompiler.js, line 16 Example import {SASSCompiler} from 'webcompiler'; const compiler = new SASSCompiler(); Extends Compiler Members &lt;readonly&gt; isProduction :boolean True if the NODE_ENV environment variable is equal to production. Caution: modifying it's value directly may lead to unexpected results Type: boolean Inherited From: Compiler#isProduction Source: Compiler.js, line 19 Methods &lt;static&gt; autoprefix(path, data, callback) Auto-prefixes the compiled code Parameters: Name Type Description path string a path to the file data ProgramData the actual program data to auto-prefix callback ProgramDataCallback a callback function Source: SASSCompiler.js, line 57 Example SASSCompiler.autoprefix('/path/to/the/output/file.css', data, result =&gt; { // successfully added the vendor prefixes }); fe(inPath, outPath, callback) Compiles, auto-prefixes and optionally minifies and g-zips in the production mode Parameters: Name Type Argument Default Description inPath string a full system path to the input file outPath string a full system path to the output file callback function &lt;optional&gt; function () {} a callback function Source: SASSCompiler.js, line 88 Example compiler.fe('/path/to/the/input/file.scss', '/path/to/the/output/file.css', () =&gt; { // compiled successfully }); &lt;protected&gt; optimize(inPath, outPath, data, callback) G-zips the program if necessary and writes the results to disk. Parameters: Name Type Description inPath string the input path outPath string the output path data ProgramData processed application code with source maps callback function a callback function Inherited From: Compiler#optimize Source: Compiler.js, line 153 Example compiler.optimize('/path/to/an/input/file', '/path/to/the/output/file', data, callback); × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "},"SASSLint.html":{"id":"SASSLint.html","title":"Class: SASSLint","body":" Documentation Classes CompilerDevServerDocumentationJSJSCompilerJSLintMarkupNativeProcessSASSSASSCompilerSASSLint Global watchyaml Class: SASSLint SASSLint new SASSLint(excludeLinter) A SASS linter Parameters: Name Type Argument Description excludeLinter string &lt;repeatable&gt; names of linters to exclude Source: SASSLint.js, line 9 Example import {SASSLint} from 'webcompiler'; import {join} from 'path'; const linter = new SASSLint(); Methods run(paths, callback) Execute the linter Parameters: Name Type Description paths Array.&lt;string&gt; an array of paths to files/directories to lint callback function a callback function, accepts 1 argument: an error message or null Source: SASSLint.js, line 46 Example // lint &quot;style.scss&quot; as well as the entire contents of the &quot;sass&quot; directory linter.run([join(__dirname, 'style.scss'), join(__dirname, 'sass')], error =&gt; { if (error) { return console.error(error); } // there were no linting errors }); × Search results Close Documentation generated by JSDoc 3.4.0 using the DocStrap template. "}}
     </script>
 
     <script type="text/javascript">
diff --git a/lib/Markup.js b/lib/Markup.js
index 1346b2c..bc37cd9 100644
--- a/lib/Markup.js
+++ b/lib/Markup.js
@@ -168,7 +168,7 @@ var Markup = exports.Markup = function () {
       var markdown = arguments.length <= 0 || arguments[0] === undefined ? '' : arguments[0];
 
       markdown = (0, _trim2.default)(markdown);
-      return markdown ? (0, _trim2.default)(this.transform((0, _marked2.default)(markdown))) : '';
+      return markdown ? (0, _trim2.default)(this.transform(Markup.markdownToUnwrappedHTML(markdown))) : '';
     }
 
     /**
@@ -189,7 +189,7 @@ var Markup = exports.Markup = function () {
       var markdown = arguments.length <= 0 || arguments[0] === undefined ? '' : arguments[0];
 
       markdown = (0, _trim2.default)(markdown);
-      return markdown ? this.htmlToJSX((0, _marked2.default)(markdown)) : [];
+      return markdown ? this.htmlToJSX(Markup.markdownToUnwrappedHTML(markdown)) : [];
     }
   }], [{
     key: 'toJSXKey',
@@ -305,6 +305,32 @@ var Markup = exports.Markup = function () {
       });
     }
 
+    /**
+     * If a simple single line string is passed to the Markdown parser it thinks that it's a paragraph (it sort of
+     * technically is) and unnecessarily wraps it into `<p></p>`, which most often is not the desired behavior.
+     *
+     * This function converts Markdown to HTML and then removes the wrapping paragraph if it is the only top level tag
+     * unwrapping its contents.
+     *
+     * @memberof Markup
+     * @static
+     * @private
+     * @method markdownToUnwrappedHTML
+     * @param {string} markdown - an arbitrary Markdown string
+     * @return {string} an HTML string
+     */
+
+  }, {
+    key: 'markdownToUnwrappedHTML',
+    value: function markdownToUnwrappedHTML(markdown) {
+      var html = (0, _trim2.default)((0, _marked2.default)(markdown));
+      var dom = (0, _cheerio.load)(html);
+      var children = dom.root().toArray()[0].children;
+
+
+      return 1 === children.length && 'tag' === children[0].type && 'p' === children[0].name ? dom('p').html() : html;
+    }
+
     /**
      * Recursively flattens `args` and combines string values.
      *
diff --git a/package.json b/package.json
index 5ab82a4..778f6c3 100644
--- a/package.json
+++ b/package.json
@@ -76,7 +76,7 @@
     "eslint-plugin-react": "^3.16.1",
     "fb-watchman": "^1.9.0",
     "ink-docstrap": "^1.1.1",
-    "js-yaml": "^3.5.2",
+    "js-yaml": "^3.5.3",
     "jsdoc": "^3.4.0",
     "json-loader": "^0.5.4",
     "lodash": "^4.3.0",
@@ -85,7 +85,7 @@
     "mkdirp": "^0.5.1",
     "node-sass": "^3.4.2",
     "node-sass-import-once": "^1.2.0",
-    "postcss": "^5.0.14",
+    "postcss": "^5.0.15",
     "react": "^0.14.7",
     "react-hot-loader": "^1.3.0",
     "tiny-lr": "^0.2.1",
diff --git a/src/Markup.js b/src/Markup.js
index 353d768..a584678 100644
--- a/src/Markup.js
+++ b/src/Markup.js
@@ -146,6 +146,28 @@ export class Markup {
     return map(reject(children, ['type', 'comment']), (c, i) => 'text' === c.type ? c.data : Markup.childToJSX(c, i));
   }
 
+  /**
+   * If a simple single line string is passed to the Markdown parser it thinks that it's a paragraph (it sort of
+   * technically is) and unnecessarily wraps it into `<p></p>`, which most often is not the desired behavior.
+   *
+   * This function converts Markdown to HTML and then removes the wrapping paragraph if it is the only top level tag
+   * unwrapping its contents.
+   *
+   * @memberof Markup
+   * @static
+   * @private
+   * @method markdownToUnwrappedHTML
+   * @param {string} markdown - an arbitrary Markdown string
+   * @return {string} an HTML string
+   */
+  static markdownToUnwrappedHTML(markdown: string): string {
+    const html = trim(marked(markdown)),
+        dom = load(html),
+        {children} = dom.root().toArray()[0];
+
+    return 1 === children.length && 'tag' === children[0].type && 'p' === children[0].name ? dom('p').html() : html;
+  }
+
   /**
    * Recursively flattens `args` and combines string values.
    *
@@ -215,7 +237,7 @@ export class Markup {
    */
   markdownToHTML(markdown: string = ''): string {
     markdown = trim(markdown);
-    return markdown ? trim(this.transform(marked(markdown))) : '';
+    return markdown ? trim(this.transform(Markup.markdownToUnwrappedHTML(markdown))) : '';
   }
 
   /**
@@ -231,7 +253,7 @@ export class Markup {
    */
   markdownToJSX(markdown: string = ''): Array<any> {
     markdown = trim(markdown);
-    return markdown ? this.htmlToJSX(marked(markdown)) : [];
+    return markdown ? this.htmlToJSX(Markup.markdownToUnwrappedHTML(markdown)) : [];
   }
 
 }
diff --git a/test/Markup.spec.js b/test/Markup.spec.js
index 3606c12..e2e3b26 100644
--- a/test/Markup.spec.js
+++ b/test/Markup.spec.js
@@ -14,7 +14,7 @@ let marked, Markup, object, cmp, args, attribs;
 describe('Markup', () => {
 
   beforeEach(() => {
-    marked = stub().returns('<h1>Hello world!</h1>');
+    marked = stub().returnsArg(0);
     Markup = proxyquire('../src/Markup', {marked}).Markup;
   });
 
@@ -208,6 +208,42 @@ describe('Markup', () => {
 
   });
 
+  describe('markdownToUnwrappedHTML', () => {
+
+    beforeEach(() => {
+      spy(Markup, 'markdownToUnwrappedHTML');
+    });
+
+    afterEach(() => {
+      Markup.markdownToUnwrappedHTML.restore();
+    });
+
+    describe('unwrap', () => {
+
+      beforeEach(() => {
+        Markup.markdownToUnwrappedHTML(' <p>something</p> ');
+      });
+
+      it('returns result', () => {
+        expect(Markup.markdownToUnwrappedHTML).returned('something');
+      });
+
+    });
+
+    describe('do not unwrap', () => {
+
+      beforeEach(() => {
+        Markup.markdownToUnwrappedHTML('<h1>something</h1>');
+      });
+
+      it('returns result', () => {
+        expect(Markup.markdownToUnwrappedHTML).returned('<h1>something</h1>');
+      });
+
+    });
+
+  });
+
   describe('flatten', () => {
 
     beforeEach(() => {
@@ -292,11 +328,7 @@ describe('Markup', () => {
       describe('arg', () => {
 
         beforeEach(() => {
-          cmp.markdownToHTML('# Hello world!');
-        });
-
-        it('calls marked', () => {
-          expect(marked).calledWith('# Hello world!');
+          cmp.markdownToHTML('<h1>Hello world!</h1>');
         });
 
         it('calls transform', () => {
@@ -338,11 +370,7 @@ describe('Markup', () => {
       describe('arg', () => {
 
         beforeEach(() => {
-          cmp.markdownToJSX('# Hello world!');
-        });
-
-        it('calls marked', () => {
-          expect(marked).calledWith('# Hello world!');
+          cmp.markdownToJSX('<h1>Hello world!</h1>');
         });
 
         it('calls htmlToJSX', () => {