A Guide to loading external JavaScript in Drupal

High Score Labs News   •   Aug 26, 2021

Surprising as it may sound, many still find it quite challenging to load external JavaScript in their Drupal sites. This article provides valuable insight to assist you load and execute exotic .js code within the native environment of your Drupal site. First, however, I assume that:

  • You will have JavaScript as a local dependency rather than externally hosted.
  • Package managers like Composer and NPM are used to import external dependencies.

Now, let’s cut to the chase.

JavaScript That’s a Dependency of a Theme

Depending on your front-end tooling and workflow, there are a few different approaches to try on this one. Nevertheless, they all boil down to adding the dependencies you need to your package manager. If you’re using NPM, you can simply run the following code in the same location as your existing package.json file:

npm install inline-svg

The process is similar if you’re using Yarn, or another similar tool.

Next, incorporate the dependency into your workflow. This will depend on the bundler or task runner you’re using or if you’re using either at all (which is quite unlikely). It’s best to import the dependency within your JavaScript so it can be part of your main bundle. If you’re not using a bundler, you’ll need to make your dependencies available for your theme to use. The vendor-copy utility is quite helpful in this regard. It allows you to copy client-side preferences to a folder of your choice. Afterwards, create libraries for the dependency using the standard approach found in Drupal documentations.

JavaScript That’s a Dependency of a Project

Since you’re managing PHP dependencies with Composer (our second assumption), it’s best to manage your JavaScript dependencies the same way. Asset Packagist is a great tool for this. Add the Composer Installers Extender PHP package to your project’s root composer.json;

composer require oomphinc/composer-installers-extender

Next, add Asset Packagist to the repositories section of your project’s root composer.json. Ensure NPM and Bower assets are registered as new “installer-types” and in “installer-paths” to make them available for installation into Drupal’s /libraries folder. Now, you can create libraries that can be used to load JavaScript dependencies in Drupal and require them using NPM and Bower in Composer’s command line.

If your dependency is missing in Asset Packagist but has a repository that contains a composer.json file, load the VCS package repository using Composer instead.

JavaScript That’s a Dependency of a Custom Module

If you’re publishing your custom module and utilizing it in several different projects, you can add your dependency to a composer.json file within the custom module rather than the root level composer.json file of each project.

If you’re using the custom module for a single project, however, you’ll need to manually add each custom module to the repositories section of the project’s root composer.json file.

Other Approaches

Here are other methods to tackle the task:

  • Add a CDN-contained externally-hosted version of the dependency as an external library in your module.
  • If an externally-hosted version of the library isn’t available, download the dependency and package it with your module or theme.

Over time, we expect Drupal to support easier methods for loading external JavaScript in native code. For now, however, make do with the approaches discussed herein and get to building amazing experiences for internet users.

Contact us today!