ShadowJS Router

Declarative client-side routing for ShadowJS applications with support for nested routes, layouts, transitions, and scroll restoration.

✨ Features

🎯 Declarative Routing: Define routes using JSX components
🧩 Nested Routes: Support for nested layouts and route hierarchies
🎭 Transitions: Built-in route transition animations
📜 Scroll Restoration: Automatic scroll position management
🔗 Programmatic Navigation: Navigate programmatically with full control
🎨 Layout Support: Shared layouts for multiple routes
📱 Hash & History Modes: Choose between hash and history-based routing
🔍 Route Parameters: Dynamic route segments with type safety

📦 Installation

The ShadowJS Router requires @shadow-js/core as a peer dependency:

# Install both packages together
npm install @shadow-js/router @shadow-js/core

# Or if you already have @shadow-js/core installed
npm install @shadow-js/router

Important: This router is specifically designed for ShadowJS applications and requires @shadow-js/core to function properly. The router imports directly from @shadow-js/core and will not work without it.

Development Setup

For development and testing, you can use the development configuration:

# Copy the development package.json
cp package.json.dev package.json

# Install dependencies (includes @shadow-js/core)
npm install

Peer Dependency Architecture

This package uses a peer dependency approach for several reasons:

Framework Integration: Tightly coupled with ShadowJS reactive system
Bundle Size: Avoids bundling framework code that consumers already have
Version Alignment: Ensures consumers use compatible versions
Tree Shaking: Allows better optimization in consumer applications

🚀 Quick Start

Basic Routing

import { Router, Route, A, useLocation } from "@shadow-js/router";

function Navigation() {
  return (
    <nav>
      <A href="/">Home</A>
      <A href="/about">About</A>
      <A href="/contact">Contact</A>
    </nav>
  );
}

function Home() {
  const location = useLocation();
  return (
    <div>
      <h1>Home</h1>
      <p>Current path: {() => location.pathname}</p>
    </div>
  );
}

function About() {
  return <h1>About Us</h1>;
}

function Contact() {
  return <h1>Contact Us</h1>;
}

function NotFound() {
  return <h1>404 - Page Not Found</h1>;
}

function App() {
  return (
    <Router notFound={NotFound}>
      <Navigation />
      <Route path="/" component={Home} />
      <Route path="/about" component={About} />
      <Route path="/contact" component={Contact} />
    </Router>
  );
}

Dynamic Routes with Parameters

import { useParams } from "@shadow-js/router";

function UserProfile() {
  const params = useParams();
  return (
    <div>
      <h1>User Profile</h1>
      <p>User ID: {() => params().id}</p>
    </div>
  );
}

function App() {
  return (
    <Router>
      <Route path="/users/:id" component={UserProfile} />
    </Router>
  );
}

🎯 Core Concepts

Route Configuration

Routes can be configured in two ways:

1. Declarative Routes (JSX)

<Router>
  <Route path="/" component={Home} />
  <Route path="/about" component={About} />
  <Route path="/users/:id" component={UserProfile} />
</Router>

2. Programmatic Routes (Objects)

const routes = [
  { path: "/", component: Home },
  { path: "/about", component: About },
  { path: "/users/:id", component: UserProfile },
];

<Router routes={routes} />;

Route Matching

ShadowJS Router uses a sophisticated matching algorithm:

