Introduction

What is resource-fallback

resource-fallback is a zero-mental-overhead frontend resource fallback solution. It provides runtime retry → multi-CDN fallback → origin capabilities for Webpack and Vite build outputs (sync / async JS, CSS) — no changes to business code required.

The project ships three npm packages:

Package	Description
@resource-fallback/core	Browser IIFE runtime + Node utility functions
@resource-fallback/vite-plugin	Vite 4+ plugin
@resource-fallback/webpack-plugin	Webpack 5+ plugin

Why resource fallback matters

Frontend static assets are usually served from CDNs. When the primary CDN hits DNS failures, network jitter, or regional outages, pages can white-screen, lose styles, or fail lazy-loaded modules.

Traditional approaches require manual failure handling in business code or complex gateway routing. resource-fallback injects a runtime at build time and intercepts failures automatically, retrying the same URL, switching to backup CDNs, and finally falling back to origin — all transparent to application code.

Use cases

• Multi-CDN disaster recovery and primary/backup switching
• Automatic degradation when static assets fail to load
• Monitoring and observability for fallback chains

Architecture overview

Fallback flow

Package structure

Package	Description	Version source
@resource-fallback/core	Browser IIFE runtime + Node utility functions	See npm page / package.json
@resource-fallback/vite-plugin	Vite 4+ plugin	See npm page / package.json
@resource-fallback/webpack-plugin	Webpack 5+ plugin	See npm page / package.json

@resource-fallback/core

Core runtime and build utilities:

• RecoveryCoordinator — the page-side decision engine for rule selection, retry/fallback, deadlines, cancellation, and events
• Retry — exponential backoff + jitter
• Circuit Registry — per-host circuit state; the page runtime currently uses a single registry with optional localStorage cross-tab sharing
• Observer — listens for <script> / <link> error events
• Adapters — Vite / Webpack / SystemJS / SW adapters; they provide transport and ownership admission
• buildInjectedTags() — generates HTML injection tags
• getRuntimeCode() — returns IIFE runtime source

@resource-fallback/vite-plugin

Vite build integration — see Vite Integration:

• transformIndexHtml HTML injection
• dynamic import() wrapping
• Optional Hybrid SW asset generation

Three current page-runtime limits are worth calling out:

• window.__RF__.url(filename) always builds the initial URL from the first compiled rule's base; it does not skip circuit-open hosts;
• rules are compiled with longer base prefixes first, and once recovery starts the RecoveryCoordinator picks one rule from the initial URL and walks that rule's ordered candidates;
• the page runtime currently initializes one circuit registry rather than one per rule.

@resource-fallback/webpack-plugin

Webpack build integration — see Webpack Integration:

• RuntimeModule injection, patches __webpack_require__.l
• html-webpack-plugin HTML injection integration
• Optional Hybrid SW asset generation

Next steps

• Quick Start — installation and minimal config
• Configuration Reference — full options
• Hybrid Service Worker — image, font, and subresource fallback