Skip to content

Backgrounds

How-to Guides

Technical References

VIP Platform /

File concatenation and minification

By default, VIP concatenates JavaScript and CSS files in an effort to reduce the number of requests a single page requires. CSS is not only concatenated but also minified which reduces the file size by removing unnecessary white space. If you minify files in your theme, as part of a build process, you should also include the source files for code review.

The responses that are generated by VIP sites are served from our global network of edge locations. This means a majority of a site’s traffic, including concatenated scripts and styles, can be served directly from the edge location closest to your visitors, without ever hitting a line of PHP. This results in the low-latency and high-performance impact expected from a CDN.

Technical details of concatenation

You will see these requests in the Network tab of a browser, the path starts with /_static/??-

The nginx-http-concat plugin handles this logic, and normally you will not need to adjust its behavior, but it is important to have a basic understanding of how it works. In some cases, you may wish to prevent specific JS or CSS files from being included in the concatenation bundles. This may be necessary if you’re seeing JS errors due to load precedence, although by defining enqueue dependencies, this should rarely happen.

Note

Some 3rd party performance scans may not recognize our CDN since the files are being served from the same domain as your site.

Cache duration

Enqueued JavaScript and CSS are concatenated on VIP Go and cached for 15 days.

For additional information on caching you may be interested in learning how VIP handles page caching.

Versioning to bust the cache

The cache can be busted for concatenated JS and CSS by incrementally updating the $ver value when changes are made to the enqueued, or registered, resources using functions like wp_enqueue_script(), wp_enqueue_style(), wp_register_script(), and wp_register_style(). This effectively changes the static URL.

// When changes are made to js/plugin.js the $ver variable should be incrementally updated.
$ver = '1.1';
wp_enqueue_script( 'plugin_script', plugins_url( 'js/plugin.js', __FILE__ ), array(), $ver );

Note

Because of the container-based infrastructure, VIP does not recommend using the function filemtime() to populate a value for $ver; each time a container is created it would result in a different value.

Disabling concatenation

If you have a need to disable concatenation completely on a VIP site, add the following constant to your vip-config.php file.

define( 'CONCATENATE_SCRIPTS', false );

However, if you’re finding a specific CSS or JS file to be problematic, it may be excluded from concatenation with a filter (css version):

add_filter( 'js_do_concat', 'my_vip_js_concat_filter', 10, 2 );

// do not include my-script-handle in concatenated bundles
function my_vip_js_concat_filter( $do_concat, $handle ) {
    if ( 'my-script-handle' === $handle ) {
		return false;
	}
	return $do_concat;
 }

add_filter( 'css_do_concat', 'my_vip_css_concat_filter', 10, 2 );

// do not include my-custom-css-handle in concatenated CSS bundles
function my_vip_css_concat_filter( $do_concat, $handle ) {
    if ( 'my-custom-css-handle' === $handle ) {
		return false;
	}
	return $do_concat;
}

You may include additional logic in the filter, such as differentiating between is_admin() or not.

To disable all JS and/or CSS concatenation:

add_filter( 'js_do_concat', '__return_false' );
add_filter( 'css_do_concat', '__return_false' );

Debugging issues

If you are trying to determine if a JS error is related to concatenation, you can disable concatenation selectively with a query parameter: concat_js=false and/or concat_css=false will disable for just the current request. You should see individual files requested instead of the static bundle. This may help you identify the cause of an issue. Do not use these query parameters in code!

Built assets and concatenation and cache

If you’re building JS and CSS assets and creating your own bundles and enqueueing those, they will be inserted into the bundles above unless they are excluded. Built assets and concatenation can cause short-term brokenness in CSS and/or JS when combined with full page caching.

Because previous bundles are cached at the edge, newly deployed changes will usually reference a new bundle, while existing cached pages will reference an old one. If either needs to be reconstructed due to a cache miss, the enqueued files must still be available on the server – the URL contains the filenames (usually compressed). So when building your assets you may not wish to delete older versions of those built files for at least 30 minutes so they can be used as needed. If you see 404s for previously-good bundles, this is a likely cause – one of the component files is missing. If you’re simply overwriting these files, keep in mind an old URL may suddenly contain the new assets even though the page was generated before the deploy.

Last updated: April 18, 2021