Using the Yireo ScriptMerge plugin

The Yireo ScriptMerge plugin allows you to optimize your Joomla! HTML-output by merging CSS-stylesheets and JavaScript-files together as one, and therefor limiting the number of HTTP-requests needed to load the page. The plugin uses an extra component for added functionality. This tutorial shows you how to implement ScriptMerge.


  1. Download both the ScriptMerge plugin as the ScriptMerge component from the download-section on this site.
  2. Install both ZIP-files from within the Joomla! Administrator as regular extensions.
  3. Next go to the Plugin Manager to enable the system-plugin. It is listed as System - ScriptMerge.
  4. Make sure the ScriptMerge plugin is loaded as one of the last plugins - give it a high ordering number (for instance 99).
  5. Make sure the Joomla! cache directory is writable for the webserver.

ScriptMerge will only function correctly when your page is W3C-compliant. First fix your SEO, then fix performance. The component is not visible within the Joomla! backend - system options are available only in the plugin parameters.

General usage

The plugin parameters allow you to enable or disable compression of either CSS or JavaScript. Compressing CSS is generally a good idea and again saves some bandwidth. Compressing JavaScript could be troublesome if third party scrips are written with non-standard code. You need to experiment with the settings to find out which settings are right.

Tuning ScriptMerge might also require you to know which CSS and which JavaScript is loaded for which purpose. If you are able to study the HTML-source, you know the possibillities of tweaking ScriptMerge to the max. If you are not familiar with HTML-sources, you should probably hire a developer to optimize performance for you.

ScriptMerge makes use of the general Joomla! cache. If you want to clean the ScriptMerge cache you can navigate to Tools > Clean Cache in the Joomla! backend.

Plugin parameters

Through the Joomla! Plugin Manager, you can manage the settings of the ScriptMerge plugin. The following parameters are available:

  • Merge Type: This can be set either to Checksum or Filelist. The default value is set to Checksum and this works fine in most environments. If you wish to implement full page caching, you will need to choose the option Filelist - but note that this issue could cause issues. See the known issues below, when you run into problems.
  • Merge CSS: This option is the main functionality of ScriptMerge, and should probably be set to Yes.
  • Merge JS: This option is the main functionality of ScriptMerge, and should probably be set to Yes.
  • Skip Compressed: This option tries to detect whether a certain file is already compressed or not. If it is already compressed, it will not be compressed again. But it will also not be included in the merged file, but served as a separate file instead.
  • Remove Mootools: Enable this to get rid of MooTools. Note that you should not be running Joomla extensions that require MooTools.
  • Follow CSS imports: When CSS-files are merged, ScriptMerge can follow @import rules to include other stylesheets as well. This option allows you to enable or disable this feature.
  • Hashing method: If you use the Checksum as Merge Type, ScriptMerge will determine a checksum to see whether the cache is still unique. If you set this to Simple, the cache will not be refreshed when CSS files change - you will need to manually clear your cache. If you set this to Advanced, the cache will expire as soon as the CSS files change. However, this causes a little extra overhead (milliseconds).
  • Enable in backend: The speed of the Joomla! Administrator can be improved as well, by enabling this option. However, some third party extensions might add CSS and JS that causes problems, effectively locking you out of the backend. Be careful when using this option, and make sure you know how to modify the ScriptMerge plugin parameters by using SQL-commands (for instance, through phpMyAdmin).
  • Enable in Frontend: This defaults to Yes, because you most likely want to improve your site-speed for visitors.
  • Compress CSS: The better compressed CSS is, the faster the page will load. However, third party extensions or the template might add CSS-code that is causing problems. Make sure the CSS is W3C compliant when enabling this option.
  • Compress JS: Enabling this option gives as well added performance, but should be handled with care. In some cases, JavaScript files from various third party extensions cause this option to break all JavaScript on your pages. If you enable this option, make sure to check all your pages for JavaScript errors.
  • Exclude CSS: This is a comma-seperated list of CSS-files to exclude from the merge-process. Names can be partially matched as well. For instance, you could exclude all files from your template by entering the template-folder.
  • Exclude JS: This is a comma-seperated list of JS-files to exclude from the merge-process. Names can be partially matched as well. For instance, you could use the keyword mootools or jquery to exclude files of that type.
  • Exclude Menu-Items: Instead of defining a manual list of files, you can also select the Menu-Items which should not be handled by ScriptMerge.
  • Exclude Components: This option allows you to disable ScriptMerge for a specific component.
  • Use Comments: Enable if you want to keep comments in the CSS and JavaScript files (including copyright notices). This only works with the basic compression techniques.
  • JavaScript Domain: If you want to serve the merged JavaScript URL through another domain than the default Joomla! domain, configure this here. This concept is known as domain sharding. The value can be either a domain-name like or an URL like If the value starts with http, but the current Joomla! URL is served through HTTPS, this option is automatically disabled. If the value starts with https, but the current Joomla! URL is non-SSL, domain sharding is still applied.
  • CSS Domain: The same as JavaScript Domain except for the merged CSS URL.
  • Expiration: This value determines the cache-time of merged files when the merge-type is set to Checksum.
  • Version: This value is appended to the merged URLs, allowing you to tell browsers to fetch a new version of the file if browser caching is enabled.
  • Data URIs: When CSS or HTML is parsed, and ScriptMerge encounters images, the path of these images is normally renamed to point to the new path of the merged output. Instead of changing the path, the entire image can also be read into a Base64 stream and outputted within the HTML or CSS itself. This makes the CSS or HTML larger, but also requires one less HTTP Request. Very cool.
  • Data URI Filesize: The maximum size at which ScriptMerge converts images into Base64 streams. You can set this a few kilobytes, but do not set this higher than 20Kb or so, otherwise your CSS or HTML will grow out of proportion.
  • Use WebP: If WebP is supported in your hosting environment, ScriptMerge can also try to convert the normal JPGs and PNGs into WebP images, resulting in up to 50% size reduction.
  • cwebp Binary: Path to the cwebp binary. Required for using WebP.
  • Use JSMIN: When compressing JavaScript, ScriptMerge can optionally call upon JSMIN for optimal compression.
  • jsmin Binary: Path to the jsmin binary. Required for using JSMIN.
  • Defer Merged File: Apply async and defer techniques to defer the loading of JavaScript. Sometimes this works, sometimes it does not.
  • Merged JS Option: Option to place the new merged JavaScript tag in the header, the bottom of the body or the bottom of the header.
  • Merged CSS Option: Option to place the new merged CSS tag in the header, the bottom of the body or the bottom of the header.
  • Force GZIP: Force GZIP output on merged JavaScript and CSS files. Make sure this does not conflict with deflate-options in your webserver.
  • Include CSS: This option allows you to implement critical CSS on your pages. You can use a tool like to determine and extract your critical CSS. Next you can remove those lines from your Joomla template, and insert those lines here within ScriptMerge.

