Route - Dead Simple Routing

The router that "just works" - Handle 90% of routing use cases with zero complexity.

🚀 Why Route?

TL;DR: If you want routing that works without thinking about it, Route is for you. If you need complex routing features, use Vue Router, Angular Router, or other framework-specific routers instead.

The Problem

Most routing libraries are either:

• Over-engineered (40KB+ bundles for simple routing)
• Framework-specific (tied to Vue/Angular/other frameworks)
• Abandoned (last updated 2019-2021)
• Complex (require hours of learning)

Route's Solution

• 3.6KB gzipped (vs 31KB-415KB alternatives)
• Zero dependencies
• 5-minute setup
• Works everywhere (vanilla JS, any framework)
• Pure vanilla JavaScript (no framework dependencies)
• Actively maintained (2025)

✨ Features

Core Features

• ✅ Static routes (/about, /contact)
• ✅ Dynamic routes (/users/:id, /posts/:slug)
• ✅ Nested routes (/admin/users, /admin/settings)
• ✅ Auto component loading (dynamic imports)
• ✅ Browser history (clean URLs, back/forward)
• ✅ 404 handling (graceful fallbacks)
• ✅ Direct DOM node support (no render methods required)

Advanced Features

• 🔍 SEO Support (meta tags, Open Graph, structured data)
• 🌐 ES3 Compatibility (IE8+ support)
• 📦 Build Tool Support (Vite, Webpack, Rollup, esbuild, Parcel, Snowpack)
• 🧪 Comprehensive Testing (167 tests)
• ⚡ Server-Side Rendering (SSR) - Full HTML rendering for SEO and performance

📦 Installation

npm install @kirkelliott/route

🎯 Quick Start

3 lines of code:

import Route from '@kirkelliott/route';

const router = new Route({
  routes: { '/': Home, '/about': About }
});

router.setContainer(document.getElementById('app'));

That's it! Your app now has working routing with clean URLs, browser history, and auto component loading.

🚀 Component Types

Route supports multiple component types for maximum flexibility. No render methods required!

Functions Returning DOM Elements

const HomeComponent = (params) => {
  const div = document.createElement('div');
  div.innerHTML = '<h1>Home Page</h1>';
  return div;
};

const router = new Route({
  routes: { '/': HomeComponent }
});

Classes Returning DOM Elements Directly

class AboutComponent {
  constructor() {
    const div = document.createElement('div');
    div.innerHTML = '<h1>About Page</h1>';
    return div;
  }
}

const router = new Route({
  routes: { '/about': AboutComponent }
});

Functions Returning HTML Strings

const ContactComponent = (params) => {
  return '<h1>Contact Page</h1><p>Get in touch!</p>';
};

const router = new Route({
  routes: { '/contact': ContactComponent }
});

String Components

const router = new Route({
  routes: { '/help': '<h1>Help Page</h1><p>Need assistance?</p>' }
});

Dynamic Imports

const router = new Route({
  routes: { 
    '/': './components/Home.js',
    '/about': './components/About.js'
  }
});

🔍 SEO Support

Route includes dead simple SEO capabilities that solve the major shortcoming of client-side routers:

class ProductComponent {
  // Static SEO data
  seo = {
    title: "Product Page",
    meta: {
      description: "Amazing product with great features",
      keywords: "product, amazing, features"
    },
    og: {
      title: "Product Page",
      description: "Amazing product with great features",
      image: "https://example.com/product.jpg"
    },
    twitter: {
      card: "summary_large_image",
      title: "Product Page",
      description: "Amazing product with great features"
    },
    structuredData: {
      "@context": "https://schema.org",
      "@type": "Product",
      "name": "Amazing Product",
      "description": "Amazing product with great features"
    }
  };

  render(params) {
    return `<div>
      <h1>Product: ${params.id}</h1>
      <p>This is an amazing product!</p>
    </div>`;
  }
}

Features:

• ✅ Auto meta tag updates (title, description, keywords)
• ✅ Open Graph support (Facebook, LinkedIn sharing)
• ✅ Twitter Card support (Twitter sharing)
• ✅ Structured data (JSON-LD for search engines)
• ✅ Dynamic SEO (based on route parameters)
• ✅ API integration (fetch SEO data from your backend)

📦 Build Tool Support

Route works with every major build tool:

Vite

// vite.config.js
export default {
  build: {
    rollupOptions: {
      external: ['@kirkelliott/route']
    }
  }
}

Webpack

// webpack.config.js
module.exports = {
  externals: {
    '@kirkelliott/route': 'Route'
  }
}

Rollup

// rollup.config.js
export default {
  external: ['@kirkelliott/route']
}

esbuild

// esbuild.config.js
require('esbuild').build({
  entryPoints: ['src/main.js'],
  bundle: true,
  external: ['@kirkelliott/route']
})

Parcel

// .parcelrc
{
  "extends": "@parcel/config-default",
  "reporters": ["@parcel/reporter-cli"]
}

Snowpack

// snowpack.config.js
export default {
  external: ['@kirkelliott/route']
}

🧪 Testing

Route includes comprehensive testing with 167 tests:

# Run all tests
npm test

# Run specific test suites
npm test -- test/basic.test.js
npm test -- test/navigation.test.js
npm test -- test/component-loading.test.js

# Run with coverage
npm run test:coverage

# Run specific test files
npm test -- test/component-loading.test.js

Test Coverage:

• ✅ Unit tests (Jest)
• ✅ Component loading tests (167 tests)
• ✅ Browser compatibility (IE8+)
• ✅ Build tool compatibility (Vite, Webpack, Rollup, etc.)
• ✅ Performance tests (bundle size, load time)

📚 API Reference

Route Constructor

const router = new Route(config, options);

Config Options:

• routes (Object): Route definitions
• basePath (String): Base path for all routes (default: '')
• mode (String): History mode ('history' or 'hash')
• fallback (Component): 404 fallback component
• seo (Object): Global SEO configuration

Core Methods

// Set container element
router.setContainer(container);

// Navigate to route
router.navigate('/about');

// Get current parameters
const params = router.getParams();

// Get current path
const path = router.getCurrentPath();

// Get all routes
const routes = router.getRoutes();

SEO Methods

// Update SEO data
router.updateSEO({
  title: 'New Page Title',
  meta: { description: 'Page description' }
});

// Get current SEO data
const seo = router.getCurrentSEO();

🌐 Browser Support

Route supports all modern browsers and IE8+:

• ✅ Chrome (latest)
• ✅ Firefox (latest)
• ✅ Safari (latest)
• ✅ Edge (latest)
• ✅ IE8+ (with polyfills)

📦 Bundle Size

Route is incredibly lightweight:

• 3.6KB gzipped (vs 31KB-415KB alternatives)
• Zero dependencies
• Tree-shakeable
• ES3 compatible

🚀 Performance

Route is blazingly fast:

• < 1ms route matching
• < 5ms component rendering
• Zero runtime overhead
• Lazy loading support

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT License - see LICENSE for details.

🆘 Support

• Documentation: https://github.com/dmvjs/route
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Route - The router that "just works" 🚀