Configuration Options
Deep dive into BareMetal.init() properties
Core Settings
debug (boolean | default: false)
Enables verbose console logs during the module loading and routing lifecycles.
keepAliveSameModules (boolean | default: true)
Prevents destruction of modules that are shared between the outgoing and incoming routes, improving cross-page performance and preserving internal module state.
autoWrap (boolean | default: true)
Automatically wraps loaded JS modules that do not export a mount function. This ensures third-party scripts don't break the loader sequence.
Performance
hoverPrefetch (boolean | default: false)
Enables 0ms latency pre-fetching. When a user hovers over an internal link, BareMetal quietly fetches the HTML payload in the background before they even click.
Tip: If you have internal links that trigger API redirects (like SSO login) or file downloads, you should prevent the router (and hoverPrefetch) from intercepting them by adding the data-baremetal="ignore" attribute to the <a> tag.
virtualizeDom (boolean | default: false)
Injects the Virtualizer helper directly into the mount contexts of your modules for optimized rendering.
Resilience & UX
persistState (boolean | default: false)
Automatically serializes the global stateManager to sessionStorage. When a user forces an F5 refresh, the state is fully recovered, preventing data loss.
showErrorNotification (boolean | default: false)
When a navigation fails (e.g., 404), BareMetal will float an error boundary on the screen instead of silently dropping the error or breaking the DOM.
Transitions
transition.enabled (boolean | default: false)
Enables the protected transition module system.
transition.module (string | default: null)
Points to your custom transition JavaScript file. The element with id="baremetal-transition-root" is protected from DOM swaps to ensure the transition continues across navigation boundaries.
transition.simulatedDelay (number | default: 0)
Adds an artificial delay (in ms) during navigation to test transition animations effectively locally.
transition.useViewTransitions (boolean | default: false)
Uses the browser's native View Transitions API (document.startViewTransition) to perform buttery smooth cross-fades between the outgoing and incoming DOM payloads. No custom CSS needed.