npm package: @kirkelliott/route
Description: Dead simple routing for JavaScript applications
Author: Kirk Elliott
Latest version: 1.1.13

# Route - Dead Simple Routing

[![Tests](https://github.com/dmvjs/route/workflows/Tests/badge.svg)](https://github.com/dmvjs/route/actions)
[![npm version](https://img.shields.io/npm/v/@kirkelliott/route.svg)](https://www.npmjs.com/package/@kirkelliott/route)
[![Bundle Size](https://img.shields.io/bundlephobia/min/@kirkelliott/route)](https://bundlephobia.com/result?p=@kirkelliott/route)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

**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

```bash
npm install @kirkelliott/route
```

## 🎯 Quick Start

**3 lines of code:**

```javascript
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**
```javascript
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**
```javascript
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**
```javascript
const ContactComponent = (params) => {
  return '<h1>Contact Page</h1><p>Get in touch!</p>';
};

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

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

### **Dynamic Imports**
```javascript
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:

```javascript
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**
```javascript
// vite.config.js
export default {
  build: {
    rollupOptions: {
      external: ['@kirkelliott/route']
    }
  }
}
```

### **Webpack**
```javascript
// webpack.config.js
module.exports = {
  externals: {
    '@kirkelliott/route': 'Route'
  }
}
```

### **Rollup**
```javascript
// rollup.config.js
export default {
  external: ['@kirkelliott/route']
}
```

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

### **Parcel**
```javascript
// .parcelrc
{
  "extends": "@parcel/config-default",
  "reporters": ["@parcel/reporter-cli"]
}
```

### **Snowpack**
```javascript
// snowpack.config.js
export default {
  external: ['@kirkelliott/route']
}
```

## 🧪 Testing

Route includes **comprehensive testing** with 167 tests:

```bash
# 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**
```javascript
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**
```javascript
// 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**
```javascript
// 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](CONTRIBUTING.md) for details.

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

## 🆘 Support

- **Documentation**: [https://github.com/dmvjs/route](https://github.com/dmvjs/route)
- **Issues**: [GitHub Issues](https://github.com/dmvjs/route/issues)
- **Discussions**: [GitHub Discussions](https://github.com/dmvjs/route/discussions)

---

**Route** - The router that "just works" 🚀