New function to programmatically navigate between routes

Programmatical navigation with preact-iso is confusing due to the use of the useLocation hook which is limited by the rules of React hooks, rules that may not be intuitive.

From reading the issues, it seems that this is causing great confusion among users so I suggest a new API to change routes which would be more intuitive for users and would alleviate some of your support burden i.e.

#71
#54
#53
#97

I suggest a new function to navigate to a route that is not limited by the rules of React hooks.

import { pushRoute } from 'preact-iso';

function AnywhereInTheCode() {
    // Anywhere in the code, not only in places where hooks can be used
    pushRoute('/url');
}

Here are a few ideas of names for this function goTo, navigate, pushRoute.

From my reading of the code

preact-iso/src/router.js

Line 30 in 82cdde4

function handleNav(state, action) {

it seems that the route function from useLocation does not fundamentally need to be a hook, so we could move it to its own dedicated function.

[rschristian]

PRs welcome, but you're missing that calling handleNav, on its own, won't connect back to the LocationProvider state:

preact-iso/src/router.js

Line 101 in 82cdde4

const [url, route] = useReducer(handleNav, props.url || location.pathname + location.search);

[rschristian]

This probably won't be addressed outside of #75

I've identified another problem that may be related to the current useLocation API, so I see this as an opportunity to rethink the API, but maybe it's too much out of scope for this project, so please let me know.

The problem is that the example code given in #108

function App() {
  return (
    <LocationProvider>
      <a href="/">A</a> | <a href="/b">B</a>
      <Main />
    </LocationProvider>
  );
}

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

  function onRouteChange() {
    console.log(location);
  }

  return (
    <Router onRouteChange={onRouteChange}>
      <Route path="/" component={A} />
      <Route path="/b" component={B} />
    </Router>
  );
}

Re-renders Main on every route change due to (from my understanding) the use of the useLocation hook and onRouteChange callback, which is very inefficient.

Thus, there is currently no way to :

