|
| 1 | +--- |
| 2 | +title: Debug Panel |
| 3 | +description: The built-in development debug bar — what each tab shows, how to configure it, and when it appears. |
| 4 | +type: howto |
| 5 | +sidebar: |
| 6 | + order: 11 |
| 7 | +--- |
| 8 | + |
| 9 | +import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components'; |
| 10 | + |
| 11 | +The Debug Panel is a fixed bar that Wheels appends to every HTML response in development mode. It surfaces request details, execution timing, parameters, environment configuration, installed packages, and links to built-in tools — without leaving the page you are working on. The panel is rendered by `vendor/wheels/events/onrequestend/debug.cfm` and runs at the very end of the request lifecycle, after your controller and views have finished. |
| 12 | + |
| 13 | +**You'll learn:** |
| 14 | + |
| 15 | +- When the debug bar appears and how to control it |
| 16 | +- What each tab shows and which configuration drives it |
| 17 | +- How to read the timing breakdown to find bottlenecks |
| 18 | +- Where to find package and plugin status |
| 19 | +- How to access developer tools from the bar |
| 20 | + |
| 21 | +## When the debug bar appears |
| 22 | + |
| 23 | +The bar only renders for standard full-page HTML requests. It is automatically suppressed for any of the following: |
| 24 | + |
| 25 | +- AJAX requests (`X-Requested-With: XMLHttpRequest`) |
| 26 | +- HTMX requests (`HX-Request`) |
| 27 | +- Turbo Frame requests (`Turbo-Frame`) |
| 28 | +- Fetch requests (`X-Fetch: true`) |
| 29 | +- Requests that produce structured output (`?format=json`, `xml`, `csv`, or `pdf`) |
| 30 | + |
| 31 | +This means AJAX-driven partial updates, Turbo Streams, API endpoints, and CSV exports all receive clean responses with no injected HTML. |
| 32 | + |
| 33 | +## Enabling and disabling |
| 34 | + |
| 35 | +The bar respects the `showDebugInformation` application setting. By default, Wheels sets this to `true` only in the `development` environment and `false` in every other environment (`testing`, `maintenance`, and `production`). You can override it explicitly in `config/environment.cfm`: |
| 36 | + |
| 37 | +```cfm title="config/environment.cfm" |
| 38 | +<cfset set(showDebugInformation=true)> |
| 39 | +``` |
| 40 | + |
| 41 | +Setting `showDebugInformation=false` removes the bar entirely — no HTML is injected into responses. |
| 42 | + |
| 43 | +<Aside type="caution"> |
| 44 | + Never enable the debug bar in production. It renders internal state — your data source name, environment, CFML engine version, and parameter values — that you do not want visible to end users. |
| 45 | +</Aside> |
| 46 | + |
| 47 | +## The debug bar |
| 48 | + |
| 49 | +When active, the bar appears as a slim strip pinned to the bottom of the browser window. Tabs are arranged from left to right: a Wheels logo (doubles as the Request tab toggle), then Request, Timing, Params, Environment, and optionally Tools. The right side shows the current git branch (when Wheels detects a `.git` directory), the framework version, and a one-click reload link when no reload password is configured. |
| 50 | + |
| 51 | + |
| 52 | + |
| 53 | +Clicking any tab opens a panel above the bar. Clicking the same tab again closes it. The minimize button (×) collapses the bar to a small "Debug" button in the corner, persisted via `sessionStorage` so it stays collapsed as you navigate. |
| 54 | + |
| 55 | +## Request tab |
| 56 | + |
| 57 | +The Request tab label shows `controller.action` for the current request. Clicking it opens a key-value panel with: |
| 58 | + |
| 59 | +| Field | Description | |
| 60 | +|---|---| |
| 61 | +| Route | Named route that matched this request (omitted when no named route matched) | |
| 62 | +| Controller | Controller name | |
| 63 | +| Action | Action name | |
| 64 | +| Key | URL key segment, if present | |
| 65 | +| HTTP Method | `GET`, `POST`, `PUT`, `DELETE`, etc. | |
| 66 | +| URL | Full URL for this request | |
| 67 | +| Application | Value of `applicationName` from `Application.cfc` | |
| 68 | +| Data Source | The configured `dataSourceName` | |
| 69 | +| DB Adapter | The active database adapter (MySQL, PostgreSQL, SQL Server, etc.) — omitted when the adapter name is not detected | |
| 70 | +| URL Rewriting | Current URL rewriting mode | |
| 71 | + |
| 72 | + |
| 73 | + |
| 74 | +Use this panel to confirm that routing resolved the way you intended, that the correct data source is in use, and that URL rewriting is configured as expected. |
| 75 | + |
| 76 | +## Timing tab |
| 77 | + |
| 78 | +The Timing tab label shows the total request duration in milliseconds, color-coded by threshold: |
| 79 | + |
| 80 | +- **Green** — under 100 ms |
| 81 | +- **Yellow** — 100–499 ms |
| 82 | +- **Red** — 500 ms or more |
| 83 | + |
| 84 | +Opening the panel shows a horizontal bar chart breaking down where time was spent. Each phase (model, queries, template rendering, etc.) is sorted by duration descending and rendered as a proportional colored bar showing both the raw milliseconds and the percentage of total time. |
| 85 | + |
| 86 | + |
| 87 | + |
| 88 | +The chart is most useful for spotting query-heavy actions: if `queries` or `model` accounts for 80%+ of total time, look at the SQL being generated (the Routes admin page lists query counts per action if you need more detail). |
| 89 | + |
| 90 | +## Params tab |
| 91 | + |
| 92 | +The Params tab shows the count of extra request parameters as a badge. Opening the panel displays a table of every parameter that was available to the action, excluding the routing parameters (`controller`, `action`, `key`, `route`) and `fieldnames`. |
| 93 | + |
| 94 | +| Column | Description | |
| 95 | +|---|---| |
| 96 | +| Name | Parameter key, lowercased | |
| 97 | +| Value | The value; complex values (structs, arrays) are JSON-encoded | |
| 98 | +| Type | `string` or `json` | |
| 99 | + |
| 100 | + |
| 101 | + |
| 102 | +This is the fastest way to confirm that form fields, query string values, and nested structs arrived the way you expected before you reach for a `writeDump` call. |
| 103 | + |
| 104 | +## Environment tab |
| 105 | + |
| 106 | +The Environment tab label shows the current environment name (Development, Testing, etc.) with a color-coded dot matching the timing badge palette. The panel is divided into subsections based on what is enabled. |
| 107 | + |
| 108 | +### Application |
| 109 | + |
| 110 | +Always shown. Lists the environment, the git branch (when the app root contains a `.git` directory), the Wheels version, the CFML engine and version, and the host name (when available). |
| 111 | + |
| 112 | +When no reload password is set, the environment name is followed by quick-switch links that reload the app in a different environment mode. This is useful during development to test environment-specific code paths without editing config files. |
| 113 | + |
| 114 | + |
| 115 | + |
| 116 | +### Packages |
| 117 | + |
| 118 | +Shown when `enablePackagesComponent` is `true` (the default in Wheels 4.0+). Displays two tables. |
| 119 | + |
| 120 | +**Installed packages** lists every package found in `vendor/` and loaded by `PackageLoader.cfc`: |
| 121 | + |
| 122 | +| Column | Description | |
| 123 | +|---|---| |
| 124 | +| Package | Package name from `package.json` | |
| 125 | +| Version | Semver version string | |
| 126 | +| Description | One-line description | |
| 127 | + |
| 128 | +If any package failed to load (manifest error, missing dependency, CFC exception), a red error list appears below the installed table with the package name and the exception message. |
| 129 | + |
| 130 | +**Available from registry** pulls the same 24-hour cached registry index used by the `wheels packages` CLI and shows what is available to install: |
| 131 | + |
| 132 | +| Column | Description | |
| 133 | +|---|---| |
| 134 | +| Package | Name, linked to the package homepage when available | |
| 135 | +| Latest | Latest compatible version | |
| 136 | +| Description | Registry description | |
| 137 | + |
| 138 | + |
| 139 | + |
| 140 | +This lets you discover first-party packages such as `wheels-hotwire`, `wheels-sentry`, or `wheels-i18n` without leaving the app. The table reflects the same 24-hour cache as `wheels packages list`; run `wheels packages registry refresh` from the CLI if you need up-to-the-minute data. |
| 141 | + |
| 142 | +### Plugins (legacy) |
| 143 | + |
| 144 | +Shown when `enablePluginsComponent` is `true`. Lists plugins installed in the legacy `plugins/` directory with their names and versions. Legacy plugins are the Wheels 3.x predecessor to packages — if you are on a fresh 4.x app, this section is likely empty. |
| 145 | + |
| 146 | +If any plugin warnings exist, a red **Warnings** subsection appears beneath the plugin table: |
| 147 | + |
| 148 | +- **Incompatible plugins** — plugins flagged as incompatible with the current Wheels version (controlled by `showIncompatiblePlugins`) |
| 149 | +- **Dependent plugins** — plugins whose dependencies are not satisfied |
| 150 | +- **Version mismatches** — plugins that require a different version of another plugin than what is loaded |
| 151 | +- **Mixin collisions** — cases where two plugins defined the same method name on the same mixin target; the later-loaded plugin wins |
| 152 | + |
| 153 | +## Tools tab |
| 154 | + |
| 155 | +Shown when `enablePublicComponent` is `true` (the default in development). Opens a grid of link cards, each opening in a new tab: |
| 156 | + |
| 157 | +| Card | Links to | |
| 158 | +|---|---| |
| 159 | +| System Info | `/wheels/info` — Wheels internals, environment variables, loaded settings | |
| 160 | +| Routes | `/wheels/routes` — all registered routes with HTTP method, path, and handler | |
| 161 | +| API Docs | `/wheels/api` — generated API documentation | |
| 162 | +| Guides | `/wheels/guides` — the documentation site | |
| 163 | +| Tests | `/wheels/app/tests` — the test runner | |
| 164 | +| Migrator | `/wheels/migrator` — the database migration UI (shown when `enableMigratorComponent` is `true`) | |
| 165 | +| Packages | `/wheels/packages` — the package browser (shown when `enablePackagesComponent` is `true`) | |
| 166 | +| Plugins | `/wheels/plugins` — the legacy plugin list (shown when `enablePluginsComponent` is `true`) | |
| 167 | + |
| 168 | + |
| 169 | + |
| 170 | +## Configuration reference |
| 171 | + |
| 172 | +All settings are applied in `config/settings.cfm` or an environment-specific file under `config/`: |
| 173 | + |
| 174 | +```cfm title="config/environment.cfm" |
| 175 | +<cfset set(showDebugInformation=true)> |
| 176 | +<cfset set(enablePackagesComponent=true)> |
| 177 | +<cfset set(enablePluginsComponent=true)> |
| 178 | +<cfset set(showIncompatiblePlugins=true)> |
| 179 | +<cfset set(enablePublicComponent=true)> |
| 180 | +<cfset set(enableMigratorComponent=true)> |
| 181 | +``` |
| 182 | + |
| 183 | +| Setting | Default | Effect | |
| 184 | +|---|---|---| |
| 185 | +| `showDebugInformation` | `true` in `development`, `false` elsewhere | Show or hide the debug bar entirely | |
| 186 | +| `enablePackagesComponent` | `true` | Show the Packages subsection in the Environment panel and the Packages link in Tools | |
| 187 | +| `enablePluginsComponent` | `true` | Show the Plugins (Legacy) subsection and the Plugins link in Tools | |
| 188 | +| `showIncompatiblePlugins` | `true` | Include incompatible-plugin warnings in the Warnings subsection | |
| 189 | +| `enablePublicComponent` | `true` in `development`, `false` elsewhere | Show the Tools tab and its link grid | |
| 190 | +| `enableMigratorComponent` | `true` | Show the Migrator link in the Tools panel | |
| 191 | + |
| 192 | +## Related guides |
| 193 | + |
| 194 | +<CardGrid> |
| 195 | + <LinkCard |
| 196 | + title="Packages" |
| 197 | + description="Install first-party packages, write your own, and understand the vendor/ activation model — the same packages that appear in the debug bar's Packages tab." |
| 198 | + href="/v4-0-0-snapshot/digging-deeper/packages/" |
| 199 | + /> |
| 200 | + <LinkCard |
| 201 | + title="Configuration" |
| 202 | + description="Full reference for all Wheels application settings, including the debug-related flags covered here." |
| 203 | + href="/v4-0-0-snapshot/configuration/" |
| 204 | + /> |
| 205 | +</CardGrid> |
![wheels-bot[bot]](https://avatars.githubusercontent.com/in/3657588?v=4&size=40){kind=avatar}
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments