Will the current transitionWhile() design of updating the URL/history entry immediately meet web developer needs?

[domenic]

As discussed previously in #19 (and resolved in #46), intercepting a navigation using the navigate event and converting it into a same-document navigation will synchronously update location.href, navigation.currentEntry, and so on. I think this is on solid ground per those threads; delaying updates is problematic. (EDIT: further discussion, starting around https://github.com/WICG/navigation-api/issues/66#issuecomment-1134818547, reveals this is not quite settled.)

However, I wonder about the user experience of when the browser URL bar should update. The most natural thing for implementations will be to have the URL bar match location.href, and update immediately. But is this the experience web developers want to give their users?

I worry that perhaps some single-page apps today update the URL bar (using history.pushState()) later in the single-page-navigation lifecycle, and that they think this is important. Such apps might not want to use the app history API, if doing so changed the user experience to update the URL bar sooner.

The explainer gestures at this with

TODO: should we give direct control over when the browser UI updates, in case developers want to update it later in the lifecycle after they're sure the navigation will be a success? Would it be OK to let the UI get out of sync with the history list?

and this is an issue to gather discussion and data on that question. It would be especially helpful if there were web application or framework authors which change the URL in a delayed fashion, and could explain their reasoning.

A counterpoint toward allowing this flexibility is that maybe standardizing on the experience of what SPA navs feel like would be better for users.

[kenchris]

I will try to reach out to some of my framework friend and see if they will leave any feedback

[manekinekko]

Thank you @kenchris for sharing this.

@mhevery @IgorMinar @alxhub @mgechev @@pkozlowski-opensource how is this going to affect Angular?

[manekinekko]

Also adding my friend @posva from the Vue.js team. Any feedback on this, Eduardo?

[posva]

I think this is on solid ground per those threads; delaying updates is problematic.

This is true. Being able to get the updated location right after pushState() in all browsers is easier to handle at framework level.

respondWith() design seems to be good to be able to use it. I would need to play with it to better know of course.

From Vue Router perspective, all navigations are asynchronous, meaning calling router.push('/some-location') will update the URL at least one tick later due to navigation guards (e.g. data fetching, user access rights, etc). This also applies for history.back() (or clicking the back buttons which seems to be the same) but in that scenario, the URL is updated immediately, and it's up to the router framework to rollback the URL if a navigation guard cancels the navigation. This means the URL changes twice in some cases (e.g. an API call to check for user-access rights). From what I understood with https://github.com/WICG/app-history/issues/32#issuecomment-790936485, this shouldn't be a problem anymore as we could avoid changing the URL until we are sure we can navigate there.

[atscott]

I don't have much additional to add for Angular beyond what @posva mentioned for Vue. Angular's router operates in much the same manner.

We do provide the ability to update the URL eagerly via the urlUpdateStrategy. The default is 'deferred' though, which means for most cases, the URL is update after guards run, like @posva mentioned for Vue.

We also have the same issue with the history.back/back buttons/url bar updates and we specifically don't do a good job of rolling back the URL (https://github.com/angular/angular/issues/13586#issuecomment-637206553) - this would be easy to fix with the app history API.

I'm in the process of going through the proposal and evaluating how we would integrate it into the Angular router.

[kenchris]

Hi there @atscott @posva can you explain me what those guards are and how they work? Asking for the @w3ctag

How long are these commonly deferred? Are we taking about microseconds here or can they be deferred indefinitely

[bathos]

I worry that perhaps some single-page apps today update the URL bar (using history.pushState()) later in the single-page-navigation lifecycle, and that they think this is important. Such apps might not want to use the app history API, if doing so changed the user experience to update the URL bar sooner.

I’m in that camp, but it’s not about the URL bar for me, it’s about ensuring APIs like location.href and node.baseURI are in sync with the effective current state of the application. I’ve seen bugs arise during the brief time between the start and end of async resolution of a new application state because of components treating the current URL as a source of truth*. Since switching to unilaterally performing an initial URL rollback before async resolution a few years ago, I’ve never seen these problems again.

Since the URL bar’s contents aren’t accessible to JS, it’s the one aspect of this which doesn’t matter to me — whether it updates optimistically wouldn’t impact whether there is an observable misaligned transitional state.

(It seems I want the exact opposite of what’s been described, if I understand right? — cause for me it’s “not delaying updates [to location.href, etc] is problematic.” Immediately-update-code-observable-location behavior might prevent us from making meaningful use of respondWith, though other aspects of AppHistory would remain useful to us regardless.)

How long are these commonly deferred? Are we taking about microseconds here or can they be deferred indefinitely

While I can’t answer for the folks above, brief unscientific testing suggests that in our case it falls between 0 and 150ms (w/ navigator.connection.effectiveType 4g). The timing depends on what dependent API requests are involved, if any. It seems fair to describe it as some specific fraction of the time it would take to load a whole new document if we were doing SSR since it’s a subset of the same work that would be done if we were (fetch x from the database, etc).

* Ex: Relative query param links, e.g. href="?page=2" from templates associated with the “old state” (which generally would not be replaced until the route resolution completes) will link to the wrong thing during the transition.

[posva]

Hi there @atscott @posva can you explain me what those guards are and how they work? Asking for the @w3ctag

How long are these commonly deferred? Are we taking about microseconds here or can they be deferred indefinitely

Sure, they are explained here and they usually last between 16ms or a few seconds. They can be deferred indefinitely but they shouldn't.