Exact Matching: /users matches only /users
Parameter Matching: /users/:id matches /users/123
Wildcard Matching: /users/* matches /users/123/posts
Optional Parameters: /users/:id? matches /users and /users/123

Nested Routes and Layouts

function DashboardLayout({ children }) {
  return (
    <div className="dashboard">
      <nav>
        <A href="/dashboard">Overview</A>
        <A href="/dashboard/users">Users</A>
        <A href="/dashboard/settings">Settings</A>
      </nav>
      <main>{children}</main>
    </div>
  );
}

function DashboardOverview() {
  return <h2>Dashboard Overview</h2>;
}

function App() {
  return (
    <Router>
      <Route path="/dashboard" layout={DashboardLayout}>
        <Route path="/" component={DashboardOverview} />
        <Route path="/users" component={DashboardUsers} />
        <Route path="/settings" component={DashboardSettings} />
      </Route>
    </Router>
  );
}

📚 API Reference

Components

`<Router>`

The main router component that manages client-side routing for your application.

Props:

routes?: RouteConfig[] - Array of route configurations (alternative to children)
children?: any - Child routes when using JSX syntax
transition?: Transition - Default transition for all routes
notFound?: ComponentType - Component to render for unmatched routes
mode?: "history" | "hash" - URL handling mode (default: "history")
scroll?: ScrollBehavior - Scroll restoration behavior

Examples:

// JSX syntax
<Router notFound={NotFound} mode="history">
  <Route path="/" component={Home} />
  <Route path="/about" component={About} />
</Router>;

// Object syntax
const routes = [
  { path: "/", component: Home },
  { path: "/about", component: About },
];

<Router routes={routes} />;

`<Route>`

Defines a route with its path and component.

Props:

path: string - Route path pattern
component?: ComponentType - Component to render for this route
layout?: ComponentType - Layout component wrapping this route
children?: RouteConfig[] - Nested routes
redirect?: string | Function - Redirect path or function
transition?: Transition - Route-specific transition

Examples:

// Basic route
<Route path="/home" component={Home} />

// Route with layout
<Route path="/dashboard" layout={DashboardLayout}>
  <Route path="/" component={Overview} />
  <Route path="/users" component={Users} />
</Route>

// Route with redirect
<Route path="/old-path" redirect="/new-path" />

// Dynamic route
<Route path="/users/:id" component={UserProfile} />

`<A>`

Enhanced anchor tag for client-side navigation with automatic active states.

Props:

href: string - Navigation target
replace?: boolean - Replace current history entry
state?: any - State to pass to the new route
className?: string | Function - CSS class (can be reactive)
All standard <a> tag props

Examples:

<A href="/home">Home</A>
<A href="/users" className={() => (location.pathname === "/users" ? "active" : "")}>
  Users
</A>

`<Redirect>`

Programmatically redirects to another route.

Props:

to: string - Redirect target path

Examples:

<Redirect to="/login" />

Hooks

`useLocation()`

Returns the current location object with reactive properties.

Returns: Store<Location>

Location Properties:

pathname: string - Current path
search: string - Query string
hash: string - Hash fragment
state: any - Navigation state

Examples:

function CurrentPage() {
  const location = useLocation();

  return (
    <div>
      <p>Current path: {location.pathname}</p>
      <p>Search: {location.search}</p>
      <p>Hash: {location.hash}</p>
    </div>
  );
}

`useParams<T>()`

Returns route parameters extracted from the current URL.

Returns: Store<T | undefined>

Examples:

function UserProfile() {
  const params = useParams<{ id: string }>();

  return <div>User ID: {params().id}</div>;
}

`useSearchParams()`

Manages URL search parameters with reactive updates.

Returns: [Store<URLSearchParams>, SetterFunction]

Examples:

function SearchComponent() {
  const [searchParams, setSearchParams] = useSearchParams();

  const updateSearch = (query: string) => {
    setSearchParams({ q: query, page: "1" });
  };

  return (
    <input
      value={searchParams().get("q") || ""}
      onInput={(e) => updateSearch(e.target.value)}
    />
  );
}

Functions

`navigate(to, options?)`

Programmatically navigate to a new route.

Parameters:

to: string - Target path
options?: NavigateOptions - Navigation options

NavigateOptions:

replace?: boolean - Replace current history entry
state?: any - State to pass to the new route

Examples:

// Basic navigation
navigate("/dashboard");

// Replace current history entry
navigate("/login", { replace: true });

// Pass state
navigate("/checkout", { state: { fromCart: true } });

`redirect(to)`

Redirect to a new route (equivalent to navigate with replace: true).

Parameters:

to: string - Redirect target

Examples:

redirect("/login");

Types

`RouteConfig<P, T>`

Configuration object for defining routes programmatically.

Properties:

path: P - Route path pattern
component?: ComponentType - Route component
layout?: ComponentType - Layout component
children?: RouteConfig[] - Nested routes
redirect?: string | Function - Redirect configuration
transition?: Transition - Route transition

`PathParams<P>`

Type-safe route parameters extracted from path patterns.

Examples:

// For path "/users/:id/posts/:postId"
// PathParams = { id: string, postId: string }

`NavigateOptions<T>`

Options for programmatic navigation.

Properties:

replace?: boolean - Replace history entry
state?: T - Navigation state

`Transition`

Animation effect for route changes.

Types:

"none" - No transition
"fade" - Fade transition
CustomTransition - Custom transition function

🔧 Advanced Usage

Programmatic Navigation

import { navigate, redirect } from "@shadow-js/router";

function LoginForm() {
  const [isLoggedIn, setIsLoggedIn] = useStore(false);

  const handleLogin = () => {
    setIsLoggedIn(true);
    // Navigate after successful login
    navigate("/dashboard", { replace: true });
  };

  const handleLogout = () => {
    setIsLoggedIn(false);
    // Redirect to home
    redirect("/");
  };

  return (
    <div>
      <button onClick={handleLogin}>Login</button>
      <button onClick={handleLogout}>Logout</button>
    </div>
  );
}

Route Transitions

<Router transition="fade">
  <Route path="/" component={Home} />
  <Route path="/about" component={About} transition="slide" />
</Router>

Available transitions: "fade", "slide", "scale", "none"

Custom Scroll Behavior

<Router
  scroll={(context) => {
    if (context.action === "PUSH") {
      window.scrollTo(0, 0); // Scroll to top on navigation
    } else if (context.action === "POP") {
      // Restore scroll on browser back/forward
      // Default behavior handles this automatically
    }
  }}
>
  {/* routes */}
