Question: How to Guard to shell route?

[Hackmodford]

I'm trying to get deep links from a cold start working. I believe I ran into the same issue with GoRouter where the deep link comes in, but the intended route gets overridden by the initial route.

With GoRouter I would cache my deep link, then on a redirect check for a cached route and go to that page.

I attempted to do something similar with guards but ran into the issue that I can only return the stack of the current router. If I have to deep link into a shell route, I'm not sure how I would proceed.

This was essentially what I'm trying to do. Is there a better way to achieve this?

[Mastersam07]

There are two things tangled together here, and I think only one of them is an actual problem.

Guards cannot do this, and that is deliberate.

A guard is typed FutureOr<List<R>> Function(List<R> current, List<R> proposed), bound to a single sealed route family. A branch router has its own family, so a main router guard structurally cannot name a branch route. That is the same property that makes your page builder switch exhaustive, so it is not something I want to loosen. Your read is correct: you can only return the current router's stack.

But you do not need a guard for this. Deep linking into a shell is a codec concern, and the cold start ordering is already handled for you.

KaiselConfig has a nestedState field. Decode the URL straight into the shell target:

@override
KaiselConfig<AppRoute>? decode(Uri uri) => switch (uri.pathSegments) {
  ['products', final id] => KaiselConfig(
    mainStack: [const ShellHost()],
    nestedState: KaiselShellConfig(
      activeBranch: 1,
      activeBranchStack: [const ProductList(), ProductDetail(id)],
    ),
  ),
  _ => null,
};

On cold start the shell has not mounted yet when this config arrives. The delegate parks the nestedState and applies it the moment the shell registers, and it will build the target branch even if that branch was never visited. So the "cache the deep link, then redirect" dance you had to write in GoRouter has no equivalent here. That part is already inside the router.

On "it gets overridden by the initial route".

That symptom has exactly two causes, and both are worth checking:

1. No codec on your KaiselRouterConfig. Without a codec, no RouteInformationParser is built at all, so the platform URL is never parsed and you always open at initial.
2. Your decode returned null for that URI. The parser then substitutes the fallback stack, which defaults to [initial]. That produces precisely the behaviour you are describing.

Since you have deep links partly working, my guess is 2 is what is going on: a pattern in the switch that does not match the incoming path. If you paste your codec, I can point at the case.

That silent fallback is on us, though. Swapping in initial with no debug output is genuinely hard to diagnose from the outside, so I would consider treating that(log or assert in debug builds when decode returns null).

If what you are really after is auth gated deep links, keep the main router guard for the "logged out, go to Login" rewrite and stash the intended destination. Today the cleanest replay after login is imperative:

None of this is written down anywhere useful. The CODEC docs shows the shell codec shape but says nothing about the cold start guarantee, and nothing covers auth combined with a shell deep link. I will add a how to for it. Thanks for surfacing it.

[Hackmodford]

I have a codec. And I did need to cache the cold start deep link. Otherwise the app wouldn't navigate.

I ended up doing this.

/// Stores destination and command to be executed after the app
/// is launched
PostLaunchData? _postLaunchData;

/// Cache the uri if the app is not initialized, otherwise handle it.
void _processAppLink(Uri uri) {
  final appLink = PostLaunchData.fromUri(uri);
  if (!getIt<AppInitializer>().isInitialized) {
    // app not ready, just cache it. The splash screen will process it later.
    _postLaunchData = appLink;
  } else {
    _handleAppLink(appLink);
  }
}

/// Handles a cached link if present. Returns true if stack changed
/// false if it does not.
bool handleCachedAppLink() {
  final appLink = _postLaunchData;
  _postLaunchData = null;
  if (appLink != null) {
    return _handleAppLink(appLink);
  }
  return false;
}

bool _handleAppLink(PostLaunchData appLink) {
  // Eventually commands can be handled here...
  goToUri(appLink.destination);
  return true;
}

@override
void goToUri(Uri uri) {
  final config = AppCodec().decode(uri);
  routerConfig.routerDelegate.setNewRoutePath(config);
}

And my splash screen calls handleCachedAppLink, bailing on navigation if that returns true.