Enqueues in WordPress

How to properly add scripts and styles, internal or external

WordPress provides built-in functions like wp_enqueue_script() and wp_enqueue_style() to safely add JavaScript and CSS to your site. These functions should be used instead of manually inserting <script> or <link> tags, as they handle dependencies, avoid conflicts, and improve caching behavior.

Scripts and styles are typically enqueued within the wp_enqueue_scripts hook for the frontend, and admin_enqueue_scripts for the backend.

How we do it at Terra

At Terra, we’ve set up a flexible system that handles script and style enqueuing for both development and production environments. This approach is especially helpful when working with modern build tools like Vite.

In development, we enable Vite’s Hot Module Replacement (HMR) by injecting the necessary scripts directly into the <head> of the page. This allows for live reloading and fast feedback during local development.
In production, we enqueue the final minified and hashed files from the /dist folder, making sure they are treated as ES modules (with type="module") and benefit from cache busting via unique hash filenames.

We also enqueue a separate stylesheet specifically for the WordPress admin area when needed.

Where to find this in Terra projects

You’ll find our enqueue logic here: functions/project/enqueues.php

This file centralizes the logic for registering and loading assets based on the current environment and is automatically hooked into WordPress through our theme structure.

<?php

/**
 * Enqueue scripts and styles based on the environment
 *
 * This code snippet is responsible for enqueuing the project's JavaScript and CSS files,
 * with different behaviors depending on whether the environment is in development or production mode.
 *
 * 1. If `IS_VITE_DEVELOPMENT` is set to `true` in local-variable.php, the function assumes the environment is in development mode.
 *    - It injects a script tag into the `<head>` of the document for Vite's Hot Module Replacement (HMR) feature,
 *      which enables live reloading during development. The script points to the local Vite development server.
 *
 * 2. If `IS_VITE_DEVELOPMENT` is `false` in local-variable.php, indicating a production environment:
 *    - It enqueues the minified and hashed JavaScript file from the `dist` directory. The `hash` in the filename
 *      is replaced by the actual hash generated during the build process, ensuring cache busting.
 *    - A filter is applied to modify the script tag, setting its `type` attribute to `module` for ES module compatibility.
 *    - The corresponding CSS file is also enqueued, with a similar hash in its filename for cache busting.
 *
 * @hook wp_enqueue_scripts  This hook runs when scripts and styles are enqueued in WordPress.
 */

add_action( 'wp_enqueue_scripts', function() {

    if (defined('IS_VITE_DEVELOPMENT') && IS_VITE_DEVELOPMENT === true) {
        function vite_head_module_hook() {
            echo '<script type="module" crossorigin src="http://localhost:9090/src/js/Project.js"></script>';
            echo '<script type="module" crossorigin src="http://localhost:9090/src/scss/style.scss"></script>';
        }
        add_action('wp_head', 'vite_head_module_hook');
    } else {
        wp_enqueue_script('project-build', get_template_directory_uri() . '/dist/Project.'.hash.'.js', [], null, true);
        add_filter('script_loader_tag', function ($tag, $handle, $src) {
            if ($handle === 'project-build') {
                $tag = '<script type="module" src="' . esc_url($src) . '"></script>';
            }
            return $tag;
        }, 10, 3);
        wp_enqueue_style('project-build',  get_template_directory_uri() . '/dist/ProjectStyles.' . hash . '.css');
    }
});

// Admin Backend Only (Exclusive CSS for Admin)
add_action( 'admin_enqueue_scripts', function() {
    wp_enqueue_style('admin-backend-style', get_template_directory_uri() . '/dist/Appbackend.'.hash.'.css');
});

?>