Update documentation for TypeScript usage

[ScreamZ]

Hello,

Just proposed some documentation improvements.

[vercel]

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

Name	Status	Preview	Comments	Updated (UTC)
next-intl-example-app-router	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 2, 2024 0:21am

[vercel]

@ScreamZ is attempting to deploy a commit to the next-intl Team on Vercel.

A member of the Team first needs to authorize it.

[amannn]

Hey, thanks for proposing this change! We do in fact already have docs for how to compose the Link with its href prop in case of localized pathnames: Link (click on "Localized pathnames" and see "How can I compose the link with its href prop?" below).

I think that should already cover this sufficiently, what do you think?

Statically typed links for shared pathnames is tracked here: #396

[ScreamZ]

Hey, thanks for proposing this change! We do in fact already have docs for how to compose the Link with its href prop in case of localized pathnames: Link (click on "Localized pathnames" and see "How can I compose the link with its href prop?" below).

I think that should already cover this sufficiently, what do you think?

Statically typed links for shared pathnames is tracked here: #396

Oh… That was hidden in a dropdown. Got it. Your implementation is a bit more verbose but makes sense too. Thanks for your kind answer :)

I ended up with

export type LinkHref = ComponentProps<typeof L>["href"] | `http${"s" | ""}://${string}` | string;

type LinkProps = Omit<ComponentProps<typeof L>, "href"> & {
  href: LinkHref;
};

/**
 * A link that works for internal or external links.
 * TODO: This is supposed to work as Link from `next/link` handle internal and external link, otherwise we need some logic.
 */
export const Link: React.FC<LinkProps> = ({ href, ...props }: LinkProps) => (
  <L
    {...props}
    href={href as ComponentProps<typeof L>["href"]}
    className={twMerge("transition-opacity hover:opacity-70", props.className)}
  >
    {props.children}
  </L>
);

I don't know if it's better, it covers the topic that's right, but I just found that some topics are —sometime— hidden deep in nested things and hard to found. Maybe they could be part of a FAQ section?

Also not sure about having a dedicated TypeScript section alone, or maybe it should backlink to such content like how to compose links? Or sometimes this might be hard to found. What do you think?

The FAQ section makes sense, and is the right answer I think, for all this dropdown stuff. (And we can still backlink each of these dropdown back to the FAQ section too)

[amannn]

There was an FAQ section at some point but it ended up just collecting random stuff that didn't fit anywhere else better 🙂. I found that it's better to provide optional expandable sections while you're researching about a particular feature. E.g., if you're exploring the docs for Link, it makes sense that there is a hint on how to compose the href prop, instead of listing this on a separate page.

The TypeScript docs are actually somewhat an exception currently, maybe we could even move them into the messages docs at some point 🤔. But generally, all of the docs are TypeScript-first.

Hope this makes sense for you!

[amannn]

I'm going to close this for the time being as there are already docs about composing the href prop. Thanks for the input though @ScreamZ!