Customize Optimization

When your visual application is stage and publish, each web application's resources are optimized to improve performance. If you want to specify the resources you want to include and exclude in the optimized resources bundle, you can define your own optimization configuration in a build.json file.

Optimization, by default, includes all application resources that match the regular expression .*(\\.(js|json|html|css))$ in an optimized resources bundle named vb-app-bundle. During this process, application stylesheets, HTML, and JSON files are minified, and RequireJS bundles created in the embedded build server that prepares your visual application to be stage and publish. To customize this configuration to include and exclude resources, you'll need to create a build.json file and define your own configuration before staging and publishing your application.

1. Select the web application in the Navigator, then click Settings to open the app-level Settings editor.
2. Click Create Build Configuration under Optimization to create the build.json file. If the file already exists, click Open Build Configuration.
3. Define your build configuration in the build.json editor to specify the resources you want to include in and exclude from the optimized resources bundle.
   Here's the schema you must use to define optimization in build.json under the optimize element:

   Property	Description
   optimize.suppress	(Boolean) If set to true, optimization is disabled. If the property is not defined or is set to false, optimization is determined by the Optimize Application setting defined in a Packaging build step, or by individual optimizer settings (for example, optimize.require-js.enable). Default is false, meaning resources are always optimized before the visual application is stage and publish. It's simpler to disable optimization from the Settings editor, instead of manually editing build.json. See Suppress Optimization.
   optimize.require-js	(Object) Configuration of the RequireJS optimizer that generates resource bundles.
   optimize.require-js.enable	(Boolean) Whether RequireJS module bundles should be created. Enabled by default.
   optimize.require-js.vb-bundles-config	(Object) Custom RequireJS module bundles, defined using this schema: <bundle_name> find ids modules find ids exclude find ids
   optimize.require-js.vb-bundles-config.bundle_name.modules	Modules that should be added to the bundle, defined using this schema: find ids
   optimize.require-js.vb-bundles-config.bundle_name.exclude	Modules that should not be added to the bundle, defined using this schema: find ids Exclusions are applied to all bundle modules, including those added following transitive module dependencies.
   optimize.require-js.vb-bundles-config.bundle_name.[exclude|modules].find	List of regular expression patterns used for matching optimized application resources. Regular expressions starting with an exclamation mark (!) are considered negative; resources matching these patterns won't be included.
   optimize.require-js.vb-bundles-config.bundle_name.[exclude|modules].ids	List of module IDs
   optimize.require-js.emptyPaths	(Array) Comma-separated list of RequireJS paths that are set to empty. This way, you indicate that this dependency must be ignored (and also that its sub-dependencies must not be recursively traversed).
   optimize.css	(Object) Whether stylesheets should be optimized. Enabled by default.
   optimize.css.enable	(Boolean) Set to false to disable stylesheet optimization.
   optimize.html	(Object) Whether HTML files should be optimized. Enabled by default.
   optimize.html.enable	(Boolean) Set to false to disable HTML file optimization.
   optimize.json	(Object) Whether JSON files should be optimized. Enabled by default.
   optimize.json.enable	(Boolean) Set to false to disable JSON file optimization.

   For default and other example configurations, see Optimization Configurations for build.json.

   Tip:

   If you use Grunt tasks to optimize your app, you must migrate your existing Grunt configuration from Gruntfile.js into build.json, so your custom configuration can take effect during resource optimization when your visual application is stage and publish. The configuration in build.json is similar to what you define in Gruntfile.js. See How to Migrate Gruntfile.js Configuration Into build.json.

Optimization Configurations for build.json

When you create the build.json file (located under /webApps/app_name/settings and accessible from the app-level Settings editor), you can specify the resources you want to include and exclude in the application's optimized resources bundle.

Include all resources and exclude specific ones

Optimization, by default, includes all application resources that match the regular expression .*(\\.(js|json|html|css))$ to an optimized resources bundle named vb-app-bundle. Here's a look at the default settings:

{
    "optimize": {
        "require-js": {
            "vb-bundles-config": {
                "vb-app-bundle": {
                    "modules": {
                        "find": [
                            ".*(.(js|json|html|css))$"
                        ]
                    }
                }
            }
        }
    }
}

You can extend this configuration, for example, to exclude some third-party libraries that are part of the application's sources, say, bcrypt.min and crypto-js (defined for the deal-registration flow). In this case, here's how you might define build.json:

{
    "optimize": {
        "require-js": {
            "vb-bundles-config": {
                "vb-app-bundle": {
                    "modules": {
                        "find": [
                            ".*(.(js|json|html|css))$",
                            "!bcrypt.min",
                            "!^flows/deal-registration/crypto-js"
                        ]
                    }
                }
            }
        }
    }
}

The find element specifies a list of regular expressions that are matched against your application. Regular expressions starting with an exclamation mark (!) are considered negative, so resources matching these patterns are not included.

Include and exclude specific resources

Here's an example that adds specific resources to vb-app-bundle, but excludes the fontawesome file:

{
    "optimize": {
        "require-js": {
            "vb-bundles-config": {
                "vb-app-bundle": {
                    "modules": {
                        "find": [
                            "app-flow.js",
                            "^build",
                            "!^build/components/oj-odcs/2.5.1/fontawesome",
                            "^flows/",
                            "^pages/",
                            "^resources/strings",
                            "^resources/css",
                            "^services/"
                        ]
                    }
                }
            }
        }
    }
}

