v1.2.0

Routing
in plain HTML.

A tiny Web Component router for HTML-first apps. Route by pathname or search query, lazy-load HTML/JS/TXT pages, nest route layouts, guard protected screens, and keep framework lock-in out of your navigation layer.

Get Startednpm i @beforesemicolon/router
5WEB COMPONENTS
0CONFIG
HTMLJS - TXT PAGES
html
<!-- index.html — zero JavaScript required -->
<nav>
    <page-link path="/" title="Home">Home</page-link>
    <page-link path="/todos" title="Todos">Todos</page-link>
    <page-link path="/contact" title="Contact">Contact</page-link>
</nav>

<page-route path="/">
    <h1>Welcome</h1>
</page-route>

<!-- lazy-load HTML, txt or JS files -->
<page-route path="/todos" src="./pages/todos.html"></page-route>
<page-route path="/contact" src="./pages/contact.js"></page-route>

<!-- redirect unknown paths -->
<page-redirect path="/404"></page-redirect>
// THE ECOSYSTEM

Built on Web Component & Markup.

Router is built on top of Web Component and Markup. Same engine, modular packages, zero lock-in.

Markup

@beforesemicolon/markup

The 9Kb reactive templating system that powers everything. Tagged templates, state, effects, repeat, suspense.

Read the Docs

Web Component

@beforesemicolon/web-component

A reactive layer over native Custom Elements — the foundation Router is built on. Props, state, scoped styles, lifecycles.

Read the Docs
// WHY THIS ROUTER

Routing that disappears into HTML.

Five web components, one central matcher, and a clean JS API for everything you can't express in markup.

Plug & play

Drop in two script tags and route with HTML. No build step, no router config, no JavaScript required.

Tiny & focused

A small surface area: five web components and a JS API. Built on Markup + Web Component, with zero extra deps.

Lazy-loaded pages

Point page-route at an HTML, txt or JS file. Modules load once, cache between visits, mount and unmount cleanly.

Nested & named routes

Children extend their parent's path. Use the name attribute for switch-like, mutually exclusive matching.

Search-query routing

page-route-query renders content based on ?key=value — tabs, filters and modals without a single line of state.

Smart redirects

page-redirect targets unknown paths only — or always, scoped to its parent route. Perfect for 404s and defaults.

One match, one render

A central matcher resolves each navigation once. Guards run once. Subscribers only fire when they're relevant.

Cached remounts

Inactive routes are detached from the DOM but kept warm. Coming back is an instant remount, not a rebuild.

Works with any builder

Vite, Webpack, esbuild, plain HTML, or a CDN script tag — it's just web components, so it slots in anywhere.

// SEE IT IN ACTION

Five examples. Infinite sitemaps.

Compose page-route, page-link, page-route-query, page-redirect, page-data and the small JS API around them.

EXAMPLE 01
Nested routes & params
html
<!-- nested routes — child paths extend the parent -->
<page-route path="/projects" exact="false">
    <h1>Projects</h1>

    <!-- /projects -->
    <page-route src="./pages/projects-list.js"></page-route>

    <!-- /projects/:projectId — pathname params -->
    <page-route path="/:projectId" src="./pages/project.js">
        <div slot="loading">Loading project...</div>
        <div slot="fallback">Could not load this project.</div>
    </page-route>

    <!-- only redirects unknown CHILD routes of /projects -->
    <page-redirect path="/projects/not-found"></page-redirect>
</page-route>
EXAMPLE 02
Search-query routes
html
<!-- routing by ?tab= — perfect for tabs, filters, modals -->
<div class="tabs">
    <div class="tab-header">
        <page-link search="tab=one">Tab 1</page-link>
        <page-link search="tab=two">Tab 2</page-link>
    </div>

    <div class="tab-content">
        <page-route-query key="tab" value="one">
            Tab One content
        </page-route-query>

        <page-route-query key="tab" value="two">
            Tab Two content
        </page-route-query>
    </div>
</div>
EXAMPLE 03
Page metadata
html
<!-- render location metadata: payload, params and search queries -->
<page-link path="/users/42" title="User profile" payload='{"role": "admin"}'
    >Open user 42</page-link
>

<page-route path="/users/:userId">
    <h1>User <page-data param="userId">unknown</page-data></h1>

    <!-- payload data passed via the link -->
    <p>Role: <page-data key="role">guest</page-data></p>

    <!-- current search query value (following router API search-param attribute) -->
    <p>Tab: <page-data search-param="tab">overview</page-data></p>
</page-route>
EXAMPLE 04
Protected routes
javascript
import {
    registerGlobalGuard,
    registerRouteGuard,
} from '@beforesemicolon/router'

registerGlobalGuard((pathname) => {
    const publicPages = ['/', '/login', '/pricing', '/404']

    if (!publicPages.includes(pathname) && !auth.isSignedIn()) {
        return '/login'
    }

    return true
})

registerRouteGuard('/admin/:section', async () => {
    return (await auth.hasRole('admin')) || '/unauthorized'
})
EXAMPLE 05
Bundler-friendly pages
javascript
import { registerRouteModules } from '@beforesemicolon/router'

registerRouteModules(
    import.meta.glob('./pages/**/*.{js,html,txt}', {
        eager: false,
    })
)
html
<page-route path="/" src="./pages/home.js"></page-route>
<page-route path="/docs" src="./pages/docs.html"></page-route>
<page-route path="/legal" src="./pages/legal.txt"></page-route>
// quick start

Install in seconds.

Choose your preferred installation method. Works everywhere JavaScript runs.

<script src="https://unpkg.com/@beforesemicolon/router/dist/client.js"></script>
npm install @beforesemicolon/router
yarn add @beforesemicolon/router
pnpm add @beforesemicolon/router

Build single and multi-page apps, your way.

Combine the simplicity of vanilla Web Standards with the power of declarative routing.

Get StartedRead the Docs