BuildOptions

  • typedef
steal-tools.BuildOptions {Object}  

Options used to configure the build process.

Object

Properties

  1. minify=true {Boolean | function()}Optional

    Boolean

    Sets whether the source code is minified prior to writing.

    Minification is optional but on by default, you can turn it off by doing:

    stealtools.build(config, {
        minify: false
    });
    

    Function

    A function can be provided to handle minification of each file in a bundle, e.g:

    stealTools.build(config, {
        minify: function(source, options) {
            // use your own library to minify source.code 
            source.code = doCustomMinification(source.code);
    
            // return the source object when minification is complete
            return source;
        }
    });
    

    The function takes a source object as the first parameter, this object contains the code and its AST version after the transpilation process; the second parameter, options, is the BuildOptions object passed to configure the build process.

  2. bundleSteal=false {Boolean}Optional

    Sets whether StealJS will be included in the built file. Enabling this option will allow you to limit the initial request to just one script.

  3. verbose=false {Boolean}Optional

    true turns on verbose output. Defaults to false.

  4. quiet=false {Boolean}Optional

    No logging. Defaults to false.

  5. dest="dist" {String}Optional

    Specifies the destination folder for the build. By default steal-tools will write to the BASEURL + '/dist' folder where BASEURL is the local Steal baseURL, usually the same folder that your package.json is located.

    The path can be specified in three ways:

    • Absolute path - dest starts with /, or matches /^\w+:[/\]/, like: __dirname+"/place", or "c:\my\bundles".
    • Relative to process.cwd() - dest starts with ./, like "./place".
    • Relative to baseURL - dest looks like: "packages", "foo/bar".
  6. bundleAssets=false {BundleAssetsOptions | Boolean}Optional

    Set to true to have assets from your project bundled into your dest folder.

  7. ignore {Array<moduleName>}

    An array of module names that should be ignored and not included in the bundled file. For more information take a look at the ignore usage http://stealjs.com/docs/steal-tools.build.html#ignore

  8. maxBundleRequests=3 {Number}Optional

    The maximum number of bundles that need to be loaded for any bundle module. Defaults to 3.

  9. maxMainRequests=3 {Number}Optional

    The maximum number of bundles that will be loaded for any main module. Defaults to 3.

  10. removeDevelopmentCode=true {Boolean}Optional

    Remove any development code from the bundle specified using //!steal-remove-start, and //!steal-remove-end comments.

  11. cleanCSSOptions {Object}Optional

    A hash of options to customize the minification of css files. All available options are listed in the clean-css documentation.

  12. uglifyOptions {Object}Optional

    A hash of options to customize the minification of JavaScript files. StealTools uses the top-level minify function of uglify-js, and the available options are listed here.

    For example, to not uglify function names you can use keep_fnames option:

    stealTools.build(config, {
      uglifyOptions: {
        mangle: { "keep_fnames": true }
      }
    });
    
  13. sourceMaps=false {Boolean}Optional

    Generate source maps alongside your bundles.

  14. sourceMapsContent=false {Boolean}Optional

    Include the original source contents in the generated source maps. Use this option if your production environment doesn't have access to the source files. Will result in a larger source maps size but will cause fewer requests.

  15. transpile {Transpile(source, compileOptions)}Optional

    A function that handles the transpiling of ES6 source to a format for production.

  16. watch=false {Boolean}Optional

    Actives watch mode which will continuously build as you develop your application.

  17. envify=false {Boolean}Optional

    Replace Node-style environment variables with plain strings.

    steal-tools uses loose-envify under the hood, this option is specially useful when building React.js applications.

    Usage:

    First, make sure NODE_ENV is set appropiately, then just turn on the envify option; if you're using the steal-tools CLI modify your build command to look like:

    NODE_ENV=production steal-tools build --envify
    

    or, if you're using the build API just pass the option like this:

    stealTools.build({}, {
        envify: true
    });
    
  18. splitLoader=false {Boolean}Optional

    Writes the optimized loader in its own bundle.

    By default the, optimize will add the loader code to the main bundle, if splitLoader is set to true, a bundle called loader.js will be created; in order to load the application the loader has to be loaded like any other bundle.

    <script src="./dist/bundles/loader.js" async></script>
    <script src="./dist/bundles/my-app.js" async></script>
    

    This option is only available for the optimize command.

  19. target {String | Array<String>}Optional

    Specifies the platform where the application is going to be deployed.

    Usage:

    stealTools.build({}, { 
      target: "node"
    });
    

    Setting target to node makes the loader suitable to run on Node.js environments (require is used to load bundles instead of script tags); currently the targets supported are: node, web, and worker (Web Workers).

    Multiple targets can be set by passing an array of supported targets, e.g:

    stealTools.build({}, { 
      target: ["node", "web"]
    });
    

    When target is not set the bundle will be written out to its default location (See dest property above), but when single or multiple targets are provided, the build assets will be written out inside folders matching the target name.

    For example, a build targeting both node and web will look like the tree below:

    ├── dist
        │   └── bundles
        │       ├── node
        │       │   └── (... application assets)
        │       └── web
        │           └── (... application assets)
    

    This option is only available for the optimize command.

  20. bundleManifest=false {Boolean | String}Optional

    Generates an HTTP2-push like manifest of the application bundles for server-side preload.

    When set to true a bundles.json file will be written at the top level of the folder where the built assets are located (see the propertydest above).

    A full path to the desired JSON filename can be provided, too. e.g:

    stealTools.build(config, { 
      bundleManifest: path.join(__dirname, "dist", "my-manifest.json")
    });
    

    The manifest has the following shape:

    {
      "[ENTRY-POINT-BUNDLE-NAME]": {
        "[SHARED-BUNDLE-NAME]": {
          "type": "style",
          "weight": 1
        },
        "[SHARED-BUNDLE-NAME]": {
          "type": "script",
          "weight": 2
        }
      }
    }
    

    The top-level objects correspond to entry level bundles; these are the bundles needed to start up individual "pages" of the application and progressively loaded bundles.

    The nested objects are shared bundles, these are created by steal-tools to minimize the number of HTTP requests needed to load the application code.

    Each shared bundle has two properties, type, an string that indicates whether the bundle contains script code or styles and weight, a number indicating loading priority; a bundle with lower weight should be loaded before other bundles, e.g: style bundles have weight of 1 and should be loaded before script bundles.

  21. bundlePromisePolyfill=true {Boolean}Optional

    Bundles a Promise polyfill with StealJS core

    By default, build will add a Promise polyfill as part of the StealJS core. If Promises are supported natively in the target environment of your application you can turn this flag off to prevent the polyfill to be included, like this:

    stealTools.build(config, {
        bundlePromisePolyfill: false
    });
    

    steal-tools will write a file called steal.sans-promises.production.js to the bundles folder, make sure the script tag in your main html page loads the correct file, e.g:

    <script src="./dist/steal.sans-promises.production.js"></script>
    

    The bundlePromisePolyfill also changes the default behavior of [bundleSteal], meaning that the Promise polyfill will be excluded from StealJS core regardless of whether it is part of the main bundle or not.

    To bundle StealJS without the Promise polyfill just pass the following options to build:

    stealTools.build(config, {
        bundleSteal: true,
        bundlePromisePolyfill: false
    });