flare-router

v1.0.0

Published

6 months ago

Blazingly fast SPA-like router for static sites - Pure vanilla JS

0High
0Medium
0Low

dunamismax

router spa navigation vanilla-js prefetch static-sites flare lightweight

flare-router 🔥

A 3.4kB zero-config router and intelligent prefetcher that makes static sites feel like blazingly fast SPAs. Transform any multi-page website into a lightning-fast experience without framework overhead.

Features

Ultra-Lightweight - Only 3.4kB gzipped bundle size
Zero Configuration - Works out of the box with any static site
Intelligent Prefetching - Automatic link prefetching with IntersectionObserver
SPA-like Navigation - Instant page transitions without full reloads
State Preservation - Long-lived JavaScript behaviors between navigations
Framework Agnostic - Drop-in solution for any website architecture
Modern Browser APIs - Built with IntersectionObserver, Fetch API, and History API

Project Structure

├── lib/
│   ├── main.js                # Main router entry point
│   ├── router.js              # Core router logic and navigation
│   ├── handlers.js            # Click and popstate event handlers
│   └── dom.js                 # DOM manipulation and head merging
├── example/                   # Example implementation
├── dist/                      # Built bundles
└── package.json               # Package configuration

Quick Start

Prerequisites: Modern browser with ES modules support

Get Running in 3 Steps

# 1. Install flare-router
npm install flare-router

# 2. Import and initialize
import flare from 'flare-router';
const router = flare();

# 3. That's it! Your site now feels blazingly fast

Example Implementation:

<!DOCTYPE html>
<html>
  <head>
    <title>My Fast Site</title>
  </head>
  <body>
    <nav>
      <a href="/">Home</a>
      <a href="/about">About</a>
      <a href="/contact">Contact</a>
    </nav>

    <main>
      <!-- Your content -->
    </main>

    <script type="module">
      import flare from 'flare-router';
      const router = flare({ prefetch: 'visible', log: true });
    </script>
  </body>
</html>

Tech Stack

Core: Vanilla JavaScript ES Modules, IntersectionObserver API, Fetch API, History API Build: esbuild for bundling Deployment: npm package with CDN support

Architecture

How flare-router Works:

Intelligent Prefetching - Uses IntersectionObserver to detect visible links and prefetches them
Event Interception - Captures click and popstate events for seamless navigation
Smart DOM Updates - Fetches new pages, swaps <body> content, and merges <head> elements
State Preservation - Maintains JavaScript state and long-lived behaviors between navigations

Development Scripts

# Build production bundles
npm run build

Advanced Usage

Router Configuration:

const router = flare({
  prefetch: 'visible', // 'visible', 'hover', or false
  log: true, // Enable debug logging
  pageTransitions: false, // Enable native browser transitions (experimental)
});

Programmatic Navigation:

// Navigate to specific routes
router.go('/dashboard');
router.back();
router.forward();

// Disable/enable router
router.enabled = false;

Event Handling:

// Listen to router events
window.addEventListener('flare:router:fetch', () => {
  showLoadingSpinner();
});

window.addEventListener('flare:router:fetch-progress', ({ detail }) => {
  updateProgressBar(detail.progress);
});

window.addEventListener('flare:router:end', () => {
  hideLoadingSpinner();
});

Link Control:

<!-- Opt-out specific links for full page reload -->
<a href="/external-site" data-cold>External Link</a>

<!-- Force head scripts to reload -->
<script src="/analytics.js" data-reload></script>

Code Examples

Basic Setup:

import flare from 'flare-router';

// Initialize with default settings
const router = flare();

Advanced Configuration:

import flare from 'flare-router';

// Full configuration
const router = flare({
  prefetch: 'visible',
  log: true,
  pageTransitions: false,
});

// Manual navigation
router.go('/products');

// Event listeners
window.addEventListener('flare:router:fetch', showLoader);
window.addEventListener('flare:router:end', hideLoader);

Progress Tracking:

window.addEventListener('flare:router:fetch-progress', ({ detail }) => {
  const progressBar = document.getElementById('progress-bar');
  const { progress, received, length } = detail;

  progressBar.style.width = `${progress}%`;
  console.log(`Downloaded ${received} of ${length} bytes`);
});

Browser Support

Supported: All modern browsers with ES modules, IntersectionObserver, Fetch API, and History API support

Fallback: Gracefully degrades to standard navigation in unsupported browsers

Framework Compatibility:

✅ Static sites (HTML, Jekyll, Hugo, etc.)
✅ Server-rendered applications
✅ Astro (with considerations for hydration)
❌ Next.js/Nuxt.js (already have client-side routing)

Contributing

Fork and create feature branch
Make changes following existing patterns
Run npm run build
Submit pull request

Development Workflow:

Uses esbuild for fast development builds
ESLint and Prettier for code quality

License

This project is licensed under the MIT License - see the LICENSE file for details.