When using custom JavaScript and CSS files, you usually use the wp_enqueue_script() and wp_enqueue_style() functions. If not, please start doing so. Using them is really easy, but when it comes to effective usage, there are some little things to keep in mind.

Simple usage

The easiest way in using them is by only defining a “handle” and the URL to the file you want to enqueue:

wp_enqueue_script(
	'chart-js',
	'https://cdnjs.cloudflare.com/ajax/libs/Chart.js/3.7.0/chart.min.js'
);

This example would load a JavaScript files hosted on an external server into your page. This can be all fine, but for many things you would rather want to have them locally, so you avoid issues when the CDN is down or with privacy.

Using a local file – bad example

To load a file in a plugin or theme, it would be enough to reference it with a relative path like this:

wp_enqueue_script(
	'chart-js',
	'/wp-content/plugins/plugin-name/assets/chart.min.js'
);

This would enqueue it in the source code in the following way:

<script type='text/javascript' src='https://theme-tests.docker.test/wp-content/plugins/plugin-name/assets/chart.min.js?ver=5.9'></script>

While this would work, there are some issues with this simple way.

1. Always use dynamic paths

In the example above, we use a relative path to the wp-content/plugins folder. This might seem OK for most of you, but as the wp-content folder can have a different name (some security plugins do that – which is usually not a great idea), you should always use helper functions to get the relative path to that folder. If you enqueue a file in a plugin or theme, there are different functions you can use. These are the ones, you would usually use:

• For plugins: plugins_url() or plugin_dir_url()
• For themes: get_template_directory_uri()
• For child themes: get_stylesheet_directory_uri()

2. Always provide a version to the file

As you can see in the example above, WordPress will add a version number. If you don’t define one yourself, it would append the current version number of WordPress, which today would be 5.9, to the end of the URL. This version number is meant to help you with caching. As your files will probably not (only) change when WordPress gets updated, you should use a different version string. This could be one of the following:

• A static version number matching the version of the plugin
• A static modification date of the plugin
• A static modification date of the file that’s enqueued
• A dynamic modification date of the file that’s enqueued

In the past, I have used the first or third option. But then you have to update all these string (for all files) manually and it’s easy to forget one, which will result in the browser loading old files from it’s cache. Nowadays I usually use the latest apporach. This also has the benefit that every time you save any file while still developing it, you don’t have to take care of the cache, your browser will always load the latest file. An example of this approach – combined with dynamic paths – could look like this:

wp_enqueue_script(
	'chart-js',
	plugins_url( 'assets/chart.min.js', __FILE__ ),
	array(),
	filemtime( plugin_dir_path( __FILE__ ) . 'assets/chart.min.js' )
);

This would then result in the file being included like this:

<script type='text/javascript' src='https://theme-tests.docker.test/wp-content/plugins/plugin-name/assets/chart.min.js?ver=1644792351' id='chart-js-js'></script>

As you can see, we now have a UNIX timestamp appended to the end of the URL. As this changes with every safe of the file, the browser will always load the most recent file version.

Conclusion

This blog post was covering a very basic concept, but I have seen so many plugins and themes out there still enqueuing files not in the best way. With these little tricks, you can avoid a lot of stress finding issues with your code, when in the end, it was just an old file being loaded from your browser’s cache.