Minification is the process of minimizing code and markup in your application. It’s one of the main methods to reduce load times and improve application performance.
Here are options and considerations for minimizing JavaScript output in your Royale application.
By default, Royale outputs a single minified JavaScript file for deployment of the application. The minified file contains all the code needed for running your application. The code contains the necessary pieces of framework code as well as your application code. The minification uses Google's Closure Compiler. The goal for the default release output is that it should always work without consideration for how the code was written.
To ensure that all features work correctly, the output by default keeps all public class and member names. The process renames and minifies the inner workings when possible, but keeps the original name in the code. This results in code which works and is reasonably compact.
There are two reasons you might want to consider using additional compiler options.
There are numerous compiler options which you can use for minification, and turn on or off for specific cases. For full details, read the whole page. Most cases of advanced minification use the following options:
-export-public-symbols=false -prevent-rename-protected-symbols=false -prevent-rename-public-symbols=false -prevent-rename-internal-symbols=false
This combination of options will produce the most compact code.
Some additional options which will reduce code size (and improve performance) are:
-js-output-optimization=skipAsCoercions -js-vector-emulation-class=Array -js-vector-index-checks=false -js-complex-implicit-coercions=false
An additional one which will have a small effect on code size, but will not effect performance and might introduce bugs if turned off is:
-js-default-initializers=false
Make sure you read the compiler options page to understand what each of these options does.
There is one option which will make some of the output code larger, but might be necessary in many situations:
-js-dynamic-access-unknown-members=true
We discuss this option in length below.
Before using advanced minification options, you need to consider your application needs:
classVar.fooBaz())If you answer no to all of the above questions, you can use the smallest size options.
If you answered yes to #1 and #2 above, you need to ensure that your dynamic object access is not renamed. Otherwise you will end up with myJSON.a instead of myJSON.thumbnail and you will get unexpected undefined values. There are two ways to do this.
myJSON["thumbnail"] instead of myJSON.thumbnail and {"name":"foo","age":20} instead of {name:"foo",age:20})The compiler option to do this automatically is -js-dynamic-access-unknown-members=true. However, bear in mind that the compiler will quote every instance of dynamic access. Using -js-dynamic-access-unknown-members=true together with the other minification options can break using your app if you don‘t declare your types correctly everywhere in your app, including arrays. If you try myArray[i].doSomething() with the combination of compiler options above, your app will break. That’s because the type of myArray[i] is unknown. The compiler does not know if it's a Foo or an Object with dynamic access which cannot be renamed.
If you need to keep dynamic names, decide if it‘s better or less work to manually quote the cases where you need to keep the names of dynamic access, or if you want to ensure you’re meticulous about declaring types in your application.
Going the path of declaring types has the advantage of giving your app more type safety and preventing bugs, but can be more work.
Vectors instead of ArraysVectors give the compiler the information it need about types so it knows not to quote access. It also gives you better type safety, so it's a good idea in general. Read the Vector page for more details.
:Object and :*If you are using a dynamic type, make sure that there's a compelling reason to do so.
Interfaces are a powerful tool for declaring your types. You can use interfaces for even unrelated types which have similar access. Interfaces can be a good choice in many cases where you might be tempted to use Object.
You can get lots of clues to places where you should have done a better jobs of declaring types by searching your JS files for [" or "]. That will find bracketed access. The pattern of "]( is especially suspect because that indicates calling a method on a dynamic object.
for infor in is a prime candidate for introducing problematic dynamic access. You can use for in for dynamic objects or statically-typed objects, but mixing the two will not work. myClassInstance[x] = myObject[x] will not work.
Sometimes you are going to have to run your minified code and find what broke. Pausing on caught exceptions is often a good way to find where your code breaks. Search the surrounding code for un-minified variables or patterns that you might recognize from your source code. Going back to your source code, you can usually figure out what value was not assigned correctly. That should give you clues to where access is broken.
Constantly checking that your app works both in debug and release mode is important for finding where you might break your app.
In general, only dependencies you need are included in your app when using Royale. Usually this means additional classes and the associated code. In certain cases, using features will affect the size of all your classes because more information will be needed at runtime.
getDefinitionByName, getQualifiedClassName, etc.) If you use reflection, information about your classes and accessors is needed at runtime. This adds significantly to the size of your runtime output. If you just need to get the class from an instance, you do not need reflection (unlike in Flash). There is org.apache.royale.utils.object.classFromInstance(), which helps with this without a reflection dependency.