@elliemae/cold-start-library
v26.3.0
Published
ICE MT Platform UI Monorepo Library - cold-start (cache warming, asset preloading, idle scheduling)
Downloads
185
Readme
Cold Start Library
@elliemae/cold-start-library prefetches micro-app assets during browser idle time to warm the HTTP cache. It fetches each app's manifest.json, discovers JS and CSS assets, and injects <link rel="preload"> tags so subsequent navigations load instantly.
How It Works
- You register micro-app entries with
CacheWarmer, providing the origin, base path, and version. - The library waits for the browser to become idle (
requestIdleCallback). - It fetches
{url}/{basePath}/{version}/manifest.jsonand identifies JS/CSS assets. <link rel="preload">tags are injected into<head>during idle time, warming the browser cache.- Subsequent navigations to those micro-apps load assets from cache.
Installation
pnpm add @elliemae/cold-start-libraryQuick Start
import { CacheWarmer } from '@elliemae/cold-start-library';
const warmer = new CacheWarmer();
warmer.register([
{
key: 'dashboard',
url: 'https://app.example.com',
basePath: 'dashboard-app',
version: '1.0',
},
{
key: 'settings',
url: 'https://app.example.com',
basePath: 'settings-app',
version: '2.1',
autoTrigger: false,
},
]);
// dashboard starts loading immediately during idle time.
// settings waits until you explicitly trigger it:
warmer.trigger('settings');
// Check the result of a prefetch:
const result = await warmer.getResult('dashboard');
console.log(result.status); // 'success' | 'error' | 'timeout'
console.log(result.preloadedAssets); // ['https://...app.abc123.js', ...]
// Clean up when done:
warmer.dispose();Selective Asset Preloading
Use assetFilter to preload only specific assets from the manifest instead of everything. Pass the manifest keys you want:
warmer.register([
{
key: 'fee-itemization',
url: 'https://encompass.q3.ice.com',
basePath: 'em-web-forms',
version: '26.2',
assetFilter: ['app.js', 'vendors.js', 'main.css'],
},
]);Only assets whose manifest key is in the list will be preloaded. When assetFilter is omitted, all JS and CSS assets from the manifest are preloaded.
API
new CacheWarmer()
Creates a new CacheWarmer instance.
register(entries: IPrefetchEntry[]): void
Registers micro-app entries for prefetching.
- Entries with
autoTrigger: true(default) begin loading on the next browser idle. - Entries with
autoTrigger: falsewait untiltrigger(key)is called. - Throws if a duplicate
keyis registered.
trigger(key: string): void
Manually triggers a deferred entry by its key, starting the prefetch.
- Throws if
keyis not registered. - Throws if
keyhas already been triggered.
getResult(key: string): Promise<IPrefetchResult>
Returns a promise that resolves with the prefetch result for the given key.
- Throws if
keyis not registered.
isTriggered(key: string): boolean
Returns whether the entry for the given key has been triggered.
- Throws if
keyis not registered.
dispose(): void
Disposes the instance, cleaning up all internal resources (preload links, idle callbacks). After disposal, all public methods will throw. Safe to call multiple times.
isDisposed: boolean
Whether the instance has been disposed.
Types
IPrefetchEntry
interface IPrefetchEntry {
key: string; // Unique identifier for this entry
url: string; // Origin URL, e.g. "https://encompass.q3.ice.com"
basePath: string; // Base path of the micro-app, e.g. "em-web-forms"
version: string; // App version, used to build the manifest URL
autoTrigger?: boolean; // Start loading on idle (default: true)
assetFilter?: string[]; // Only preload these manifest keys
}The manifest URL is derived as {url}/{basePath}/{version}/manifest.json.
IPrefetchResult
interface IPrefetchResult {
url: string; // The origin URL
key: string; // The entry key
status: 'success' | 'error' | 'timeout'; // Outcome
duration: number; // Time in milliseconds
preloadedAssets?: string[]; // Asset URLs that were discovered and preloaded
}Debug Logging
Enable verbose console logging by setting the following in the browser console:
window.cacheWarmerDebug = true;Running Tests
pnpm testRuns Playwright E2E tests against real browsers. Tests run in Chromium and Firefox on all platforms, with WebKit (Safari) on macOS.