Typed links

[florian-lefebvre]

Body

Summary

Have a way to typecheck links.

Background & Motivation

It's easy to make mistakes when writing links: you can forget to take the base or the trailing slash into consideration, or even just mispell a route.

It would be useful to have a shorter feedback look during development and be able to cancel a build if you made a mistake.

Goals

• Be able to type links on a link basis
• Must be optional

Non goals

• Runtime checking of links

Example

Other frameworks like Nuxt or Next.js have this feature in experimental, through a feature flag:

// nuxt
// https://nuxt.com/docs/guide/going-further/experimental-features#typedpages
export default defineNuxtConfig({
  experimental: {
    typedPages: true
  }
})

// next
// https://nextjs.org/docs/app/building-your-application/configuring/typescript#statically-typed-links
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  experimental: {
    typedRoutes: true,
  },
}
 
export default nextConfig

That makes routing APIs typed, such as their <Link /> component or navigate() helpers.

I think Astro is in a different situation: we don't have such helpers. Want a link? Just use <a />. Want to navigate? Use Astro.redirect(), window.location.push() or navigate(). What I mean is that most of these APIs are not exclusively for routes owned by Astro.

We could type all those cases to be strictly typed but not fail if it's not strictly correct to account for situations where you want to point to external URLs, but defeats the whole purpose of this proposal. That would also be hard since we support many frameworks/syntaxes.

Instead, I suggest we follow the same approach as https://github.com/florian-lefebvre/astro-typed-links: we provide a helper function that is typed. It's much simpler code-wise and it allows users to opt-in instead of messing up with standard (eg. typing a href).

Until stable, it would be enabled with an experimental flag:

export default defineConfig({
	experimental: { typedLinks: true }
})

The link function would be made available through the astro:link virtual module. Here are some example usages:

import { link } from "astro:link"

link("/") // "/"
link("/a-base/about", { hash: "contact" }) // "/a-base/about#contact"
link("/[tenant]/[...slug]", { params: { tenant: "abc", slug: "foo/bar" }}) / "/abc/foo/bar"
link("/whatever/", { searchParams: { foo: "bar" /* or URLSearchParams */ }}) "/whatever/?foo=bar"

IMO an advantage of this approach is that it's agnostic: you can use it in Astro files, React, on the backend for webhooks redirect urls etc...

Note this approach allows to type any Astro route, including injected ones. That means it's fully compatible with integrations such as https://inox-tools.fryuni.dev/custom-routing by @Fryuni.

There's a tentative implementation PR at withastro/astro#12041

[Princesseuh]

I'd be +1 for typing a as well. Perhaps it'd be doable through an object shape?

a={{path: "something", ...}} much like how style works

[florian-lefebvre]

I think that could work!

[florian-lefebvre]

Other thing that has been proposed, using template literals:

type Link = '/' | `/blog/${string}`

And then extend astro/framework types for a

[florian-lefebvre]

I don't think a template literal is viable. As Luiz said, the following is possible but invalid:

type Link = '/' | `/blog/${string}/test`

const link: Link = "/blog//test"

[Fryuni]

Well, it is possible to make a type that validates the path correctly. But then I don't think the lang-server will provide any auto-complete.

[florian-lefebvre]

Have an example of what that could look like?

[Fryuni]

https://tsplay.dev/NDQROm

[florian-lefebvre]

mmh, I see you what you mean about the autocomplete. I'd very much prefer autocomplete, people will be confused otherwise

[HiDeoo]

I wonder if a type helper could also be nice, e.g. I have a <BlogLink /> component that takes an href prop and I want to type that prop so that the link matches "/blog/[...slug]" or whatever the path is.

[ascorbic]

How about typing links with template literal types instead, so each route would have a type generated such as "/blog/[...slug]" creating the type:

type TypedLink = `/blog/${string}`

You could then type links with a union of those types, as well as the route pattern itself so it would show in autocomplete. I think you may need some trickery to avoid collapsing the types:

type TypedLink = `/blog/[...slug]` | (`/blog/${string}` & {} ) | `/users/[id]` | ( `/users/${string}` & {});`

We could then update the types for <a href>, but also provide it as a type that could be imported and used directly.

[florian-lefebvre]

I brought your point a bit earlier in the conversation ;), see answers of #1026 (comment)

[ascorbic]

Not sure how I missed that!

[ematipico]

Some of us already know this, but many don't.

I think you missed the part that explains which part of the suggested API is typed 😅

[ematipico]

But typed "how"? For example, the first argument will be strongly typed with the routes of the user, and it will be updated every time the routes change.

And it's typed in a way that ts-server will offer auto completion

I believe this information is missing (or taken for granted).

[Princesseuh]

This is a stage 1 RFC, it typically does not describe the specific implementation. The high level goal is "Be able to link to other pages in a type safe way"

[ematipico]

We are both on the same page, but "type safe" doesn't give me enough information to me, without more context.

I am just asking for more context. Is the context provided by the attached links? I haven't followed them.

Sorry for playing the devil's advocate.

[Princesseuh]

Type safe as in checked by a type checker. You get completions for links, wrong links result in a type error etc.

[florian-lefebvre]

Yes exactly, it's not an IDE only thing