Automated assets registration and enqueueing

The Chisel theme centralizes all asset logic in inc/WP/Assets.php and exposes convenient hooks to add/modify assets per context (frontend, admin, editor, login). It also handles versioning, dependencies, localization, async/defer, and a fast-refresh DX.

Overview

Core class: Chisel\WP\Assets
Entry points:
- register_assets() on init
- enqueue_frontend_assets() on wp_enqueue_scripts
- enqueue_frontend_assets_in_footer() on wp_footer
- enqueue_admin_assets() on admin_enqueue_scripts
- enqueue_editor_scripts() on enqueue_block_editor_assets
- enqueue_login_page_assets() on login_enqueue_scripts
Context buckets:
- Frontend: $frontend_styles, $frontend_scripts, $frontend_footer_styles
- Admin: $admin_styles, $admin_scripts
- Editor: $editor_styles, $editor_scripts
- Login: $login_styles, $login_scripts

File structure and naming

Scripts: build/scripts/{name}.js (+ optional {name}.asset.php)
Styles: build/styles/{name}.css (+ optional {name}.asset.php)
Versioning & deps: Read from .asset.php when present; fallback to theme version
Handles: Chisel\Helper\AssetsHelpers::get_final_handle('{name}')

Localization and globals

inc/WP/Assets.php localizes:
- Frontend app as chiselScripts:
  - chiselScripts.ajax.url and chiselScripts.ajax.nonce for REST/AJAX
- Admin admin as chiselAdminScripts
- Editor editor as chiselEditorScripts (e.g., icon labels)
Script translations are set when a script depends on wp-i18n.

DX: fast refresh (development)

Webpack outputs build/runtime.js used only in dev; registered as runtime
Styles also register a “style watcher” script (build/styles/{name}.js) in dev so CSS hot-reloads without full page refresh

Performance adjustments

Move scripts to footer: move_scripts_to_footer() removes head hooks and prints in footer
Defer/async:
- defer_script() defers all non-core-WP script handles
- async_script() stubbed for selective async (extend if needed)
Preload CSS:
- preload_styles() preloads specific handles and prefixes (wp-block-library, gform_, block...)
Inline styles support via wp_add_inline_style
Inline scripts support via wp_add_inline_script

Filters you can use

Registration time:
- chisel_frontend_styles
- chisel_frontend_footer_styles
- chisel_frontend_scripts
- chisel_login_styles, chisel_login_scripts
- chisel_admin_styles, chisel_admin_scripts
- chisel_editor_styles, chisel_editor_scripts
Right before enqueue:
- chisel_pre_enqueue_frontend_styles
- chisel_pre_enqueue_frontend_scripts
- chisel_pre_enqueue_frontend_footer_styles
- chisel_pre_enqueue_admin_styles, chisel_pre_enqueue_admin_scripts
- chisel_pre_enqueue_editor_styles, chisel_pre_enqueue_editor_scripts
- chisel_pre_enqueue_login_styles, chisel_pre_enqueue_login_scripts
Per-asset allow/deny:
- chisel_enqueue_frontend_style
- chisel_enqueue_frontend_script
- chisel_enqueue_frontend_footer_style
- chisel_enqueue_admin_style, chisel_enqueue_admin_script
- chisel_enqueue_editor_style, chisel_enqueue_editor_script
- chisel_enqueue_login_style, chisel_enqueue_login_script

Adding assets (examples)

Add a frontend script with localization and deps:

add_filter('chisel_frontend_scripts', function ($scripts) {
    $scripts['my-feature'] = [
        // defaults: src auto-resolves to build/scripts/my-feature.js
        'deps'     => ['wp-i18n', 'jquery'],
        'strategy' => [ 'in_footer' => true, 'strategy' => 'defer' ],
        'localize' => [
            'name' => 'myFeature',
            'data' => [ 'foo' => 'bar' ],
        ],
        // 'condition' => fn() => !is_page('contact'), // optional: boolean or callable
    ];
    return $scripts;
});

add_filter('chisel_frontend_scripts', function ($scripts) {
    $scripts['my-feature'] = [
        // defaults: src auto-resolves to build/scripts/my-feature.js
        'deps'     => ['wp-i18n', 'jquery'],
        'strategy' => [ 'in_footer' => true, 'strategy' => 'defer' ],
        'localize' => [
            'name' => 'myFeature',
            'data' => [ 'foo' => 'bar' ],
        ],
        // 'condition' => fn() => !is_page('contact'), // optional: boolean or callable
    ];
    return $scripts;
});

PHP

Add a frontend style with inline CSS:

add_filter('chisel_frontend_styles', function ($styles) {
    $styles['my-style'] = [
        // defaults: src auto-resolves to build/styles/my-style.css
        'inline' => [
            'data' => ':root{--my-color: #ff6600;}',
        ],
    ];
    return $styles;
});

add_filter('chisel_frontend_styles', function ($styles) {
    $styles['my-style'] = [
        // defaults: src auto-resolves to build/styles/my-style.css
        'inline' => [
            'data' => ':root{--my-color: #ff6600;}',
        ],
    ];
    return $styles;
});

PHP

Add an editor stylesheet:

add_filter('chisel_editor_styles', function ($styles) {
    $styles['editor-custom'] = [];
    return $styles;
});

add_filter('chisel_editor_styles', function ($styles) {
    $styles['editor-custom'] = [];
    return $styles;
});

PHP

Conditionally include assets:

add_filter('chisel_frontend_scripts', function ($scripts) {
    $scripts['map'] = [
        'deps'      => [],
        'condition' => function () { return is_page_template('templates/page-map.php'); },
    ];
    return $scripts;
});

add_filter('chisel_frontend_scripts', function ($scripts) {
    $scripts['map'] = [
        'deps'      => [],
        'condition' => function () { return is_page_template('templates/page-map.php'); },
    ];
    return $scripts;
});

PHP

How the pipeline works (lifecycle)

On after_setup_theme, set_properties() seeds default asset entries and localization payloads
On init:
- register_assets() pulls your arrays through filters and calls:
  - register_style(handle, file, args)
  - register_script(handle, file, args)
On enqueue hooks (per context), filtered arrays are re-fetched, then:
- enqueue_style() and enqueue_script() are called
- Inline CSS/JS and localization are applied
- Script translations are attached if using wp-i18n
In dev, style watcher JS is enqueued for hot CSS updates

Paths and versioning details

Script URL: get_template_directory_uri() . '/build/scripts/{name}.js'
Style URL: get_template_directory_uri() . '/build/styles/{name}.css'
Asset metadata: build/(scripts|styles)/{name}.asset.php returning:
- ['dependencies' => [...], 'version' => '...']
If no asset file exists, version falls back to ThemeHelpers::get_theme_version()

Key methods to know

register_style() and register_script() support:
- src, deps, ver, strategy (script), media (style), condition, inline, localize
- condition may be boolean or callable
enqueue_style(), enqueue_script() handle inline/localize and enqueue
set_script_translations() attaches translations for wp-i18n scripts

Relevant files

inc/WP/Assets.php — main orchestrator
build/scripts/ and build/styles/ — compiled output and .asset.php
inc/Helper/AssetsHelpers.php — handle normalization
inc/Helper/ThemeHelpers.php — environment flags, theme version
inc/Helper/AjaxHelpers.php — AJAX base URL for REST endpoints

Automated assets registration and enqueueing

Overview

File structure and naming

Localization and globals

DX: fast refresh (development)

Performance adjustments

Filters you can use

Adding assets (examples)

How the pipeline works (lifecycle)

Paths and versioning details

Key methods to know

Relevant files

Do you like Chisel?