When testing out these settings, make sure to check the browsers Error Console for any errors. If errors occur, you probably configured something that does not work on your site. Make sure to test things site-wide as well.

The ScriptMerge component is not accessible from the Joomla! backend and contains no parameters.

Notes on minification and copyright

When minifying JavaScript and CSS, there are various tricks to perform: Whitespaces are unneeded and removed. But also, comments are removed. Sometimes however, these comments contain copyright declarations. And it could be illegal to remove that copyright notice. We don't offer this tool with a lot of options, but you should note that some of these options break copyright rules. It's up to you to decide whether this is actually something to conform to or not. On a personal note, any CSS or JS that is offered to you by third party developers, and that contains copyrights that can't be legally removed, is crap.

Notes on JavaScript compression

The JsMinPlus library included with ScriptMerge allows for best compression of JavaScript-files. The alternative is to compress JavaScript with simple PHP-rules, or not compress it at all. The downside of JsMinPlus is that is quite slow. Do not use it with the Merge Type set to Filelist, because this will run JsMinPlus on every page-request. Note that JsMinPlus is not compatible with MooTools - so ScriptMerge automatically applies the simple compression when finding a file with the word mootools in it.

The Closure Compiler API works over HTTP and requires your firewall to allow outgoing connections. Do not use this with the Merge Type set to Filelist. Also try to set the Skip compressed option to Yes, because the service gives bad results when both MooTools as jQuery compressed versions are included.

Tip: Make sure your JavaScript is working first

Before testing our plugin, make sure JavaScript is working on your site (so without this plugin being enabled). Check every page with your browsers Error Console open. If any JavaScript errors occur there, fix those errors first. Enabling ScriptMerge on your site, while JavaScript errors are still there, will cause huge issues.

Tip: Make sure your CSS is working first

Before testing our plugin, make sure CSS is working as well. Use the W3C CSS validator to make sure there are no CSS lines that will break the rest.

Tip: Exclude certain JavaScript

The following scripts are known to cause issues when merging JavaScript files, and are best excldued through the Exclude JS option:

  • jce (use this as keyword to match all JCE scripts)
  • jquery.cycle.all.js

Known issue: Unable to access site

You might have installed ScriptMerge and started playing with it. Sure this is possible, but with a valid backup, right? And on a testing environment, right? If no, something really is wrong with the procedure to safeguard your site. Anyway, if you have played with some settings: For instance, enabling ScriptMerge for the backend sounds really cool. But there are tons of experimental options that might or might not work, and if they do not work, they might cause your backend to stop working. Nothing unexpected.

Solution: Restore your backup. If you don't have a backup, that's your real problem. As a last resort, try removing the ScriptMerge plugin-files from the Joomla! folder system/plugins. After you have gained access to your Joomla! backend, remove the ScriptMerge extension. Optionally reinstall it. Create a backup first.