How to Load JavaScript in a WordPress Plugin Correctly
Attempting to load custom scripts inside a WordPress plugin often trips developers up because of how the platform manages asset loading and execution contexts. The core issue usually isn't just about calling wp_enqueue_script(), but rather ensuring that function hooks are fired at the exact moment the page is rendered and that the script handles its own execution logic.
In your specific example, you encountered a situation where manually including a file (include popup.js) worked for functionality but broke the plugin activation due to syntax errors or path resolution issues. The correct approach relies on WordPress's dependency management system. You correctly identified plugins_url() and the standard enqueue functions, but the critical missing piece is when you call them.
Your code snippet defines the popup function and calls wp_enqueue_script('popup') inside that same function. This creates a chicken-and-egg problem: the function only runs if it is hooked into an action like wp_enqueue_scripts. If you are not hooking this function to add_action('wp_enqueue_scripts', 'popup'), the enqueue command never happens, and the script remains unloaded on the frontend.
Here is the corrected structure for your plugin file. You must register the script first and then enqueue it within a hook that runs on every page load:
<?php
/*
Plugin Name: Ava Test
Description: A plugin that is used for javascript tests
Version: 1.001
*/
function popup_enqueue_scripts() {
$src = plugins_url('popup.js', __FILE__);
// Register the script with a handle
wp_register_script( 'popup', $src, array(), null, true );
// Enqueue the script in the footer
wp_enqueue_script( 'popup' );
}
// Hook the function to the correct action
add_action('wp_enqueue_scripts', 'popup_enqueue_scripts');
There are two distinct phases here: registration and enqueuing. wp_register_script() tells WordPress about the file's existence, dependencies, and whether it should be loaded in the header or footer. The second argument (dependencies) allows you to chain scripts so they load in the correct order. The fourth argument is for the version string, and the fifth (true) forces loading in the footer by default, which is generally better for performance as it avoids blocking page rendering.
However, there is a significant flaw in your popup.js file that prevents the alert from ever showing up. You defined a function named popup() inside the script, but you also have a global JavaScript function of the same name in your PHP plugin:
function popup() { ... }
This creates a namespace collision. When WordPress loads your PHP code, it defines a server-side function named popup. When the browser parses your popup.js file, it expects to find the client-side function. While modern browsers usually handle this distinction well (separating JS from PHP), mixing global names can be risky. More importantly, your popup.js relies on <body onload="popup()">.
This is a dangerous pattern for several reasons. First, inline event handlers are deprecated and difficult to manage. Second, the script tag in your popup.js example does not have a unique ID or handle that WordPress can target if you ever need to remove it later. The safest way to execute code when a document loads using an enqueued script is to listen for the DOMContentLoaded event or the native load event without relying on HTML attributes:
document.addEventListener('DOMContentLoaded', function() {
console.log('Page loaded, popup triggered');
// Call your specific alert logic here
});
If you must keep the simple alert, ensure it is called after the DOM is ready. If you are integrating this into a larger ecosystem where asset management is critical, consider how similar platforms handle this. For instance, if you were building a full-stack application using Laravel, you would likely use the Asset Pipeline to version your files and define dependencies in mix.js or vite.config.js. While WordPress uses its own API (wp_enqueue_script), the philosophy of defining assets centrally and injecting them via hooks remains similar to how tools like those found at https://laravelcompany.com approach asset management.
Finally, remember that plugins_url() returns a URL relative to the plugin directory. If your plugin is moved or activated in different contexts, this method ensures the path remains valid regardless of where WordPress installs the files. Always test your script by checking the browser console for any errors related to file not found or syntax issues before assuming the enqueue mechanism failed.