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=true {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; by default the build command will turn envify on, just run:

    NODE_ENV=production steal-tools build
    

    If you want to turn off this behavior, just pass the following flag to the CLI:

    NODE_ENV=production steal-tools build --no-envify
    

    or, set the flag to false when using the build API, like this:

    stealTools.build({}, {
        envify: false
    });
    
  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.optimize({}, {
      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.optimize({}, {
      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=false {Boolean}Optional

    Bundles a Promise polyfill with StealJS core

    By default, steal-tools's output requires Promises being natively supported in the target environment where the application runs; if Promises are not supported, turn on this flag to include the polyfill in your built code, e.g:

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

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

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

    The bundlePromisePolyfill flag also changes the default behavior of the build command when bundleSteal is set; the Promise polyfill will be included in StealJS core regardless of whether StealJS's code is part of the main bundle or not.

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

    stealTools.build(config, {
        bundleSteal: true,
        bundlePromisePolyfill: true
    });
    
  22. treeShaking=true {Boolean}Optional

    Tree shakes the dependency graph, removing dead code created from unused exports. For more information on how tree shaking works, see the Tree Shaking topic.

    Tree shaking is enabled by default. Set this flag to false if you would like to disable it (this might be necessary in legacy applications that depend on side effects created by unused exports).

    stealTools.build(config, {
        treeShaking: false
    });
    
Help us improve StealJS by taking our community survey