Astro Typesafe Routes

_{Enhance your Astro development experience with rigorous type safety for every route in your application. This integration automatically generates TypeScript definitions from your project's route structure.}

Documentation • npm • GitHub

---

Features

• Astro — Compatible with version 5 and 6 of Astro.
• Typesafe — Ensures all URLs match a route in your Astro project.
• Typed Link Component — Replace your anchor links with the typesafe Link component.
• Typesafe Search Params — Support for typesafe and JSON serialized search params.
• Custom Component Support — Add type safety to custom link components.
• Zero Dependencies — No 3rd-party packages.

Prerequisites

1. Astro ^5.0.0 or ^6.0.0 is required
2. Install Typescript and Astro Check

npm i -D typescript @astrojs/check

1. Add astro check command to build script in package.json

{
  "scripts": {
    "build": "astro check && astro build"
  }
}

Installation

1. Add integration:

npx astro add astro-typesafe-routes

1. Start the Astro development server if it's not already running to run type generation:

npm run dev

Manual Installation

If automatic installation didn’t work, follow these steps:

1. Install package:

npm install astro-typesafe-routes

1. Add integration to astro.config.mjs:

import { defineConfig } from "astro/config";
import astroTypesafeRoutes from "astro-typesafe-routes";

export default defineConfig({
  integrations: [astroTypesafeRoutes()],
});

1. Start the Astro development server if it's not already running to run code generation:

npm run dev

Basic Usage

Link

Import the Link component to create a typesafe link

---
import Link from "astro-typesafe-routes/link";
---

<Link to="/blog/[postId]" params={{ postId: "1" }}>Post</Link>

Reading Params

To safely read route params with proper types, create a Route.

---
import { createRoute } from "astro-typesafe-routes/route-schema";

export const Route = createRoute({
  routeId: "/blog/[postId]",
});

const params = Route.getParams(Astro);
---

Typesafe GetStaticPaths

---
import { createRoute } from "astro-typesafe-routes/create-route";
import { z } from "astro/zod";

export const Route = createRoute({
  routeId: "/blog/[postId]",
});

export type Props = {
  content: string;
};

export const getStaticPaths = Route.createGetStaticPaths<Props>(() => {
  return [
    {
      params: {
        postId: "1",
      },
      props: {
        content: "Lorem Ipsum",
      },
    },
  ];
});
---

{Astro.props.content}

Advanced Usage

For more in-depth information and detailed usage instructions, please refer to the documentation.

Automatic Route Updates

Astro Typesafe Routes will automatically update the routeId of changed routes. If you want to disable this, you can set disableAutomaticRouteUpdates in the integration options.

export default defineConfig({
  integrations: [
    astroTypesafeRoutes({
      disableAutomaticRouteUpdates: true,
    }),
  ],
});