How To: Enable Script Bundling

In Serene template there are about 3MB+ of javascript files which are included by default in _LayoutHead.cshtml.

This might cause bandwidth and performance problems for some systems, especially when a Serenity based site is accessed from mobile devices.

There are several ways to handle these problems, like minification and gzipping to decrease script size, bundling to pack scripts into fewer files, thus reduce number of requests.

You might prefer to use tools like Webpack, Grunt, Gulp, UglifyJS etc, but in case you want a simpler and effective solution with much less manual steps, Serenity comes with a script bundling and minification / compression system out of the box.

Please note that this feature requires Serenity 2.0.13+

ScriptBundles.json

First, you need a ScriptBundles.json file under MyProject.Web/scripts/site folder. ScriptBundles.json configures which script bundle will contain which files when bundling is turned on.

This file is included by default in Serene template 2.0.13+ and looks like this:

Unless you want to add some custom scripts to bundles, you don’t need to modify this file.

  1. {
  2.     "Libs": [
  3.         "~/Scripts/pace.js",
  4.         "~/Scripts/rsvp.js",
  5.         "~/Scripts/jquery-{version}.js",
  6.         "~/Scripts/jquery-ui-{version}.js",
  7.         "~/Scripts/jquery-ui-i18n.js",
  8.         "~/Scripts/jquery.validate.js",
  9.         "~/Scripts/jquery.blockUI.js",
  10.         "~/Scripts/jquery.cookie.js",
  11.         "~/Scripts/jquery.json.js",
  12.         "~/Scripts/jquery.autoNumeric.js",
  13.         "~/Scripts/jquery.colorbox.js",
  14.         "~/Scripts/jquery.dialogextendQ.js",
  15.         "~/Scripts/jquery.event.drag.js",
  16.         "~/Scripts/jquery.scrollintoview.js",
  17.         "~/Scripts/jsrender.js",
  18.         "~/Scripts/select2.js",
  19.         "~/Scripts/toastr.js",
  20.         "~/Scripts/SlickGrid/slick.core.js",
  21.         "~/Scripts/SlickGrid/slick.grid.js",
  22.         "~/Scripts/SlickGrid/slick.groupitemmetadataprovider.js",
  23.         "~/Scripts/SlickGrid/Plugins/slick.autotooltips.js",
  24.         "~/Scripts/SlickGrid/Plugins/slick.headerbuttons.js",
  25.         "~/Scripts/SlickGrid/Plugins/slick.rowselectionmodel.js",
  26.         "~/Scripts/SlickGrid/Plugins/slick.rowmovemanager.js",
  27.         "~/Scripts/bootstrap.js",
  28.         "~/Scripts/Saltarelle/mscorlib.js",
  29.         "~/Scripts/Saltarelle/linq.js",
  30.         "~/Scripts/Serenity/Serenity.CoreLib.js",
  31.         "~/Scripts/Serenity/Serenity.Script.UI.js",
  32.         "~/Scripts/Serenity/Serenity.Externals.js",
  33.         "~/Scripts/Serenity/Serenity.Externals.Slick.js",
  34.         "~/Scripts/jquery.cropzoom.js",
  35.         "~/Scripts/jquery.fileupload.js",
  36.         "~/Scripts/jquery.iframe-transport.js",
  37.         "~/Scripts/jquery.slimscroll.js",
  38.         "~/Scripts/mousetrap.js",
  39.         "~/Scripts/fastclick/fastclick.js"
  40.     ],
  41.     "Site": [
  42.         "~/Scripts/adminlte/app.js",
  43.         "~/Scripts/Site/Serene.Script.js",
  44.         "~/Scripts/Site/Serene.Web.js"
  45.     ]
  46. }

Here we define two distinct bundles, Libs and Site, corresponding to Bundle.Libs.js and Bundle.Site.js dynamic script files.

Bundle.Site.js is configured to contain these three JS files (in the listed order):

  1. "~/Scripts/adminlte/app.js",
  2. "~/Scripts/Site/Serene.Script.js",
  3. "~/Scripts/Site/Serene.Web.js"

While Bundle.Libs.js contains all other javascript files.

Here we used 2 bundles by default, but it is possible to use one, three or more in case you need a different configuration. Just be careful about dependencies.

Here, the ordering inside a bundle (package) is very important. You must include scripts in the order they appear in your _LayoutHead.cshtml.

When you will add another custom script, make sure that it is placed after all its dependencies.

For example, if you include a jquery plugin before jquery is loaded itself, you’ll have errors.

Also make sure that you don’t include same file in two bundles.

Enabling Bundling

You should enable bundling (especially minification) only in production. Otherwise it might become very difficult to debug Javascript.