[bathos]

Currently playing with the Chromium impl, the required pattern to achieve the behavior we currently have (location updates after successful state transition) is roughly:

• on navigate, branch based on info value that may or may not be some sentinel:
  • sentinel absent and canRespond:
  • create & dispatch custom event (e.g. "navigaterequest"). associate orig destination / impl similar respondWith API
  • if custom respondWith called:
    • preventDefault / stopprop original event
    • await custom respondWith promise
    • if rejected, dispatch custom navigateerror (and do not commit the failed change to url)
    • otherwise, create navigate options based on original destination + promise result value (e.g. url canonicalization) and call navigate() with the sentinel info value to "commit" it

The built-in respondWith needs to be ignored in this model - the only "response" action is to preventDefault - but the end result is a similar API surface. It does seem like an improvement because it involves less code than current History-based solutions, but the misalignment is also very stark.

[domenic]

Very interesting! The fact that you are able to mostly emulate the delayed-URL-update behavior based on the current primitives is a good sign. It feels similar to #124 in that maybe we can add it to the API on top of what exists, so that anyone who wants to achieve a similar experience can just use app history directly instead of needing to get all the edge cases right in a way similar to what you describe.

[bathos]

Edit: This was a previously question I asked due to mistaking a behavior change related to location updates for one which would implement the behavior I’m seeking. But I got ahead of myself and can answer my own question about it: the bit I was clearly not paying attention to was that it said “after all handlers have finished running,” so no, the behavior did not change in the way I thought. Leaving the comment intact below to avoid confusion if people got emails.

Original comment/question

@domenic I just saw https://github.com/WICG/app-history/issues/94#issuecomment-849800737: > > Change the updating of location.href and appHistory.current to synchronously happen after all handlers have finished running (if respondWith() was called by any of them), instead of happening synchronously as part of respondWith(). This helps avoid the problem where future handlers see appHistory.current === appHistory.destination. Edit: this was done in Move URL/history updating out of respondWith() #103. > > The last of these is done. I'm interested in feedback on which, if any, of the first three of these we should do. Is it correct to interpret this as saying `event.methodCurrentlyKnownAsRespondWith(x)` behavior has been changed to now defer the update of observable `location`/`current` until `x` settles? Previous comments had given me the impression that location/current updating at the start rather than the end of a transition was a settled question. Our last two comments here are from a month later than the comment I quoted, too — so I’m not sure if maybe I’m misinterpreting what I read there. If this behavior is set to change, the cancel-initially-but-repeat-the-navigation-again-later dance I described in my prior comment won’t be needed as far as I can tell. Since I _think_ this was the only challenging disconnect between AppHistory’s behavior and the routing behavior we currently implement and want to preserve, if location update deferral is real now, it likely means we’ll be able to use the appHistory API “bare”! ^{_{I am dizzy imagining the possible thundering satisfication of just outright _deleting_ ten thousand pounds of terrifying tower-of-hacks-and-monkey-patches History mediation code without leaving _one trace_ ... gonna go lie down whew}}

[domenic]

From @jakearchibald in #232

With MPA:

1. Begin fetching

2. Time passes

3. Fetch complete

4. Switch to new page - URL changes here

With transitionWhile:

1. Begin fetching

2. `transitionWhile` called - URL changes here

3. Time passes

4. Fetch complete

5. Alter DOM

This means old-page content is being shown between steps 2-5, but with the new URL. This presents issues for relative URLs (including links, images, fetch()), which won't behave as expected.

It feels like URL changing should be deferred until the promise passed to transitionWhile resolves, perhaps with an optional commitURLChange() method to perform the swap sooner.

Along with the URL issue, there's also the general issue of the content not matching the URL.

We've known for some time that the content will not match the URL. This thread (as well as various offline discussions) have various framework and router authors indicating that is OK-ish, except for @bathos who is working around it.

The novel information for me here is Jake's consideration for relative URLs. It's not clear to me exactly what goes wrong here; surely for new content, you want to fetch things relative to the new URL? But I can imagine maybe that's not always what's assumed.

Anyway, toward solutions: the big issue here is that any delay of the URL needs to be opt-in because it breaks previous platform invariants. Consider this:

navigation.addEventListener("navigate", e => {
  e.transitionWhile(delay(1000), { delayURLUpdate: true });
});

console.log(location.href); // "1"
location.hash = "#foo";
console.log(location.href); // Still "1"!!!

Similarly for all other same-document navigation APIs, like history.pushState(), which previously performed synchronous URL updates.

As long as we have such an opt-in, we can probably make this work. The page just has to be prepared for same-document navigation APIs to have delayed effects.

[jakearchibald]

navigation.addEventListener("navigate", e => {
  e.transitionWhile(delay(1000), { delayURLUpdate: true });
});

console.log(location.href); // "1"
location.hash = "#foo";
console.log(location.href); // Still "1"!!!

fwiw, I think it'd be fine if fragment changes are guaranteed to be synchronous. Only navigations that would be cross-document can have their URL update delayed, matching MPA behaviour.

[jakearchibald]

Here are a couple of demos that might help:

https://deploy-preview-13--http203-playlist.netlify.app/ - requires Canary and chrome://flags/#document-transition. There's a two second timeout between clicking a link and the DOM updating.

This was supposed to be my "works fine" demo because it doesn't use relative links. However, I noticed that if I click one thumbnail, then click another within the two seconds, the transition isn't quite right.

