How on earth does the createNavigation() function work?

[Lee-Minhoon]

If you refer to the code, it exports hooks like useRouter, which cannot be used on the server, along with the Link component. However, even when importing the Link component in a server component, no error occurs.

// i18n/navigation.ts
import { createNavigation } from "next-intl/navigation";

import { routing } from "./routing";

export const { Link, redirect, usePathname, useRouter, getPathname } =
  createNavigation(routing);

export const i18nNavigation = createNavigation(routing);

However, when I write code with a similar structure within the project and only import the Link component, I encounter an error like the one below.

// progress.tsx
import { useMemo } from "react";

import { default as NextLink } from "next/link";
import {
  useRouter as useNextRouter
} from "next/navigation";
import nProgress from "nprogress";

type Router = () => ReturnType<typeof useNextRouter>;

function createHandler<T extends (...args: any) => any>(handler: T) {
  return (...params: Parameters<T>) => {
    nProgress.start();
    return handler(...params);
  };
}

export function createProgressRouter(baseRouter: Router): Router {
  function useRouter() {
    const router = baseRouter();

    return useMemo(() => {
      return {
        ...router,
        push: createHandler(router.push),
        replace: createHandler(router.replace),
        back: createHandler(router.back),
        forward: createHandler(router.forward),
      };
    }, [router]);
  }

  return useRouter;
}

export function createProgressLink<
  T extends React.ComponentProps<typeof NextLink>,
>(BaseLink: React.ComponentType<T>): React.ComponentType<T> {
  return function Link(props: T) {
    return (
      <BaseLink
        onClick={(e) => {
          nProgress.start();
          props.onClick?.(e);
        }}
        {...props}
      />
    );
  };
}

// navigation.ts
export const Link = createProgressLink(i18nNavigation.Link);
export const useRouter = createProgressRouter(i18nNavigation.useRouter);
export const { redirect, usePathname, getPathname } = i18nNavigation;

[amannn]

How on earth does the createNavigation() function work?

😅 Glad you're asking!

The way this works in next-intl is that we use the react-server export condition to provide a different implementation, depending on if you're importing from a Server or Client Component.

next-intl/packages/next-intl/package.json

Lines 64 to 69 in 1e74950

	"react-server": {
	"development": "./dist/esm/development/navigation.react-server.js",
	"default": "./dist/esm/production/navigation.react-server.js"
	},
	"development": "./dist/esm/development/navigation.react-client.js",
	"default": "./dist/esm/production/navigation.react-client.js"

While all APIs are available in Client Components, in Server Components some APIs are replaced with functions that will throw if invoked by accident:

next-intl/packages/next-intl/src/navigation/react-server/createNavigation.tsx

Lines 48 to 49 in 1e74950

	usePathname: notSupported('usePathname'),
	useRouter: notSupported('useRouter')

This allows to have createNavigation as a single factory function that can be used in either environment.

In consuming apps, in case you want to create your own navigation APIs, I'd suggest to not use the factory pattern, but to create your navigation APIs in distinct files (e.g. useRouter.ts, Link.tsx, …). This way, you don't have to worry about any of this.

[Lee-Minhoon]

@amannn Thank you so much for your precise and detailed response! I really appreciate your hard work in developing such a great library.

[amannn]

Sure, glad to hear you like it! 🙌