Router

[kyeotic]

There is already a crank-router package but it unmaintained and is missing features like query and hash change integration. I think this is a missing piece in the crank ecosystem.

Is there an option or plan that I am missing?

If not, I maintain a small react routing library based entirely on react hooks, and I think the API would be a pretty good fit for crank (using context utilities). I'd be happy to port it to crank, and I have a project I could dogfood with.

[brainkim]

You might not like the answer, but the direction I’m headed is @b9g/router. The key points for a router (in my mind) are:

• Isomorphic/universal definition: routes should be defined once and somehow shared
• Context variables are unnecessary: The History and Location APIs are shared globals, so to wrap the root App in a Provider component which provides history utilities is to me, unnecessary. Just use globals.
• Preserve page state: The primary reason for a client-side router is to do fancy things like a media player which persists in the navbar or infinite scroll. The full solution should likely figure this out
• Route components: I am willing to entertain component-based router APIs, but I personally prefer flat enumeration of route patterns like my first love Django.
• NO FILESYSTEM-BASED ROUTING: Under no circumstances will I ever bless a filesystem-based router. That stuff is 2010s madness
• AVOID LINK WRAPPERS: <a> tags are supremely composable and flexible things.

In my mind this might turn into a client-side runtime library which attaches an event listener to the root, and swaps in elements.

With all this said, we live in a nominally free country, and this is open source, so you’re free to do what you want. Raviger seems to be tastefully designed 😙

https://github.com/bikeshaving/shovel/tree/main/packages/router

[kyeotic]

That's a very reasonable answer, though I have some disagreements

• Isomorphic: 🟢 This makes sense for SSR + CSR
• Context Variables: 🔴 History and Location are globals, but route definitions are not. Apps can live in a multi-app space (enterprises love dynamically loaded applets). I also like supported nested routers that don't need to be aware of their parents, and globals break this.
• Preserve Page State: 🟡 This is valuable, but I wouldn't say its the primary reason (at least not mine). I want page navigation to happen clientside when it makes sense, and a client-side router is required for this.
• Route Components: 🟢 I like both options. Flat enumeration is default, components are available for nesting
• FS Routing: 🟢🟢🟢🟢🟢🟢🟢🟢🟢🟢🟢🟢🟢🟢🟢🟢🟢 I F**** hate FS based routes. Why is everyone doing this?!
• Avoid Link Wrappers: 🟡 I haven't dived deep into how possible everything is with crank and pure <a> tags, but my suspicion is they will lack ergonomics for things like active classes, internal-vs-external styling (e.g. automatic icons), and a few other cases.

I'd like to help with the official solution, as long as its intended to cover my use cases.

I am a little confused on how @b9g/router will work client-side. Its API seems tailored to request mapping, not url-component mapping. Without a route component Im not sure how the page updates will be handled. Are you picturing the same API makes render calls that overwrite a DOM target?

[brainkim]

Context Variables: Fair point about multi-app spaces and nested routers. I'm not saying there should be zero context; route definitions obviously need to live somewhere. What I'm pushing back on is the React Router pattern where you wrap your entire app in <BrowserRouter> just to provide history/location down the tree. Those are already globals. But you're right that nested routers that don't know about their parents is a valid use case, and router.mount() already supports this on the server side, a subrouter doesn't know its mount path. I'd want to preserve that property client-side too.

Preserve Page State: Yeah, I overstated this. Client-side navigation is the primary motivation. You want instant transitions without a full page load. State preservation is a nice bonus you get for free once you have that.

Link Wrappers: I'm not dogmatic about this. If <a> tags need a thin wrapper for active class detection or internal-vs-external distinction, that's fine. What I want to avoid is a <Link> component that reimplements half of <a> and breaks when you try to do normal anchor things with it.

A utility that enhances <a> rather than replacing it. I’ve had dreams of just adding a top-level listener on the document and using event bubbling to intercept all <a> tag clicks. Something like https://github.com/youtube/spfjs which I thought had really interesting ideas. This would give us link wrapping for free.

Client-side usage: Good question. The route definitions are portable: you define patterns once in the Router and they work on both sides. The client doesn't need the Request -> Response handlers though. The idea is you'd be able to use the router with handlers omitted, just calling something like router.match(url) to get back the matched route name/params. Then a small client-side runtime listens for navigation events (click interception on <a> tags, popstate) and calls router.match() to figure out what to render. The actual DOM update would go through Crank's renderer.render() — the router just tells you what matched, Crank handles the rendering.

So it's not the router making render calls directly. It's more like: navigation event -> router.match(url) -> your app decides what component to render -> renderer.render(<App route={match} />). The router stays a pure pattern matcher, and the glue between routing and rendering is a thin layer that could be a Crank context utility or just a few lines in your entry point.

The other detail is that we might need router/route serialization/deserialization so that it gets added to the HTML sent to the initial client. Or perhaps a special route? Or somehow imported without the handlers (maybe dynamic import makes sense).

Would love your help on this, especially the client-side runtime piece. Your experience with raviger would be extremely valuable there. I think the thing which is genuinely interesting is the nested views approach. That stuff is fascinating and could be heavily optimizable.

[kyeotic]

In a nested router context you want to provide a subset of the total path, so asking a global for the path won't work. You need the closest ancestor to provide what is "left over"; each router consume its portions of the path and passes the remainder to the next router down.

Full Path: /application/random/about

Router.routes([
  ['/random/*', RandomApp] // * is greedy wildcard
])

function App(this: Context) {
  return (
    <main>
      <NavBar />
      <AppletRouter />
    </main>
  )
}

function AppletRouter(this: Context) {
  const route = Router.match(location.pathname)
  this.provide('basePath', route.basePath) // random

  return (
    <div>
      <AppSelector />
      {route}
    </div>
  )
}

function RandomApp(this: Context) {
  const appPath = this.consume('basePath') // /random/about
  const page = Router.match(appPath) // about

  return (
    <div>
      <RandomNavBar />
      {page}
    </div>
  )
}

To keep RandomApp from needing to know about the parent app or the route that its hosted at (or even know that its being nested) you need to get the path from the context, not from a global. This is where the <BrowserRouter> pattern comes from. It is serving a real purpose, not just obscuring globals.

Its also nice to have components encapsulate their interactions with the router. The application route config shouldn't need to register every single component that wants to respond to url changes; they can register listeners themselves using context helper utilities (aka hooks). When doing SSR the same globals (location, history) aren't available, so getting them from a standard abstraction provided by the routing library is a natural fit.

[brainkim]

That makes sense. I’m seeing clearer now. The key design constraint is path prefix independence. Code is more portable when you can define routes under a subpath prefix. That and using the component hierarchy makes sense.

[cowboyd]

fwiw, I was able to throw together dead simple routing with nano-router and switch statement because crank rules.

https://github.com/thefrontside/inspector/blob/main/ui/app/app.tsx

I'm sure there are a ton of use-cases I'm not really considering, but for those looking for something low-cost that will have them up and running in 5 minutes, this has carried us a long way.