1. efficiently subscribe to route changes (e.g. to update the active item in a sidebar)
2. to have a central "routing guard": prevent the nagivation to some route depending on some state (e.g. prevent unauthenticated users to go to `/dashboard/*')

I currently see 2 potential and non-exclusive solutions.

First, it would be to replace the onRouteChange callback with a signal instead, so we can subscribe to route changes in any component. Maybe something like:

const routeSignal = createSignal(new URL());
<Router signal={routeSignal}>

Second, having an API similar to VueJS navigation guards which would allow us to "intercept" route change, and redirect to another route if some condition is not met.

router.beforeEach((to, from) => {
  // redirect to another route if not authenticated
  return "/login"
  // ...
  // explicitly return false to cancel the navigation
  return false;
})

[rschristian]

re-render Main on every route change due to (from my understanding) the use of the useLocation hook and onRouteChange callback, which is very inefficient.

It's very inefficient that you subscribe to a value and that subscription triggers rerenders? That's what you're doing by using useLocation, subscribing to it and telling Preact to rerender <Main> every time it changes. This doesn't make much sense to me.

onRouteChange passes the current path to the callback anyhow, you can entirely skip using useLocation for that.

to have a central "routing guard": prevent the nagivation to some route depending on some state (e.g. prevent unauthenticated users to go to `/dashboard/*')

This is pretty simple to build yourself, and better done there too; allows for more flexibility in implementation.

Here's a little example though:

import { useLocation } from "preact-iso";
import { useContext, useEffect } from "preact/hooks";
import { StateContext } from "../context/state-context";

export default function useAuth({ authentication = true }) {
  const { route } = useLocation();
  const state = useContext(StateContext);

  useEffect(() => {
    if (authentication && state.auth?.value.isAuthenticated !== authentication) {
      route("/login");
    }
  }, [state, authentication]);
}

function MyComponent() {
  useAuth(true);
  ...
}

// Alternatively as a route component...

function AuthRoute(props) {
    const { route } = useLocation();
    const state = useContext(StateContext);

    if (!state.auth?.value.isAuthenticated) {
        route("/login");
    }

    return h(props.component, props);
}

// You can use it in place of Route, i.e.,

<AuthRoute path="/private" component={MyPrivateComponent} />

Easy to adjust for whatever specific behavior you need, without having to patch the library's implementation.

First, it would be to replace the onRouteChange callback with a signal instead, so we can subscribe to route change in any component.

We'd never use signals here, sorry, but it too is trivial to write in userland.

It's very inefficient that you subscribe to a value and that subscription triggers rerenders?
onRouteChange passes the current path to the callback anyhow, you can entirely skip using useLocation for that.

What I'm telling is that the subscription / re-render inefficiency is forced on us and there is no other way to efficiently subscribe to route changes and to programmatically navigate between routes.

For example the path may not be enough to take a decision in a onRouteChange callback, we may also need query parameters.

This is pretty simple to build yourself, and better done there too; allows for more flexibility in implementation.

We are currently doing something similar, but I believe that it's a pattern common enough that it warrants a dedicated API in the base routing library. The solution adopted by vue-router (beforeEach) is really great, why not copy it?

We'd never use signals here, sorry, but it too is trivial to write in userland.

I understand not wanting to add dependencies. On the other hand, writing it in userland (as we've done) forces re-renders of the entire components tree due to subscriptions.

Taking again the example of the sidebar, vue router and vue's reactivity system allows the sidebar to subscribe to route changes so we don't need to re-render the entire component tree to update which item of the sidebar is "active".

Another example would be a component in a navbar the shows the current active project depending on the current route e.g.

Workspace > project

Preact is very well placed to offer similar ergonomics and performance thanks to signals. But I understand if it's out of scope for preact-iso, I'm just offering food for thoughts in order to make the project better for a larger number of users.

I believe that these patterns are common enough that hey deserve consideration about how to incorporate them in the base API. I believe that we should take inspiration from vue-router which provides 90% of what you need, for 10% of the code / API surface.

[rschristian]

For example the path may not be enough to take a decision in a onRouteChange callback, we may also need query parameters.

You can use location for that? It'll provide all current path information, albeit, disconnected from the router. It'll be perfectly sufficient there.

but I believe that it's a pattern common enough that it warrants a dedicated API in the base routing library. The solution adopted by vue-router (beforeEach) is really great, why not copy it?

We generally don't build software in that way here. Usually solutions need extremely broad appeal and cannot be reasonably implemented in userland to make it into our libraries. That's not always the case of course, but it's what we aim for. If you can do it yourself we probably won't provide it.

Every addition increases the surface area further and we simply don't have an army of folks helping us maintain this stuff, nor do we have any companies funding full-time development. We maintain as we can in our free time and at the moment it's pretty much just me, as you can see from the activity here in the repo.

On the other hand, writing it in userland (as we've done) forces re-renders of the entire components tree due to subscriptions.

It'd cause rerenders either way as we won't be refactoring this lib to be signals-based anytime soon.

What you're suggesting and asking for is a rather significant divergence and a completely different model -- I'm glad you like signals but a change of that scope is simply too much, IMO. It's too big of a change.

A signals-based router would be pretty neat, and perhaps you can build it via a fork of iso and reuse some code, but it's not going to land here in the near future, sorry.

[rschristian]

Going to close this out as there's noting actionable here at the moment. We (I) won't be fundamentally rewriting the router anytime soon and #75 should at least offer a better method of navigating when the Navigation API becomes more stable.

If you have other comments or concerns I'd be happy to address them, but sounds like you might be happier looking for a different router or writing one up yourself. We're a very different ecosystem than Vue, we won't necessarily be trying to copy their "all inclusive" approach in the near future.

[micahjon]

FWIW, if others are running into this, it's pretty trivial to expose route in a dummy component. Kinda gross but it works and shouldn't impact perf.

// global-route.ts

import { useLocation } from 'preact-iso';

let exposedRoute: (to: string, replace?: boolean) => void;

// Just stick <GlobalRouteExposer /> in your root component
export function GlobalRouteExposer() {
  const { route } = useLocation();
  exposedRoute = route;
  return null;
}

// Import this wherever you need access to route() outside of components
export function route(to: string, replace = false) {
  return exposedRoute(to, replace);
}

[rschristian]

You have to be a bit careful with that though, if GlobalRouteExposer isn't rendered first you'll get a nasty error that's not going to be the easiest thing to track down.

But yeah, it will work. You can hoist any hook out of a component like that.