feat: createNavigation

[amannn]

An exploration to create a unified function to create navigation APIs for an easier setup.

This is also intended to fix some long-standing issues with the current navigation APIs:

• Fixes Improve initial render of Link for localePrefix: 'as-necessary' and make getPathname more useful #444
• Fixes redirect does not respect as-needed locale prefix #1335
• Fixes Managing canonical links #785

TODO

• Implementation
  • react-server
  • react-client
  • domains
    • Incorporating it based on routing config (see comment in getPathname)
    • Should we accept it similarly to a locale as an argument for functions that generate pathnames?
• Restructure playground tests around "use cases"?
• Support cloneElement in RSC-rendered <Link /> (better compatibility with Radix Primitives & friends) #1271
• Verify (maybe add docs for) exceptions where we add a prefix regardless of the routing strategy
  • Changing locale with Link: This helps to update the cookie. Theoretically we could do this in a click handler, but only after hydration. Should we remove the prefix as part of hydration?
• Check bundle size difference
• Check (and add test for) the use case when adding pathnames to previously shared pathnames routing
• Have a brief look at Support localePrefix setting per domain #1055, at least enough to make sure this is possible to implement later
• Docs
  • See New: markers in createNavigation
  • Shared pathnames
  • Composing Link is now easier
  • Edge cases for localePrefix: 'as-needed' + domains
    • redirect has to always include prefix since we don't know the host (can user provide domain to avoid this? alternatively suggest multiple builds per domain)
    • Link prefixes always during SSR, but removes on client (can user provide domain to avoid this?)
• Rollout strategy
  • Adapt examples?
  • Adapt docs?
  • Export with unstable_ prefix?

Improvements

• redirect no longer adds unnecessary locale prefixes for localePrefix modes other than always (fixes redirect does not respect as-needed locale prefix #1335)
• Easier composition of Link
• getPathname now requires a domain when a combination of localePrefix: 'as-necessary' and domains is used. This enables to compute the correct pathname based on the defaultLocale of a given domain.

Migrating to createNavigation

createNavigation is generally a drop-in replacement for createSharedPathnamesNavigation as well as createLocalizedPathnamesNavigation.

The following changes might be necessary in your code base though:

1. If you've used createLocalizedPathnamesNavigation and have composed the Link with its href prop, you no longer have to provide the generic Pathname type argument.

- ComponentProps<typeof Link<Pathname>>
+ ComponentProps<typeof Link>

2. If you've used getPathname and have previously manually prepended a locale prefix, you should no longer do so—getPathname now takes care of this depending on your routing strategy.

- locale + getPathname(/* ... */)
+ getPathname(/* ... */);

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
next-intl-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Sep 20, 2024 1:26pm
next-intl-example-app-router	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Sep 20, 2024 1:26pm
next-intl-example-app-router-without-i18n-routing	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Sep 20, 2024 1:26pm