</Router>

Route Guards and Redirects

function ProtectedRoute({ component: Component }) {
  const [isAuthenticated, setIsAuthenticated] = useStore(false);

  return (
    <Show when={() => isAuthenticated()} fallback={<Redirect to="/login" />}>
      <Component />
    </Show>
  );
}

function App() {
  return (
    <Router>
      <Route
        path="/dashboard"
        component={() => <ProtectedRoute component={Dashboard} />}
      />
    </Router>
  );
}

Query Parameters

import { useSearchParams } from "@shadow-js/router";

function ProductList() {
  const [searchParams, setSearchParams] = useSearchParams();

  const category = () => searchParams().get("category") || "all";
  const sort = () => searchParams().get("sort") || "name";

  const updateFilters = (newFilters) => {
    setSearchParams({
      ...Object.fromEntries(searchParams().entries()),
      ...newFilters,
    });
  };

  return (
    <div>
      <select
        value={() => category()}
        onChange={(e) => updateFilters({ category: e.target.value })}
      >
        <option value="all">All Categories</option>
        <option value="electronics">Electronics</option>
        <option value="books">Books</option>
      </select>
    </div>
  );
}

🏗️ Router Architecture

Route Compilation

The router compiles route configurations into an optimized matching tree:

Parse route patterns into regex and parameter names
Build matching tree for efficient route resolution
Cache compiled routes for performance

Navigation Flow

URL Change Detection: Listen to popstate and hashchange events
Route Matching: Find matching route for current path
Component Resolution: Resolve component and layout hierarchy
Transition Handling: Apply route transitions
Scroll Management: Handle scroll restoration
Render: Update DOM with new route content

State Management

The router manages several reactive states:

Current location: pathname, search, hash
Current route match: matched route and parameters
Navigation history: for back/forward functionality
Scroll positions: for restoration

🔌 Integration

With ShadowJS

import { useStore } from "@shadow-js/core";
import { Router, Route, useLocation } from "@shadow-js/router";

function App() {
  const [user, setUser] = useStore(null);

  return (
    <Router>
      <Route path="/" component={Home} />
      <Route path="/profile" component={Profile} />
    </Router>
  );
}

Custom History Implementation

// For server-side rendering or custom history management
const customHistory = {
  push: (path) => {
    /* custom push logic */
  },
  replace: (path) => {
    /* custom replace logic */
  },
  go: (delta) => {
    /* custom go logic */
  },
};

// Pass to router
<Router history={customHistory}>{/* routes */}</Router>;

🎨 Styling Routes

Routes can have their own styling:

// Route-specific styles
<Route path="/dashboard" component={Dashboard} className="dashboard-route" />;

