Asset Injector
Allows administrators to inject CSS and JavaScript into page output based on configurable rules without modifying themes.
asset_injector
Install
composer require 'drupal/asset_injector:8.x-2.21'
composer require 'drupal/asset_injector:8.x-2.20'
Overview
Asset Injector combines the functionality of CSS Injector and JS Injector into a single module, providing site administrators with a quick and easy way to add custom CSS and JavaScript snippets to their Drupal site without diving into full-fledged theme development.
All configurations are stored as Config Entities in the database, making them fully exportable via Features, Drush config export, or custom module installations using YAML files. This architecture is particularly useful for multi-site installations where each site may have minor differences that are easiest to manage through per-site configurations.
The module leverages Drupal's Condition Plugin API to provide flexible, context-aware asset injection. Assets can be conditionally displayed based on URL paths, content types, user roles, themes, languages, and any other registered condition plugin. The module also supports CSS/JS preprocessing and aggregation for optimal performance.
Features
- CSS injection with support for media types (all, print, screen) and CSS preprocessing/aggregation
- JavaScript injection with optional jQuery dependency, header/footer loading options, and JS preprocessing/aggregation
- Conditional asset display using Drupal's Condition Plugin system (paths, content types, themes, languages, user roles)
- Noscript fallback support for JavaScript injectors with per-theme region mapping
- ACE code editor integration with syntax highlighting for CSS and JavaScript
- Configuration entity-based storage enabling export/import via Drush, Features, or YAML files
- CKEditor integration for CSS assets to apply styles within the WYSIWYG editor
- Asset duplication feature for quickly creating variations of existing injectors
- Enable/Disable functionality without deleting assets
- AND/OR condition logic allowing flexible rule combinations
- Automatic cache invalidation when assets are created, updated, or deleted
- Support for Drupal's config override system for domain/language-specific asset variations
Use Cases
Quick CSS fixes for specific pages
Add targeted CSS fixes for specific pages without modifying theme files. For example, float a sidebar element on node edit pages by creating a CSS injector with path condition '/node/*/edit'.
Third-party tracking scripts
Inject third-party tracking scripts (analytics, marketing pixels) on specific pages or content types without modifying theme templates. Use conditions to limit scripts to production environment or specific sections.
A/B testing styles
Create multiple CSS injectors with different styling approaches, enable/disable them to quickly test visual changes without deployment. Use the duplicate feature to create variations.
Multi-site customization
In a multi-site setup, use Asset Injector to manage site-specific CSS/JS tweaks per site while sharing a common codebase and theme.
JavaScript enhancements without custom modules
Add small JavaScript enhancements (scroll behaviors, form validations, UI tweaks) without creating custom modules. Useful for site builders who need quick functionality additions.
Print stylesheets
Add print-specific CSS using the media type selector to optimize page printing for specific content types or sections.
Role-based styling
Apply different styling for authenticated users, administrators, or specific roles using the user role condition.
Language-specific adjustments
On multilingual sites, inject language-specific CSS or JavaScript to handle RTL layouts, font adjustments, or locale-specific behaviors.
Theme-specific overrides
Apply CSS/JS only when a specific theme is active, useful for making adjustments to contrib themes without creating a sub-theme.
Noscript fallback content
Provide alternative content for users with JavaScript disabled, such as static versions of dynamic elements or informational messages.
Tips
- Use the 'Save and Continue Editing' button when iterating on CSS/JS code to avoid navigating back to the edit form repeatedly.
- Take advantage of the duplicate feature to create variations of existing injectors with slight modifications.
- Use the 'Require all conditions' setting strategically - unchecking it allows for OR logic which can simplify complex targeting scenarios.
- For performance, keep 'Preprocess' enabled unless you specifically need the asset to load separately for debugging purposes.
- Load JavaScript in the footer (default) rather than header for better page load performance.
- Export injector configurations via Drush (drush config:export) to track changes in version control.
- Use path wildcards like /admin/* to target entire sections of the site.
- When debugging, temporarily disable other CSS/JS aggregation to isolate issues with specific injectors.
Technical Details
Admin Pages 7
/admin/config/development/asset-injector
Main landing page for the Asset Injector module providing links to CSS Injector and JS Injector administration pages.
/admin/config/development/asset-injector/css
Lists all CSS injector configurations with their conditions and status. Provides operations to edit, delete, enable, disable, and duplicate each CSS injector.
/admin/config/development/asset-injector/css/add
Form to create a new CSS injector configuration with code, conditions, and advanced options.
/admin/config/development/asset-injector/css/{asset_injector_css}
Form to edit an existing CSS injector configuration. Same fields as the add form but with the machine name disabled.
/admin/config/development/asset-injector/js
Lists all JavaScript injector configurations with their conditions and status. Provides operations to edit, delete, enable, disable, and duplicate each JS injector.
/admin/config/development/asset-injector/js/add
Form to create a new JavaScript injector configuration with code, conditions, noscript fallback, and advanced options.
/admin/config/development/asset-injector/js/{asset_injector_js}
Form to edit an existing JS injector configuration. Same fields as the add form but with the machine name disabled.
Permissions 2
Hooks 1
hook_asset_injector_library_info_build_alter
Allows other modules to alter the dynamic library array generated by Asset Injector before it is returned to Drupal for inclusion.
Troubleshooting 6
Check that the injector is enabled (Status: Enabled), verify the conditions are correctly configured, and clear all caches. Also ensure the user has the appropriate permissions to view the content.
Ensure the public://asset_injector directory exists and is writable by the web server. Check file system permissions in Administration > Reports > Status report.
CKEditor integration requires the CSS injector to be enabled and have no conditions that would prevent it from loading. Verify the injector status and conditions.
Check browser console for JavaScript errors. Ensure the code does not include <script> wrapper tags. If the code requires jQuery, enable the 'Requires jQuery' checkbox.
Asset Injector automatically invalidates caches when saving, but if using external caching (Varnish, CDN), you may need to purge those caches manually.
Drupal 9.5+ changed the theme condition to support only a single theme. Review your theme condition settings and select only one theme per asset.
Security Notes 7
- The 'Administer JS Assets' permission allows injection of arbitrary JavaScript and should only be granted to highly trusted administrators as it can be used for XSS attacks.
- The 'Administer CSS Assets' permission is less dangerous but can still be used to alter page appearance maliciously or inject CSS-based attacks.
- Both permissions have 'restrict access: true' indicating they should be carefully managed.
- Asset code is not sanitized - administrators are responsible for ensuring injected code is safe.
- Consider using Content Security Policy (CSP) headers to provide additional protection against injected script attacks.
- Review all injector configurations periodically, especially on sites with multiple administrators.
- Generated asset files are stored in publicly accessible directories - do not include sensitive information in injected code.