Download the PHP package modracx/mage-frontend-dev-tools without Composer

Modracx Frontend Dev Tools

Overview

A storefront developer toolbar and profiler for Magento 2 that lives on the top‑center of every storefront page. Compatible out-of-the-box with Luma, Hyvä, and Breeze themes, it delivers real-time visibility into database query counts, N+1 query patterns, block rendering hierarchies, layout handles, Full Page Cache (FPC) state, theme file fallback resolution, event observer overhead, client-side JavaScript errors, Core Web Vitals, and frontend state (Alpine, Breeze, RequireJS/Knockout) – all without slowing down the page or interfering with your site's design.

The toolbar features a 3-layer security gate (module switch/mode, IP CIDR whitelist, and signed crypt-key access tokens) to ensure zero impact on regular shoppers and zero exposure of sensitive store telemetry in production environments.

Features

UI Design & Architecture

• Launcher & Severity Indicator – A dimmed MODRACX pill centered at the top edge of the screen. The pill changes color depending on the severity of issues detected on the page (clean, low, medium, high, critical).
• Lazy-Loaded Drawer – Clicking the pill slides down a tab strip. Panel content is fetched lazily via AJAX (modracx_fdt/panel/view), ensuring the profiler never adds overhead to the page rendering time.
• 3-Layer Security Gate –
  1. Master configuration switch & Magento mode check (allow_production).
  2. Client IP check supporting exact IPs and CIDR ranges (e.g. 10.0.0.0/8).
  3. HMAC token cookie (mdx_fdt) derived from Magento's crypt/key.
• Smart Theme Asset Resolution – Resolves theme assets directly using resolvedTheme() so the toolbar's CSS and JS load cleanly even on Full Page Cache (FPC) hits without 404 errors under placeholder paths like frontend/_view/en_US/.
• Non-Intrusive & Persistent Position – Drag the launcher horizontally if it overlaps page elements; position is saved in localStorage. Fits securely between standard layouts with z-index: 999999.
• Keyboard Shortcuts & CSP Safe – Supports Esc to close, Tab focus trapping, and arrow key tab switching. Hydrates runtime state via inert JSON script blocks to remain fully compliant with strict Content Security Policy (CSP) rules on Magento 2.4.8+.

Installation

Storefront Access (Opt-in Workflow)

Because the storefront is public, access requires explicit opt-in so shoppers never see profiling data:

1. Generate your developer access link via CLI:

2. Open the generated link in the browser where you want the toolbar enabled:

   This sets a signed mdx_fdt cookie valid for 30 days.

3. Ensure your IP address is allowed in Stores → Configuration → Advanced → Modracx Frontend Dev Tools → Allowed IP Addresses.
4. To disable access for your browser, click Disable Toolbar in the toolbar drawer footer or navigate to /modracx_fdt/access/disable.

Configuration

Configure options under Stores → Settings → Configuration → Advanced → Modracx Frontend Dev Tools:

Permissions & ACL

Control access to profiler administration under System → Permissions → User Roles → Role Resources:

Routes

CLI Commands

Safety & Security

• Zero Shopper Overhead – Requests from unallowed IPs or browsers lacking the access cookie undergo zero timing, zero database logging, and zero DOM injection.
• Crypt-Key HMAC Verification – Access token is derived dynamically from deploymentConfig::get('crypt/key') using SHA-256 HMAC (Modracx\FrontendDevTools\Model\AccessGate). It is never stored in the database or exposed in plain text.
• Memory & Storage Defense – Each collector respects a configurable cap (max_events, default 5,000). Stored profiles are automatically pruned by background cron (Modracx\FrontendDevTools\Cron\PruneProfiles) according to retention_hours (default 24h).
• Isolated Template Hints – Toggling template or block hints relies on a secure cookie (mdx_fdt_hints) scoped strictly to your browser session without altering global Magento store settings.
• Sensitive Value Masking – Database queries and environment diagnostic parameters automatically sanitize credentials and tokens.

User Guide (full walkthrough)

Accessing the Toolbar

1. Run bin/magento modracx:frontend:token on your server terminal.
2. Copy the enablement URL and open it in your web browser.
3. Visit any storefront page. Locate the dimmed "MODRACX" pill centered on the top edge of the browser viewport.
4. Hover over the pill to see overall page status; click to slide down the developer toolbar.

