Debug

FrontAlign ships with a lightweight, dependency-free diagnostics utility called Debug. It gives you structured, color-coded console output for everything the runtime does internally — component registration, lazy initialization, observer activity, and configuration issues — without adding any noise to your production console.

Debug mode is disabled by default. Nothing is printed to the console unless you explicitly turn it on.

Why Debug exists

Building interfaces with an intelligent runtime — one that lazily initializes components, observes the DOM, and reacts to visibility — makes silent failures easy to miss. The Debug utility exists to make that runtime observable on demand:

• Off by default. Zero console output, zero performance overhead in production.
• Guarded by level. Informational and warning messages only appear in debug mode; genuine errors are never hidden.
• Styled output. Each message is namespaced and color-coded by severity, so runtime logs are easy to scan visually.
• Framework-agnostic. Works identically in the browser console and in Node.js during SSR — style directives are simply ignored server-side.

Enable debug mode via the runtime

The most common way to use Debug is implicitly, through the FrontAlign runtime configuration. Pass debug: true when creating your instance.

import { FrontAlign } from "frontalign";

const fa = new FrontAlign({
  debug: true,
});

With this flag set, every guarded log and warn call made internally by the runtime — component registration, observer setup, lazy-load activity — becomes visible in your console. Leave it false (or omit it) in production.

Using Debug directly

Debug is also exported as a standalone module, so you can drive the same styled logging from your own application code — independent of whether a FrontAlign instance exists.

import { Debug } from "frontalign";

Debug.enable();

Debug.log("Custom component mounted:", "hero-carousel");

This is useful when you are building on top of FrontAlign — for example, inside a custom component, a plugin, or your own initialization logic — and want console output that's visually consistent with the rest of the framework.

API Reference

Log levels at a glance

Example: grouped diagnostics

Use group and groupEnd to keep related messages visually contained in the console. Both are no-ops when debug mode is off, so they're safe to leave in your code permanently.

import { Debug } from "frontalign";

Debug.enable();

Debug.group("Component Initialization");
Debug.log("Registering delegate components...");
Debug.log("navbar, collapse, dropdown, drawer, accordion, alert, form");
Debug.warn("No handler found for fa-component=\"legacy-carousel\"");
Debug.groupEnd();

Example: conditional setup from config

Debug.set() is convenient when you want to mirror an external boolean — such as your own app's environment flag — without branching manually.

import { Debug } from "frontalign";

Debug.set(process.env.NODE_ENV !== "production");

console.log(Debug.isEnabled); // true in development, false in production

Best practices

• Never enable debug mode in production builds. It is intended for local development and troubleshooting only.
• Prefer Debug.log over console.log inside custom components built on top of FrontAlign, so your output stays consistent with the runtime's own diagnostics and respects the guarded state.
• Never guard Debug.error. Real errors — misconfiguration, missing dependencies, invalid component registration — should always surface, even outside debug mode.
• Leave group/groupEnd calls in place. They are inert when debug mode is disabled, so there's no need to strip them out before shipping.

Related