Initialization

BareMetal.init(config)

BareMetal exports its core engine as a global configuration object. Initializes the engine, sets up the Router, and binds global configurations.

Usage Example

BareMetal.init({ debug: false, keepAliveSameModules: true, autoWrap: true, hoverPrefetch: true, persistState: false, virtualizeDom: false, showErrorNotification: true, transition: { enabled: false, useViewTransitions: false } });

Importing & Auto-Wrapping JS Modules

BareMetal strictly uses ES Modules (type: "module"). When navigating to a new page, the engine dynamically imports the scripts defined in your loader({...}) configuration.

By default, dynamically imported modules are expected to export a mount(context) function. However, if you are working with plain JavaScript files that don't explicitly export a mount function, BareMetal's built-in auto-wrapper will handle it.

When autoWrap: true is enabled (which is the default), the engine fetches the script and automatically wraps the content inside a mount function, injecting the state context for you:

Auto-Wrapped Output Example

export async function mount(context) { const { state } = context; // Your original script content here }

Manual Module Wrapping

For full control (and to avoid the overhead of auto-wrapping), you can manually export the mount function. This allows you to safely subscribe to state changes, initialize UI bindings, and return a destroy() function for garbage collection when the user navigates away.

assets/js/shared.js

export function mount({ state, onCleanup }) { // 1. Initialize state state.init('transCount', 0); // 2. Bind UI Elements const bindUI = () => { const btn = document.getElementById('btn-translate'); if (btn) { btn.onclick = () => state.update('transCount', state.get('transCount') + 1); } }; bindUI(); // 3. Listen to state changes const unsub = state.subscribe('transCount', (val) => { const display = document.getElementById('trans-count'); if (display) display.textContent = val; }); // 4. Register cleanups using the hook onCleanup(() => { unsub(); // Remove other event listeners... }); // Alternatively, you can explicitly return a destroy function: return { destroy: () => { // Cleanup to prevent memory leaks } }; }

Importing Modules via Loader

Once your module is ready, you tell the engine to load it on specific pages by calling loader({...}) in the HTML:

index.html

Bypassing the SPA Router

If you have internal links that you do not want the engine to intercept (e.g., links that trigger server-side redirects, file downloads, or SSO authentication), you can add the data-baremetal="ignore" attribute to the anchor tag. This forces the browser to perform a native, hard navigation.

Usage Example

<a href="/api/login" data-baremetal="ignore">Login</a>

Configuration Reference

BareMetal exposes several powerful configuration options to control module caching, page transitions, and DOM virtualization.

Read Full Configuration Guide