Navigating the Drawer

Use mouse or keyboard navigation:

Panel Walkthrough

1. Overview Tab

• Displays headline timing stats: total request time, peak memory usage, DB query count & time, block count & time, dispatched events, and FPC cache status (HIT, MISS, UNCACHEABLE, OFF).
• Shows a direct comparison against the previous run of the same action to immediately spot performance regressions.

2. Issues Tab

• Separates findings into Userland (your custom/third-party code) and Core (Magento/Hyvä framework code).
• Groups findings by severity (critical, high, medium, low).
• Identifies N+1 query loops, duplicate queries, slow block renders, and slow observers with exact code origins and estimated time savings (saving_ms).

3. Vitals Tab

• Displays real user browser performance metrics:
  • LCP (Largest Contentful Paint)
  • CLS (Cumulative Layout Shift)
  • INP (Interaction to Next Paint)
  • TTFB (Time to First Byte)
  • FCP (First Contentful Paint)
  • DOM Interactive & Load event timing.

4. SQL Tab

• Lists every database query executed during the request.
• Groups queries by fingerprint, showing execution counts, average/total times, and distinct parameter bindings.
• Expands any query to view full PHP stack backtraces identifying the caller class, method, file, and line number.

5. Blocks Tab

• Visualizes the complete block rendering tree.
• Details Exclusive Time (time spent purely in the block method/template) versus Inclusive Time (time including child blocks).
• Shows block class names, assigned template files, cache keys, and cache lifetimes.

6. Layout Tab

• Displays all active layout handles applied to the request (e.g. default, catalog_product_view).
• Inspects merged layout XML structure.
• Flags non-cacheable blocks (cacheable="false") that prevent Full Page Caching.

7. Theme Tab

• Displays active frontend stack detection (Hyvä, Breeze, or Luma).
• Shows the active theme inheritance chain.
• Resolves theme fallback files to pinpoint exactly which module or theme template override rendered.

8. Cache Tab

• Inspects Full Page Cache hit/miss/uncacheable status and response headers.
• Lists active cache tags generated for the page.
• Monitors customer section data (private content) state, invalidation triggers, and section payload TTLs.

9. Events Tab

• Lists all Magento events dispatched during the request lifecycle.
• Displays registered observer classes, sort order, and individual execution times in milliseconds.

10. Modules Tab

• Summarizes total CPU time, database query count, block count, and observer overhead grouped by module namespace.
• Helps immediately pinpoint heavy third-party vendor modules.

11. Client Tab

• Reports frontend runtime errors captured in the browser:
  • JavaScript uncaught exceptions & stack traces.
  • Failed AJAX / fetch network requests.
  • Content Security Policy (CSP) violations.
  • 404 missing static assets.

12. Stack Tab

• Provides deep state inspection for your active frontend framework:
  • Hyvä: Alpine.js component data & customer section store state.
  • Breeze: Breeze JS components & PJAX state.
  • Luma: RequireJS loaded modules & Knockout component registry.

13. Environment Tab

• Summarizes PHP version, memory limits, OPcache & Xdebug state, Magento mode, active database connection, and indexer status.

14. History Tab

• Logs recent storefront page loads, AJAX requests, and GraphQL operations.
• Click any historical run to inspect its complete profile in the toolbar.

Toggling Template & Block Hints

Use the Hints toggle button in the top right of the toolbar drawer to switch template hints on demand:

• Off: Standard storefront rendering.
• Templates: Shows template file paths (.phtml) directly on storefront markup for your session only.
• Blocks: Shows template file paths alongside Magento Block class names.

Security & Best Practices

1. Keep require_cookie Enabled: Ensures only authorized developers with valid tokens can view profiler output.
2. Restrict IP Ranges: Limit allowed_ips to known office/VPN IP subnets.
3. Production Mode Guard: Leave allow_production set to No unless actively debugging a staging/production issue under strict IP restrictions.

Uninstalling the Extension

Clear caches after disabling to remove toolbar assets from storefront pages.

Happy profiling!

Elevate your storefront performance analysis with Modracx Frontend Dev Tools. For updates, documentation, or support, visit the Modracx Portal or check the repository.