| Understand Drupal's JavaScript architecture |
JavaScript Architecture |
Use this understanding before implementing any JavaScript functionality in Drupal. This is foundational knowledge for all Drupal JS work. |
| Define a JavaScript library |
Library Definitions |
Use every time you add JavaScript to a module or theme. All JS must be defined in a library. |
| Choose core dependencies |
Core Dependencies |
Use when defining any JavaScript library. Dependencies ensure required code loads first. |
| Load scripts in header or footer |
Header vs Footer Loading |
Use when JavaScript affects critical rendering or initial page display. Otherwise, use default footer loading. |
| Attach libraries via PHP |
Library Attachment Methods |
Use when deciding how to attach libraries to pages based on context and conditions. |
| Load JavaScript conditionally |
Conditional Loading |
Use when optimizing performance by loading JavaScript only when needed based on content type, route, user role, or other conditions. |
| Initialize JavaScript on page load and AJAX |
Drupal.behaviors Pattern |
Always for DOM manipulation in Drupal. Behaviors are the foundation of Drupal JavaScript - they work with AJAX, BigPipe, and dynamic content loading. |
| Prevent duplicate initialization |
Once API |
Every time you process elements in a behavior. The once() API prevents duplicate initialization and is required for proper AJAX compatibility. |
| Pass PHP data to JavaScript |
drupalSettings |
Use when passing server-side data (PHP) to client-side JavaScript. Alternative to AJAX requests for static configuration data available at page render. |
| Manipulate the DOM safely |
DOM Manipulation |
Use when modifying page structure, content, or attributes in response to user interaction or dynamic updates. |
| Integrate with Drupal AJAX |
AJAX Integration |
Use when loading content dynamically without full page refresh, or when JavaScript needs to respond to Drupal AJAX events. |
| Handle user interactions and events |
Event Handling |
Use when responding to user interactions (clicks, input changes, scrolling) or custom application events. |
| Use ES6+ features |
ES Modules and Modern JavaScript |
Use when understanding modern JavaScript features available in Drupal 10/11 and how to use ES6+ syntax. |
| Add JavaScript to SDC components |
JavaScript in SDC Components |
Use when adding interactive behavior to Single Directory Components (Drupal core feature since 10.3). |
| Optimize JavaScript performance |
Performance Optimization |
Use for every JavaScript implementation - performance is not optional. Frontend performance directly impacts user experience and SEO. |
| Enable aggregation and minification |
Aggregation and Minification |
Use in production environments - always enable JavaScript aggregation for performance. |
| Use defer and async attributes |
Defer and Async Attributes |
Use as default for most JavaScript - improves page load performance by allowing non-blocking script loading. |
| Debounce or throttle events |
Debounce and Throttle |
Use for events that fire rapidly (scroll, resize, input, mousemove) where executing handler every time causes performance issues. |
| Prevent XSS and secure JavaScript |
Security |
Use any time JavaScript handles user input, manipulates DOM, or processes data from external sources. |
| Test JavaScript functionality |
Testing JavaScript |
Use when verifying JavaScript functionality, especially AJAX interactions, accessibility, and cross-browser compatibility. |
| Avoid common mistakes |
Common Anti-Patterns |
Use when reviewing code for mistakes and understanding what NOT to do. |
| Review code quality standards |
Best Practices Summary |
Use as a code review checklist and development standards reference. |