To enable bundling, just change Enabled property of ScriptBundling application setting in your web.config to true:

  1. <add key="ScriptBundling" value="
  2.    { Enabled: true, Minimize: false, UseMinJS: false }" />

When Enabled is false (default) system will do nothing, and you’ll work as usual with your script includes. And your page source looks like this:

  1. <script src="/Scripts/pace.js?v=..."></script>
  2. <script src="/Scripts/rsvp.js?v=..."></script>
  3. <script src="/Scripts/jquery-2.2.3.js?v=..."></script>
  4. <script src="/Scripts/jquery-ui-1.11.4.js?v=..."></script>
  5. <script src="/Scripts/jquery-ui-i18n.js?v=..."></script>
  6. ...
  7. ...
  8. ...
  9. <script src="/Scripts/adminlte/app.js?v=..."></script>
  10. <script src="/Scripts/Site/Serene.Script.js?v=..."></script>
  11. <script src="/Scripts/Site/Serene.Web.js?v=..."></script>
  12. ...

When Enabled is true, it will become like this one:

  1. <script src="/DynJS.axd/Bundle.Libs.js?v=..."></script>
  2. <script src="/DynJS.axd/Bundle.Site.js?v=..."></script>
  3. ...

These two bundles are generated in memory and contains all other script files configured in ScriptBundles.json file.

They are also compressed with GZIP and cached in memory (in gzipped form), so now our scripts will consume much less bandwidth and will cause fewer requests to server.

Now our script files will consume 600KB, instead of 3000KB before, a %80 reduction, not bad…

Enabling Minification

After enabling bundling, you may also enable minification of scripts with the same web.config setting. Set Minimize property to true:

  1. <add key="ScriptBundling" value="
  2.    { Enabled: true, Minimize: true, UseMinJS: false }" />

Please note that Minimize property only works when Enabled is true, thus when bundling is enabled.

UglifyJS library is used for minification. This will be applied before bundling / gzipping so our bundles will become about %40 smaller, but will be much harder to read, so enable this only in production.

Now our bundled and minified script files will consume 375KB, instead of 3000KB before, a %87 reduction, or 1/8 the initial size.

UseMinJS Setting

Minification might take some time, and first request to your site might take around 5-40 seconds more, depending on speed of your server.

Other requests will not be affected as minification is only performed once at application start.

Anyway, if you still need more performance at first request, you may ask Serenity to reuse already minified files in disk, if they are available.

Set UseMinJS to true:

  1. <add key="ScriptBundling" value="
  2.     { Enabled: true, Minimize: true, UseMinJS: true }" />

When this setting is ON, before minifying a file, let’s say jquery-ui-1.11.4.js, Serenity will first check to see if a jquery-ui-1.11.4.min.js already exists in disk. If so, instead of minifiying with UglifyJS, it will simply use that file. Otherwise, it will run UglifyJS.

Serene comes with minified versions of almost all libraries, including Serenity scripts, so this setting will speed up initial start time.

There is a little risk that you should be careful about. If you manually modify a library script, make sure you minify it manually and modify its .min.js file too, otherwise when bundling is enabled an old version of that script might run at production.

How Serenity Modifies Your _LayoutHead.cshtml Includes?

If you look at your _LayoutHead.cshtml you might spot lines like these:

  1. @Html.Script("~/Scripts/jquery.cropzoom.js")
  2. @Html.Script("~/Scripts/jquery.fileupload.js")
  3. @Html.Script("~/Scripts/jquery.iframe-transport.js")

When bundling is disabled, these statements generates such HTML code:

  1. <script src="/Scripts/jquery.cropzoom.js"></script>
  2. <script src="/Scripts/jquery.fileupload.js"></script>
  3. <script src="/Scripts/jquery.iframe-transport.js"></script>

Html.Script is an extension method of Serenity, so when bundling is enabled, instead of generating this HTML code, Serenity will first check to see if this script is included in a bundle.

For the first script that is included in a bundle, let’s say Bundle.Lib.js, Serenity will generate code below:

  1. <script src="/DynJS.axd/Bundle.Libs.js?v=..."></script>

But, for other Html.Script calls that is included in same bundle, Serenity will generate nothing. Thus, even though you call Html.Script 50 times, you’ll get only one <script> output in page code.

What Is v=p53uqJ… In My Script Tags?

This is a version number, or HASH of your script. Whether bundling is enabled or not, when you use Html.Script, it will add these hash to your script includes. This hash allows browser to cache script until it changes. When content of a script changes, its hash will change too, so browser won’t cache and use an older version.

This is the reason you’ll never have script caching problems with Serenity apps.