This is because my code is like:

navigation.addEventListener('navigate', (event) => {
  event.transitionWhile(
    createPageTransition({
      from: navigation.currentEntry.url,
      to: event.destination.url,
    })
  );
});

Because the URL commits before it's ready, on the second click the from doesn't represent the content. To work around this, I guess I'd have to store a currentContentURL somewhere in the app, and try to keep that in sync with the displayed content.

https://deploy-preview-14--http203-playlist.netlify.app/ - here's an example with relative URLs. If you click one thumbnail then another, you end up on a broken URL. Even if you click the same thumbnail twice, which some users will do accidentally.

My gut feeling is that relative URLs on links is uncommon these days, but there are other types of relative URL that will catch folks out here. Eg, fetching ./data.json and expecting it to be related to the content URL.

[jakearchibald]

I wonder if frameworks have adopted the model of:

1. Update URL
2. Fetch content for new view while old view remains
3. Update DOM

…because of limitations in the history API, or whether they think this is the right model in general. Thoughts @posva @atscott?

It just seems like a fragile ordering due to things like relative URLs, and other logic that wants to do something meaningful with the 'current' URL, assuming it relates to the content somehow. It's also a different order to regular navigations, where the URL updates only once content is ready for the new view.

[jakearchibald]

https://github.com/sveltejs/kit/pull/4070 - Svelte switched to a model where the URL is only changed when the navigation is going to succeed, as in the new content is ready to display.

From the issue:

This is arguably less good UX since it means a user may get no immediate feedback that navigation is occurring

This isn't a problem with the navigation API, as it activates the browser loading spinner.

[bathos]

@jakearchibald FWIW, we don’t use relative pathnames, but we use relative query-only links in all our search/filter panels. This is where URL-first hit us.

[jakearchibald]

Oh yeah, I imagine that kind of thing is way more common

[Rich-Harris]

Echoing Jake, updating the URL before the navigation completes is very fragile. It's true that many prominent SPAs (including the very site on which we're having this discussion) do update the URL eagerly — and I suspect it is because there's otherwise no immediate feedback that the navigation intent was acknowledged — but we moved away from this approach in SvelteKit because it's buggy. Anything that involves a relative link during that limbo period is likely to break.