// Conditional styling based on active route
function Navigation() {
  const location = useLocation();

  return (
    <nav>
      <A href="/" className={() => (location.pathname === "/" ? "active" : "")}>
        Home
      </A>
      <A
        href="/about"
        className={() => (location.pathname === "/about" ? "active" : "")}
      >
        About
      </A>
    </nav>
  );
}

🐛 Error Handling

Route Errors

function App() {
  return (
    <Router
      notFound={() => <div>Custom 404 Page</div>}
      onError={(error) => {
        console.error("Route error:", error);
        // Handle route errors
      }}
    >
      {/* routes */}
    </Router>
  );
}

Navigation Errors

import { navigate } from "@shadow-js/router";

try {
  await navigate("/protected-route");
} catch (error) {
  if (error.code === "UNAUTHORIZED") {
    navigate("/login");
  }
}

📊 Performance

Route Preloading

// Preload routes on hover for better UX
function Link({ href, children }) {
  const [isPreloading, setIsPreloading] = useStore(false);

  return (
    <A
      href={href}
      onMouseEnter={() => {
        setIsPreloading(true);
        // Preload route component
        import(`./pages${href}.js`);
      }}
      className={() => (isPreloading() ? "preloading" : "")}
    >
      {children}
    </A>
  );
}

Route Memoization

Routes automatically memoize components to prevent unnecessary re-renders.

🧪 Testing

import { render } from "@shadow-js/core";
import { Router, Route } from "@shadow-js/router";

describe("Routing", () => {
  test("renders correct component for route", () => {
    const container = document.createElement("div");

    render(
      <Router>
        <Route path="/test" component={() => <div>Test Component</div>} />
      </Router>,
      container
    );

    // Navigate to test route
    window.history.pushState({}, "", "/test");

    expect(container.innerHTML).toContain("Test Component");
  });
});

📚 Examples

See the examples documentation for:

Basic routing patterns
Nested routes and layouts
Dynamic routing
Protected routes
Search and query parameters

🤝 Contributing

We welcome contributions! See the Contributing Guide for details.

📄 License

MIT License - see LICENSE for details.

📞 Support

Documentation: Router API
Examples: Routing Examples
Issues: GitHub Issues
Discussions: GitHub Discussions

Built with ❤️ for the ShadowJS ecosystem.

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.changeset		.changeset
.github		.github
src		src
.editorconfig		.editorconfig
.gitignore		.gitignore
.nvmrc		.nvmrc
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
DEVELOPMENT.md		DEVELOPMENT.md
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
package.json		package.json
package.json.dev		package.json.dev
tsconfig.base.json		tsconfig.base.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

License

shadowjs-dev/router

Folders and files

Latest commit

History

Repository files navigation

ShadowJS Router

✨ Features

📦 Installation

Development Setup

Peer Dependency Architecture

🚀 Quick Start

Basic Routing

Dynamic Routes with Parameters

🎯 Core Concepts

Route Configuration

1. Declarative Routes (JSX)

2. Programmatic Routes (Objects)

Route Matching

Nested Routes and Layouts

📚 API Reference

Components

<Router>

<Route>

<A>

<Redirect>

Hooks

useLocation()

useParams<T>()

useSearchParams()

Functions

navigate(to, options?)

redirect(to)

Types

RouteConfig<P, T>

PathParams<P>

NavigateOptions<T>

Transition

🔧 Advanced Usage

Programmatic Navigation

Route Transitions

Custom Scroll Behavior

Route Guards and Redirects

Query Parameters

🏗️ Router Architecture

Route Compilation

Navigation Flow

State Management

🔌 Integration

With ShadowJS

Custom History Implementation

🎨 Styling Routes

🐛 Error Handling

Route Errors

Navigation Errors

📊 Performance

Route Preloading

Route Memoization

🧪 Testing

📚 Examples

🤝 Contributing

📄 License

📞 Support

About

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

`<Router>`

`<Route>`

`<A>`

`<Redirect>`

`useLocation()`

`useParams<T>()`

`useSearchParams()`

`navigate(to, options?)`

`redirect(to)`

`RouteConfig<P, T>`

`PathParams<P>`

`NavigateOptions<T>`

`Transition`

Packages