🕹️ intentx-react-router

LIVE EXAMPLE

Intent‑based navigation layer for React applications.

Built on top of React Router and designed to work nicely with event‑driven architectures like eventbus-z.

Navigate by intent, not by URL.

Why intentx-react-router?

Traditional routing:

navigate("/users/42/edit")

Intent Router:

navigateIntent("edit-user", 42)

Benefits:

• 🧠 Intent‑driven navigation
• 🔗 URL structure fully decoupled from UI
• 🔧 Easy URL refactor
• 🧩 Micro‑frontend friendly
• 📡 Event‑driven navigation support
• 🪶 Lightweight core (~200 lines)

Installation

npm install intentx-react-router react-router@^7 react-router-dom@^7

Recommended Versions

• react: >=18
• react-dom: >=18
• react-router: >=7
• react-router-dom: >=7

Basic Setup

1. Define intents

import { createIntentRouter, NavigateFn } from "intentx-react-router"

createIntentRouter({
  "view-user": "/users/:userId/name/:page",
  "edit-user": "/users/:userId/edit",
  "checkout": "/checkout"
})

// Bind navigate in App
export function bindRouterNavigate(navigate: NavigateFn) {
  bindNavigate(navigate);
}

2. Bind React Router navigate

import React from "react"
import { useNavigate } from "react-router-dom"
import { bindNavigate } from "intentx-react-router"

export function RouterBinder() {
  const navigate = useNavigate();

  React.useEffect(() => {
    // require
    bindRouterNavigate(navigate);
  }, [navigate]);

  return null;
}

3. Use in App

import React from "react"
import { BrowserRouter, Routes } from "react-router-dom"
import { IntentLink, IntentRoute } from "intentx-react-router"
import { RouterBinder } from "./router"

import { UserPage } from "./pages/UserPage"
import { EditUserPage } from "./pages/EditUserPage"
import { CheckoutPage } from "./pages/CheckoutPage"

export default function App() {
  return (
    <BrowserRouter>
      <RouterBinder />

      <nav style={{ marginBottom: 20 }}>
        <IntentLink intent="view-user" params={[1, 2]}>View User</IntentLink>{" "}
        | <IntentLink intent="edit-user" params={1}>Edit User</IntentLink>{" "}
        | <IntentLink intent="checkout">Checkout</IntentLink>
      </nav>

      <Routes>
        <IntentRoute intent="view-user" component={UserPage} />
        <IntentRoute intent="edit-user" component={EditUserPage} />
        <IntentRoute intent="checkout" component={CheckoutPage} />
      </Routes>
    </BrowserRouter>
  )
}

Navigation

Object params

navigateIntent("view-user", {
  userId: 1,
  page: 2
})

Result:

/users/1/name/2

Array params

navigateIntent("view-user", [1,2])

Params automatically map to:

:userId
:page

Single param shortcut

navigateIntent("edit-user", 1)

Result:

/users/1/edit

Query params

Intent navigation also supports query parameters.

navigateIntent("view-user", {
  userId: 1,
  page: 2
}, {
  tab: "activity",
  filter: "recent"
})

/users/1/name/2?tab=activity&filter=recent

Query arrays are also supported:

navigateIntent("view-user", [1,2], {
  tags: ["admin", "vip"]
})

Result:

/users/1/name/2?tags=admin&tags=vip

Advanced Navigation

options, fallback, microFE

import React from "react"
import { useNavigateIntent, setFallbackPath, setSharedBus } from "intentx-react-router"
import { createEventBus } from "eventbus-z"

// Micro-frontend shared bus
const externalBus = createEventBus()
setSharedBus(externalBus)

setFallbackPath("/not-found")

function Dashboard() {
  const navigateIntent = useNavigateIntent()

  const handleCheckout = () => {
    navigateIntent("checkout", undefined, { ref: "dashboard" }, { replace: true, scrollTop: true })
  }

  return (
    <div>
      <h1>Dashboard</h1>
      <button onClick={handleCheckout}>Go to Checkout</button>
      <button
        onClick={() => {
          navigateIntent("unknown-intent")
        }}
      >
        Unknown Intent
      </button>
    </div>
  )
}

React Helpers

useNavigateIntent

import { useNavigateIntent } from "intentx-react-router"

function Button() {
  const navigateIntent = useNavigateIntent()

  return (
    <button onClick={() => navigateIntent("checkout")}>
      Checkout
    </button>
  )
}

IntentLink

import { IntentLink } from "intentx-react-router"

<IntentLink intent="view-user" params={[1,2]} query={{ tab: "profile" }}>
  Open User
</IntentLink>

Equivalent to:

<Link to="/users/1/name/2?tab=profile" />

useIntentRouter

Reads intent + params from URL.

import { useIntentRouter } from "intentx-react-router"

function Page() {
  const { intent, params } = useIntentRouter()

  console.log(intent)
  console.log(params)

  return null
}

Example result:

{
  intent: "view-user",
  params: {
    userId: "1",
    page: "2"
  }
}

IntentRoute

Intent‑aware route wrapper.

import { IntentRoute } from "intentx-react-router"

<IntentRoute
  intent="view-user"
  component={UserPage}
/>

Guards

Global guard:

addIntentGuard((intent, params) => {

  if (!isLoggedIn && intent === "checkout") {
    return "/login"
  }

})

Per‑intent guard:

addIntentGuardFor("checkout", () => {

  if (!cartReady) {
    return "/cart"
  }

})

Preload

Preload logic before navigation.

addIntentPreload("checkout", () => {
  fetchCart()
})

Manual preload:

preloadIntent("checkout")

Reverse Routing

Generate path manually.

generatePathFromIntent("view-user", [1,2], {
  tab: "activity"
})

Result:

/users/1/name/2?tab=activity

Resolve Intent From URL

resolveIntentFromUrl("/users/1/name/2?tab=activity")

Result:

{
  intent: "view-user",
  params: {
    userId: "1",
    page: "2"
  },
  query: {
    tab: "activity"
  }
}

Event-Driven Navigation

Example

import { createEventBus } from "eventbus-z"
import { navigateIntent } from "intentx-react-router"

const bus = createEventBus()

// Somewhere in your app
bus.$on("CHECKOUT_REQUESTED", (userId) => {
  navigateIntent("checkout", { userId })
})

Trigger navigation from anywhere:

bus.$emit("CHECKOUT_REQUESTED", 42)

Result:

/checkout?userId=42

Why this is powerful

• Navigation becomes decoupled from UI components.

Instead of:

<button onClick={() => navigate("/checkout")} />

You can emit a domain event:

bus.$emit("CHECKOUT_REQUESTED")

This allows:

• UI-agnostic navigation
• better architecture in large apps
• seamless micro-frontend communication

Comparison

| Criteria | intent-router | React Router | |-------------------------|---------------|--------------| | Intent-based navigation | ✅ | ❌ | | URL refactor safety | ✅ | ⚠️ | | Event-driven navigation | ✅ | ❌ | | Micro-frontend friendly | ✅ | ⚠️ | | Reverse routing | ✅ | ❌ | | Type-safe intent params | ✅ | ⚠️ | | Query support | ✅ | ⚠️ |

Architecture

Component
    ↓
navigateIntent()
    ↓
eventbus-z
    ↓
Intent Router
    ↓
React Router navigate()
    ↓
URL

License

MIT