How you organize your app's resources into bundles depends on your application's structure as well as what you deem critical for application start. Try to bundle resources in such a way that what's really needed by the application is placed in one bundle while the rest goes into one or more other bundles.

Here's an example of configuration defined to create three specific RequireJS module bundles:

• One for all resources that belong to the application flow dashboard. This bundle includes all files that match the flows/dashboard pattern (in other words, all pages, modules, resources, and nested flows stored in the flows/dashboard directory). It, however, excludes the helpers module, referred by one of the page modules.
• Two for resources that belong to the application flow customers. In this case, nested flows (which are placed into a separate bundle later on) are excluded—as is the referred helpers module.
• Three for resources that belong to nested flows of the customers flow.

In addition to these three bundles, a fourth base bundle includes application resources, such as shell pages, libraries, and styles. This bundle explicitly adds the referred helpers module.

{
    "optimize": {
        "require-js": {
            "vb-bundles-config": {
             "dashboard": {
                "modules": {
                    "find": [
                        "flows/dashboard"
                    ]
                },
                 "exclude": {
                    "ids": [
                        "helpers"
                    ]
                }                
            },
             "customers": {
                 "modules": {
                    "find": [
                        "flows/customers",
                        "!flows/customers/flows"
                    ]
                },
                 "exclude": {
                    "ids": [
                        "helpers"
                    ]
                }
            },
             "customers-nested": {
                 "modules": {
                    "find": [
                        "flows/customers/flows"
                    ]
                }
            },
             "base": {
                 "modules": {
                    "find": [
                        "app-flow.js",
                        "^pages/",
                        "resources/strings",
                        "resources/css"
                    ],
                    "ids": [
                        "helpers"
                        ]
                    }
                }
            }
        }
    }
}

Exclude resources using emptyPaths

Sometimes, when your app includes a custom web component that refers to a third-party library (for example, resources/components/mycomponent that references ckeditor), you might want to include the component in your bundle but not the third-party library. To do this, you can use "!^resources/components/mycomponent/ckeditor" in build.json. But the library will still be included if code in your bundle references it. It may be code in the custom web component itself, or something in a file that refers to this library, for example, code in the app-flow.js file included in the bundle that refers to 'resources/components/mycomponent/ckeditor'. In such cases, you can add the emptyPaths element to build.json to ignore the dependency and also not recursively traverse its sub-dependencies:

{
    "optimize": {
        "require-js": {
            "emptyPaths": [
                "ckeditor"
            ],
            "vb-bundles-config": {
              "dashboard": {
                "modules": {
                    "find": [
                        "flows/dashboard"
                    ]
                },
                 "exclude": {
                    "ids": [
                        "helpers"
                    ]
                }                
            },
             "base": {
                 "modules": {
                    "find": [
                        "app-flow.js",
  ...

Here's an example emptyPaths definition that ignores multiple libraries:

 {
   "optimize": {
        "require-js": {
            "emptyPaths": [
                "ckeditor",
                "ckeditor-jquery"
            ],
  ...

How to Migrate Gruntfile.js Configuration Into build.json

If you use Grunt tasks to optimize your application, it's important to migrate configuration you've already defined in the Gruntfile.js file into build.json. Without this definition in build.json, resource optimization that occurs by default when your application is stage and publish won't include your customizations.

1. Select the web application in the Navigator, then click Settings to open the app-level Settings editor.
2. Click Open Build Configuration under Optimization to open your application's build.json file. If you don't see this option, click Create Build Configuration to create the build.json file (under /webApps/app_name/settings) and open it from within the Settings editor.
3. Add this snippet to build.json:

   {
       "optimize": {
           "require-js": {
               "emptyPaths": [
               ],
               "vb-bundles-config": {
               }
           }
       }
   }

4. Open your application's Gruntfile.js file (located at the root of your visual application in Source view).
5. Move the following configuration from Gruntfile.js to build.json:
   • Move the content of vb-require-bundle.options.bundles from Gruntfile.js into optimize.require-js.vb-bundles-config in build.json.
   • Move the content of vb-require-bundle.options.emptyPaths, if defined, from Gruntfile.js into optimize.require-js.emptyPaths in build.json.
   Remember to fix the syntax for JSON schema. For example, here's a side-by-side comparison of the configuration in Gruntfile.js and build.json:

   Gruntfile.js	build.json
   'use strict'; module.exports = (grunt) => { require('load-grunt-tasks')(grunt); grunt.initConfig({ "vb-require-bundle": { options: { emptyPaths: [ 'ckeditor', ], "bundles": { "vb-app-bundle": { "modules": { "find": [ "^flows/", "^pages/", "^resources/", "!^services/", ], }, }, }, }, }, }); };	{ "optimize": { "require-js": { "emptyPaths": [ "ckeditor" ], "vb-bundles-config": { "vb-app-bundle": { "modules": { "find": [ "^flows/", "^pages/", "^resources/", "!^services" ] } } } } } }

6. Remove vb-require-bundle from Gruntfile.json, so your file looks something like this:

   module.exports = (grunt) => {
       require('load-grunt-tasks')(grunt);
   };