Here's a simple demo — from the / route, click 'a-relative-link` a few times. The app immediately gets into a broken state: https://stackblitz.com/edit/node-sgefhh?file=index.html.

Browser UX-wise, I think there's a case for updating the URL bar immediately — it provides an even clearer signal that activity is happening, and makes it easier to refresh if the site is slow to respond, and so on. But I think it's essential that location doesn't update until the navigation has completed. In fact I'd go so far as to say that updating location immediately could be a blocker for SvelteKit adopting the navigation API, which we very much want to do!

[domenic]

Thanks all for the great discussion. My current take is that we need to offer both models (early-update and late-update/update-at-will), and this discussion ups the priority of offering that second model significantly. Read on for more philosophical musings...

Cross-document (MPA) navigations have essentially four key moments:

• Start: clicking the link, setting location.href, etc.
• Commit: after the fetch of the destination page has gotten back headers, unload/pagehide fire on the starting page, the URL bar updates, and the content of the starting page becomes non-interactive. (This point used to flash a white screen, but "paint holding" these days keeps the old content around, non-interactively.)
• Switch: as response body content for the destination streams in, at some point it replaces the old page as the displayed content.
• Finish: once the response body, and all blocking subresources, have finished loading, the load/pageshow events fire. (The actual user perception of "finish" is usually somewhere before this point, leading to metrics like "FCP", "LCP", etc. to try to capture the user experience.)

The raw tools provided by history.pushState() allow you to emulate a variety of flows for same-document (SPA) navigations. For example, to emulate the above, you would:

• Start: Watch for click events on links. When they happen, start a fetch, and maybe add an in-page loading indicator.
• Commit: When the fetch headers come back, make the current page non-interactive, and call history.pushState().
• Switch: At some point during the fetch body streaming, swap in the fetched content into the document
• Finish: Once the entire response body has streamed in and been rendered, stop any in-page loading spinner.

But you can also emulate other flows, e.g. many people on Twitter mention how they prefer to consolidate Start + Commit. Or, you can do things MPAs can't accomplish at all, such as replacing "Switch" with "Show Skeleton UI", and then doing Start + Commit + Show Skeleton UI all together at once.

The navigation API currently guides same-document (SPA) navigations toward the following moments:

• Start+Commit: clicking a link, setting location.href, etc. will fire a navigate event. Then, the developer immediately updates location and the URL bar by calling navigateEvent.transitionWhile(). This starts the loading spinner, and creates the navigation.transition object.
• Switch: at some developer-determined point, they can replace the content of the page with something from the network (or wherever).
• Finish: at some developer-determined point, when the promise passed to navigateEvent.transitionWhile() settles, stop the loading spinner, set navigation.transition to null, and fire a navigatesuccess (or navigateerror) event.

We've found this to be pretty popular. Especially given how developers are keen to avoid double-side effect navigations (e.g. double submit), or to provide instant feedback by e.g. loading a skeleton UI of the next screen instead of waiting for network headers. We've even found Angular transitioning away from a model that allows late-Commit, into one that only allows Start+Commit coupled together. But as some folks on this thread are pointing out, it's not universal to couple those two. And coupling comes with its own problems; it's really unclear what the best point at which to update location is, with each possibility having tradeoffs depending on what assumptions your app and framework are making.

So we should work on some way of allowing Commit to be separated from Start, for SPAs and frameworks which want that experience.

[domenic]

So, https://twitter.com/aerotwist/status/1529138938560008194 reminded me that traversals are very different here than push/replace/reload navigations. For implementation reasons, it is extremely difficult to allow delayed Commit for them. (This is in fact a big reason why Angular is transitioning to not allowing delayed Commit.)

Introducing an asymmetry between traversals and others seems unfortunate, so I'm now less optimistic about solving this soon...

We've discussed something similar in https://github.com/WICG/navigation-api/issues/32, about preventing traversal Commit. Preventing and delaying are essentially equivalent, because delaying means preventing and then re-starting. Some of the more technical discussions in #207 and #178. The best current plan is allowing preventing traversal Commit for top-level frames only, and only for navigations initiated by user activation.

How would you all developers/framework authors feel if we could only delay Commit for push/replace/reload, but traversals always had Start+Commit coupled?

[atscott]

I wonder if frameworks have adopted the model of:

1. Update URL
2. Fetch content for new view while old view remains
3. Update DOM

…because of limitations in the history API, or whether they think this is the right model in general. Thoughts @posva @atscott?

It just seems like a fragile ordering due to things like relative URLs, and other logic that wants to do something meaningful with the 'current' URL, assuming it relates to the content somehow. It's also a different order to regular navigations, where the URL updates only once content is ready for the new view.

Here's the historical context for the eager vs deferred url updates in Angular: https://github.com/angular/angular/issues/24616

In defense of the initial design deferring the URL update:

...application developers would want to stay on the most recently successfully navigated to route.

The motivation to also support URL eager updates:

However, this might not always be the case. For example, when a user lands on a page they don't have permissions for, we might want the application to show the target URL with a message saying the user doesn't have permissions. This way, if the user were to copy the URL or perform a refresh at this point, they would remain on the same page.

Angular supports both eager and deferred URL updates and will likely need to continue to do that. Having the support for both in the navigation API would make adopting it easier so we won't have to work as hard to get both behaviors.

FWIW, I've never felt totally comfortable with the deferred strategy because it's not possible to maintain this behavior for all cases. What I mean is that even when using the deferred URL update strategy, the URL update is still "eager" when users navigate with forward/back buttons or the URL bar directly.

On the issue with relative links: we don't exactly have this issue in Angular because we expect users to only trigger navigations using the router APIs (for better or for worse). Links in the application are expected to use the routerLink directive which captures the click event on a href, navigates with the router API, and prevents the browser from doing its default navigation (code reference)

[jakearchibald]

@domenic

For implementation reasons, it is extremely difficult to allow delayed Commit for them

Ah, that's a real sadness. They behave with delayed commit in regular navigations.

I agree that there's little point adding delayed commit for new navigations if we can't have them for traversals too.

[Rich-Harris]

How would you all developers/framework authors feel if we could only delay Commit for push/replace/reload, but traversals always had Start+Commit coupled?

That's how it works at present for those of us deferring pushState, so it would be acceptable but perhaps not ideal — it would be definitely be more robust if the meaning of relative links wasn't dependent on the type of navigation taking place.

I noticed that traversals do involve a delayed commit when bfcache is disabled (e.g. there's an unload event handler), which makes me wonder if it's truly an impossibility in the case where the Navigation API is being used. I'm also curious about the extent to which we're limited by location mirroring what's in the URL bar — is there a possible future in which the URL bar updates immediately (to satisfy whatever design constraints make delayed commit difficult) but location only updates once navigation completes, or is that a non-starter?

Small point of clarification: to use the terminology in https://github.com/WICG/navigation-api/issues/66#issuecomment-1136101311, SvelteKit navigations (other than traversals) are Start then Commit+Switch+Finish. I think that's probably the case for most SPA-ish frameworks (i.e. there are two 'moments', and it's either that or Start+Commit then Switch+Finish); IIUC even frameworks that do Turbolinks-style replacements generally do a single element.innerHTML = html rather than something more granular involving streaming.

My current take is that we need to offer both models

I've spent a lot less time thinking about the nuances of the Navigation API than other people in this thread, but it does feel like something as fundamental as navigation should have one correct approach. The fact that SPA frameworks currently have different opinions about this is entirely because of the History API's terribleness, and I think it would be a shame if that prevented the Navigation API from being a clean break with the past.

On the issue with relative links: we don't exactly have this issue in Angular because we expect users to only trigger navigations using the router APIs (for better or for worse).

We're getting into edge case territory, but it's not just relative links — they're just the most obvious way in which things can break (and it's not always practical to use a framework-provided component, for example when the links are inside HTML delivered from a CMS). Constructing <link> elements, or images or iframes, or fetching data will also break if you're using relative URLs.

[domenic]

I noticed that traversals do involve a delayed commit when bfcache is disabled (e.g. there's an unload event handler), which makes me wonder if it's truly an impossibility in the case where the Navigation API is being used.

Sort of. How it actually works is that traversals are locked in and uncancelable roughly from the moment they start. So from the browser's point of view, they are "committed". (But, I agree this is not precisely the same as the "Commit" step I mentioned above... I can dig into this in nauseating detail if we need to.)

In more detail, there is an inter-process communication sent immediately upon any traversal-start, which gets a lot of machinery irreversably moving, including (in the non-bfcache case) the network fetch. So the technical problems come with inventing a new code path which delays this usual flow.

There is some precedent, in that beforeunload can prevent traversals. But then you start getting into less-technical issues around preventing back-trapping abuse...

Anyway, to be clear, I'm saying "extremely difficult" and "less optimistic about solving this soon", not "impossible".

I'm also curious about the extent to which we're limited by location mirroring what's in the URL bar — is there a possible future in which the URL bar updates immediately (to satisfy whatever design constraints make delayed commit difficult) but location only updates once navigation completes, or is that a non-starter?

It seems possible in theory to decouple them, subject to security/UI team's review. However I'm not sure how many problems it solves. The technical design constraints are not really related to the UI. On the implementation-difficulty side, they're as explained above; on the web developer expectations side, I think they're about what a given app/framework's expectations are for location, and I think we have examples of both expectations.

I think that's probably the case for most SPA-ish frameworks (i.e. there are two 'moments', and it's either that or Start+Commit then Switch+Finish);

I agree most SPA-ish frameworks tend to prefer a two-moment model. However I most commonly experience a split of Start+Commit+Switch, then Finish. E.g. start on a fresh tab with https://twitter.com/home , then click the "Explore" button.

I've spent a lot less time thinking about the nuances of the Navigation API than other people in this thread, but it does feel like something as fundamental as navigation should have one correct approach. The fact that SPA frameworks currently have different opinions about this is entirely because of the History API's terribleness, and I think it would be a shame if that prevented the Navigation API from being a clean break with the past.

I'm really torn on this!! And have been since March 9, 2021, when this thread was opened :).

My instincts are very similar to what you're saying. However I just have a hard time picking a model and saying everyone should use the same one. Especially given all the difficulties around traversals, and how I thought we had a good model but now Jake and you are coming in with solid arguments for a different model.

I think the constraints are the following:

• Switch needs to be developer-controlled since it's decoupled from navigation API concerns; it's really about presentation. Unless we tie the navigation API really strongly to some DOM-update or transition model, we can't enforce where it is grouped.
• We can either couple Start+Commit, or separate them. Separating them is very hard for traversals.

So this leads to the navigation API providing either Start+Commit, Switch, Finish; Start, Commit, Switch, Finish; or Start, Switch, Commit+Finish. Here + means inherently-coupled, and , means they are separate steps which the web developer can couple or decouple as they want.

The fact that I am torn and people have good arguments for both places to put Commit, makes me want to build Start, Commit, Switch, Finish. But if everyone was willing to accept Start+Commit, Switch, Finish, then we could say that's canonical today, and do no further work. And if everyone was willing to accept Start, Switch, Commit+Finish, then we could try to put the brakes on this API, go back to the drawing board, and try to build that. But I don't see that kind of agreement...

Constructing <link> elements, or images or iframes, or fetching data will also break if you're using relative URLs.

I am really curious to hear more about how people handle this. Jake and I were unable to find any non-demo sites that were broken in the wild by this issue. This suggests developers are either working around it painfully, or their frameworks are handling it for them. E.g., one way a framework could handle it for you is by preventing any code related to the "old" page from running, after Commit time. Is that a strategy anyone has seen? What does Angular do, @atscott?

[atscott]

This suggests developers are either working around it painfully, or their frameworks are handling it for them. E.g., one way a framework could handle it for you is by preventing any code related to the "old" page from running, after Commit time. Is that a strategy anyone has seen? What does Angular do, @atscott?

I don't know if I totally follow the whole problem here but I think the missing piece from @Rich-Harris is "it's not always practical to use a framework-provided component, for example when the links are inside HTML delivered from a CMS". To me, this means we're working outside the confines of the framework so this isn't really anything Angular would or could control.

For things inside the application, we do expect any URLs to be constructed from Router APIs. This means that any relative links created from within the application would only update when the Angular Router state updates. That said, regardless of "eager" or "deferred" browser URL/location updates, this internal state update in the Router is always deferred until we are pretty certain the activation will happen: https://github.com/angular/angular/blob/8629f2d0af0bcd36f474a4758a01a61d48ac69f1/packages/router/src/router.ts#L917-L927

[Rich-Harris]

I am really curious to hear more about how people handle this. Jake and I were unable to find any non-demo sites that were broken in the wild by this issue.

Yeah, I'm not too surprised by that. Most SPA frameworks provide a <Link> component (I'm personally not a fan — I prefer just using HTML, particularly since it works seamlessly with markup delivered from an API etc), and I suspect most developers are probably in the habit of preferring absolute URLs anyway out of a primal instinct to prevent exactly this sort of question from arising. And when relative links do slip through, they'll be indistinguishable in Sentry logs etc from any other 404.

So it's definitely arguable that this is enough of an edge case that it's a wontfix (I wasn't aware of it myself until people mentioned it in the SvelteKit issue tracker). It just seems like 'relative links on the web are brittle, avoid them unless you know what you're doing' would be an unfortunate place to end up! Truly, there are no right answers here.

[posva]

The fact that I am torn and people have good arguments for both places to put Commit, makes me want to build Start, Commit, Switch, Finish. But if everyone was willing to accept Start+Commit, Switch, Finish, then we could say that's canonical today, and do no further work. And if everyone was willing to accept Start, Switch, Commit+Finish, then we could try to put the brakes on this API, go back to the drawing board, and try to build that. But I don't see that kind of agreement...

I wanted to say that pretty much of what @Rich-Harris explained and argumented applies to Vue Router as well and specifically the differences between a UI initiated navigation and one that comes from the code (e.g. a <Link> component or an <a> element) in terms of Start, Commit, Switch, and Finish is what, IMO, makes this new API feel like we are still facing some of the same issues that the History API has.

Vue Router also has a Start and then Commit+Switch+Finish strategy and given how much users struggle with routing concepts (besides the different behaviors of browsers, which fortunately got much much better in the past decade), I think it would be preferable to have one correct way of handling the navigation that is consistent through different user interactions.

[jakearchibald]

It seems like https://router.vuejs.org/guide/ does things the other way. The URL changes, then sometime later the content updates.

Is it using an older version of the router? Has it been a recent change?

[jakearchibald]

React Router is also moving to a model where the URL change happens when content changes https://twitter.com/ryanflorence/status/1529272521031159809

[jakearchibald]

I started a Twitter discussion about this https://twitter.com/jaffathecake/status/1529031579980419072. A lot of developers prefer the model where the URL updates straight away, because:

• It feels responsive
• It means if the user presses refresh, they're refreshing the URL they want to go to
• The URL is "the source of truth"
• It's how the browser behaves by default

Of course, it isn't how the browser behaves by default. I think folks are being misled by paint holding. And when it comes to "source of truth", that doesn't seem like a good argument, as there's also the "source of truth" in terms of the current content, and the mismatch there is what's creating problems.

It seems like folks who've thought a lot more about this, as in folks making routing libraries, prefer a model where the URL changes when the old content is removed. Angular is moving back to a model where the URL change happens earlier, but this seems motivated by the inability to delay URL commits on traversal (@atscott shout up if this is incorrect).

Commiting the URL when old content is removed seems to closer match MPA behaviour, and one of the things I really like about the Navigation API is it attempts to reinstate a lot of the MPA behaviours you get for free, but lose with the current history API.

[jakearchibald]

Thinking of the parts involved in an SPA navigation:

• Browser loading state
• In-app loading state
• Content & view fetch
• Scroll state stored
• View switch to placeholder content
• Focus state reset
• View switch to populated content
• History entry switch (including URL change)
• Scroll state restored

And their timings in a "late URL commit" model:

Browser loading state

Starts: Right after the "navigate" event, unless it's cancelled. Ends: Assuming an SPA navigation, no earlier than "History entry switch", although it'd be nice to keep the loading state going for secondary assets. In Navigation API: ✅ Start and end is controlled by the promise passed to transitionWhile. ⚠️ Although the end of the promise also triggers scroll restoration, so you're kinda restricted when it comes to stopping the browser loading state.

In-app loading state

Optional - In some cases the browser loading state will be enough. I'm assuming this doesn't significantly change the layout of the page, it's just a spinner etc added to the current content. Starts: Right after the "navigate" event, unless it's cancelled. Ends: no earlier than "view switch to placeholder content". In Navigation API: ✅ Developer makes the DOM change right after calling transitionWhile.

Content & view fetch

Starts: Right after the "navigate" event, unless it's cancelled. Ends: As soon as possible! Might be synchronous. In Navigation API: ✅ Developer begins the fetch right after calling transitionWhile.

Scroll state stored

When: Ideally, just before the old content is removed. So, just before "view switch to placeholder content" or "view switch to populated content", whichever is first. In Navigation API: ⚠️ When transitionWhile is called. There's a gotcha with the current design where it's easy to accidentally do "view switch to populated content" or "view switch to placeholder content" before calling transitionWhile. See https://github.com/WICG/navigation-api/issues/230. It also means that scrolling during content fetching is forgotten.

View switch to placeholder content

Optional - only beneficial if this will be significantly sooner than "view switch to populated content". When: Between the view being available and "view switch to populated content". When the view is available, this step may be delayed to avoid a flash of this state before "view switch to populated content". In Navigation API: ✅ Developer updates the DOM manually sometime after calling transitionWhile.

Focus state reset

When: When the old content is removed. So, just before "view switch to placeholder content" or "view switch to populated content", whichever is first. Maybe this should happen again with "view switch to populated content" even if it already happened with "view switch to placeholder content"? In Navigation API: ⚠️ Seems like developers would have to do this manually? Particularly as focus resetting doesn't happen if the user changes focus during the loading process, it seems like automatic focus resetting is unreliable.

View switch to populated content

When: As soon as possible! Might be synchronous. I'm counting this as 'done' when core content is available, although secondary content may continue to load and display. In Navigation API: ✅ Developer updates the DOM just before the promise passed to transitionWhile resolves.

History entry switch

When: When the old content is removed. So, just before "view switch to placeholder content" or "view switch to populated content", whichever is first. It's important that it happens before, so things like relative URLs and references to the current history entry reference the correct thing. In Navigation API: ❌ Currently as soon as transitionWhile is called, which doesn't allow for the model being discussed in this issue.

Scroll state restored

When: After "View switch to populated content". In Navigation API: ✅ After the promise passed to transitionWhile settles.

[posva]

It seems like router.vuejs.org/guide does things the other way. The URL changes, then sometime later the content updates.

That's not vue router, that's vitepress light routing on its docs, but for vue router, this is how I understand the terms:

• Start: router.push() or clicking a link
• Commit: change the URL
• Switch: Update what is displayed on the page
• Finish: end of the navigation

In those terms, yes, the URL changes, and then the content updates (this takes a few ms but happens with the commit hence the +). This is because the route is used as the source of truth to choose what view is displayed and of course, nothing prevents us from adding another source of truth to differentiate the pending view (the one that should be displayed if the ongoing navigation succeeds) from the current view associated with the URL (last valid view). But right now, as soon as we call history.push(), we update the route (source of truth) and immediately after the content switch follows.

React Router is also moving to a model where the URL change happens when content changes twitter.com/ryanflorence/status/1529272521031159809

I would say we do the same in Vue Router but that depends on what "updating the url with the dom" means: does one happen before the other or does the new page render at the exact same time (same js tick) the URL changes (or does it even matter?). If they happen at the exact same time, then vue router does indeed change the URL one tick before changing the content but I do have plans to change it in the future, unless there is a new correct way of doing navigation with this API, in which case we will align.

[jakearchibald]

I think the correct time to switch the current history entry (which impacts URL resolving, navigation.current, and location) is right after removing the old content, although the order might not matter when both actions happen synchronously.

That means that the order is:

1. Old view stops running
2. History entry changes
3. New view (or placeholder view) starts

That means each view exists during its relevant history entry, like MPA.

[Rich-Harris]

Commiting the URL when old content is removed seems to closer match MPA behaviour, and one of the things I really like about the Navigation API is it attempts to reinstate a lot of the MPA behaviours you get for free, but lose with the current history API.

Thanks for the survey of different routing libraries Jake — it's starting to seem like there's more consensus than we previously imagined, and the only real sticking point is traversal.

But I had a realisation about traversal. Traversing using the Navigation API is akin to traversing between pages that disable bfcache — in both cases, the application is preventing the browser's normal behaviour. In the latter case, that manifests as a delayed commit. If emulating MPA behaviour is the goal, I think it would be more correct for Navigation API traversals to also have delayed commits.

[jakearchibald]

Yep. We've been trying to spec this properly in https://whatpr.org/html/6315/document-sequences.html#navigable - that's why there's a 'current' and 'active' history entry. This caters for cases where the user presses back twice before the first fully commits.

[atscott]

It seems like folks who've thought a lot more about this, as in folks making routing libraries, prefer a model where the URL changes when the old content is removed. Angular is moving back to a model where the URL change happens earlier, but this seems motivated by the inability to delay URL commits on traversal (@atscott shout up if this is incorrect).

I definitely wouldn't say Angular is moving to earlier URL updates. The feature to do that was added in 2018 to address developer requests. Of the thousands of Angular apps in Google, only a couple dozen use eager URL updates. Every other application uses the default: deferring the URL update until right before the view is synchronously replaced.

Some bullet pointed notes on this:

• Deferred updates are certainly easier to manage with the current history API. Not touching the URL or history until you're ready to commit the change means the rollback scenario is easier.
• The above point did lead to some assumptions in the Angular router that broke on a cancelled navigation because of traversals (https://github.com/angular/angular/issues/13586).
• With the above, it would be good to have some consistency in either what we can expect from the browser URL between traversals and those triggered programmatically. Or a consistent way to roll back a cancelled navigation in both scenarios so we don't have two branches of how to resolve/roll back a cancelled navigation.
• Eager URL updates does make some things easier. For example, redirecting to a new page but keeping the URL of the original navigation. For eager URL updates, you're able to just trigger a redirect navigation and skip the URL change (https://github.com/angular/angular/issues/17004).
• Similar to above and the original motivation for adding support for more eager URL updates (as mentioned above), "when a user lands on a page they don't have permissions for, we might want the application to show the target URL with a message saying the user doesn't have permissions. This way, if the user were to copy the URL or perform a refresh at this point, they would remain on the same page"
• Even with "eager" updates in Angular, the URL update is still a bit deferred. We don't update the URL until processing redirects, which can be asynchronous, to prevent URL thrashing. This process can actually take a fair bit amount of time because it also includes expanding and fetching any lazy web chunks.

[jakearchibald]

Chatted through some of the use-cases with @domenic, and in ideal cases there's probably not a ton of difference between the late-commit and early-commit models.

In https://github.com/WICG/navigation-api/issues/66#issuecomment-1137087989, if you have a view with placeholder content, that would only come in with a significant delay if the view itself wasn't ready (as in, it's loaded on-demand, which is likely in web apps with many views), or if there wasn't any placeholder view, so full content is needed.

@domenic pointed out that in native apps, it's rare for there to be a delay between tapping something and going to the next view. It's more common to go straight to a placeholder view. Although it's sometimes different if it's like a form submit.

Back/forward should ideally use cached data, which is in line with browser's bfcache behaviour. But even without bfcache, the browser will use a stale copy of the page from the cache, unless it's no-store.

So I guess the difference between early commit and late commit is almost unnoticeable in ideal UX cases. Although folks making routing libraries don't get to enforce ideal UX 😄, if the developer wants to create a slow loading route, the routing library has to do the best it can with that.

[Rich-Harris]

in native apps, it's rare for there to be a delay between tapping something and going to the next view

This is true, but I think different norms prevail on the web. MPAs have trained us to expect content immediately, and the current crop of MPA-SPA hybrid frameworks (Next, Nuxt, Remix, SvelteKit et al) seek to emulate this. It's certainly possible to render a placeholder view immediately and then fetch content in a useEffect or similar (which the frameworks in question would consider 'outside' the navigation; reasonable people could differ on that point though it's probably not important), but it's generally considered a bad practice.

In general I don't think placeholder views on the web constitute 'ideal UX', so I think there is a significant difference between early and late commit.

Aside from the well-trod concerns around relative URLs, redirects are a good example of deferred commits providing better UX. Consider the case where the user navigates to /admin, but (after the app communicates with the server to load user data) is redirected to /login. Briefly flashing the intermediate URL is jarring, and not how MPAs work.

[jakearchibald]

Another probably-more-common relative URL issue that came up: <a href="#further-reading">…</a>

In the current model:

1. User is on /foo/
2. User clicks link to /bar/
3. Fetch begins, URL changes to /bar/
4. User clicks 'further reading'. URL changes to /bar/#further-reading, and page is scrolled to that content.

This seems weird, as it wasn't the intention to go to /bar/#further-reading. The end result will depend on how the app chooses to handle the hashchange navigation.

[PH4NTOMiki]

It looks like GitHub too moved to updating URL after loading all of the require resources for page navigation.

[natechapin]

@dvoytenko had an interesting idea when I mentioned this issue: instead of adding a delayURLUpdate bit, add an optional precommitHandler to the NavigationInterceptOptions dictionary. So a delayed update would look something like:

navigation.addEventListener("navigate", e => {
  e.intercept({ precommitHandler: commitBlockingFunc, handler: afterCommitFunc });
});

The precommitHandler would execute before commit, and commit would be deferred until any promise returned by the precommitHandler resolves.

Both precommitHandler and handler are optional, so you could mix and match usage as needed. Passing state from a precommitHandler to a post-commit handler is not perfectly ergonomic, but it has the advantage of giving both types of handlers well-defined execution times, instead of varying the execution order based on a boolean.

It certainly makes the browser-side implementation easier, but I'd appreciate framework-author feedback on whether it would meet your use cases.

[jakearchibald]

It would be common to want to pass state from one to the other, so that ergonomic issue is a big deal.

What is it about the two-callback system that makes it easier in terms of implementation vs a boolean?

[domenic]

Hmm, can you give an example of such a common need? This thread seems to be mostly people saying they would only use precommit, or only use post-commit, in their framework.

Also, the "ergonomic issue" is just having to use closures, right? It doesn't feel so bad to me...

[jakearchibald]

Hmm, can you give an example of such a common need? This thread seems to be mostly people saying they would only use precommit, or only use post-commit, in their framework.

If that's the case, maybe it's ok. I thought there'd be stuff you could only do in handler, such as scroll & focus handling, so you'd end up doing the fetching in precommitHandler and then have to use the result of that in handler.

Although, maybe this division is good? Things like scroll position capturing can be done after precommitHandler, but before handler.

[atscott]

For Angular, if we wanted to maintain the exact same url update timing there is today, passing data between the two handlers would make things easier. Currently this would have to be done by cancelling the first navigation and then triggering a new one.

Both update strategies in Angular today delay the URL update until after redirects are determined and a final target is matched (which can be async), even for “eager” url updates. And then for “deferred” updates, we commit then URL change right before activating the components (so there’s still some work post-commit).

So being able to do things in the precommit and then continue the navigation in the after commit handler would make things easy to maintain the current timings.

That said, I do think this is a nice idea even without being able to pass data between the two. Hopefully the slight timing differences wouldn’t be too difficult for existing applications to account for.

[domenic]

So let's be a bit clearer about passing data between the two. Without any first-class support from the API, you could do this, right?

let someData;

navigateEvent.intercept({
  async precommitHandler() {
    someData = await (await fetch("data.txt")).text();
  },
  async handler() {
    await doTypingAnimation(document.body, someData);
  }
});

In particular, "Currently this would have to be done by cancelling the first navigation and then triggering a new one" doesn't seem accurate; you could just use code like the above, I believe.

Whereas with first-class support, you'd have something like... this?

navigateEvent.intercept({
  async precommitHandler() {
    return await (await fetch("data.txt")).text();
  },
  // Takes an array because there might be other precommitHandlers
  // from other intercept() calls. We'll assume there's only one though.
  async handler([data]) {
    await doTypingAnimation(document.body, someData);
  }
});

or maybe this?

// Today `this` is undefined inside handler(),
// but we could change that so that it's the passed-in object:

navigateEvent.intercept({
  async precommitHandler() {
    this.someData = await (await fetch("data.txt")).text();
  },
  async handler() {
    await doTypingAnimation(document.body, this.someData);
  }
});

Those don't seem like very big wins to me, so maybe I'm missing what people are thinking about.

[atscott]

@domenic By “currently” I meant in the absence of this new proposed precommit handler (ie https://github.com/WICG/navigation-api/issues/66#issuecomment-870098095). I didn’t mean to imply I see no workarounds without first class support using the precommit proposal. I was only trying to provide a use-case for wanting to pass data between the handlers.

[domenic]

Got it, sorry for misunderstanding. What do you think of the various code snippets? Would one of the latter two be more pleasant to use than the one based on closures?

[jakearchibald]

One of the main reasons this API exists is because the history API is ergonomically bad. So, if we're making a compromise on ergonomics here, it'd be good to know if it's worth it. If it's just to make the implementation a bit easier, I'd rather the implementation pain was taken once per engine rather than once per use of the API.

Some stuff that isn't clear to me:

When would things like scroll position be captured in relation to these two callbacks?

If I decided not to use handler and just use precommitHandler, are there features that I wouldn't have access to (like manual scroll/focus handling).