Next.js Routes

Type safe routing for Next.js

!nextjs-routes preview gif

What is this? 🧐

nextjs-routes generates type safe routing utilities from your pages and/or app directory.

Notice

If you are using Next.js's App Router you may not need this library. Next.js provides an experimental option to generate typed links. Next.js's option only works for the app directory, and not pages. If you're using the pages directory, or if you're using the app directory and want to use typed objects instead of string interpolation to provide URL parameters and queries, use this library.

Highlights

🦄 Zero config

💨 Types only -- zero runtime (pages directory only)

🛠 No more broken links

🪄 Route autocompletion

🔗 Supports all Next.js route types: static, dynamic, catch all and optional catch all

Installation & Usage 📦

1. Add this package to your project:

``sh
npm install nextjs-routes
# or
yarn add nextjs-routes
# or
pnpm add nextjs-routes
`

2. Update your next.config.js:

`diff
+ const nextRoutes = require("nextjs-routes/config");
+ const withRoutes = nextRoutes();

/* @type {import('next').NextConfig} /
const nextConfig = {
reactStrictMode: true,
};

- module.exports = nextConfig;
+ module.exports = withRoutes(nextConfig);
`

3. Start or build your next project:

`sh
npx next dev
# or
npx next build
`

That's it! A @types/nextjs-routes.d.ts file will be generated the first time you start your server. Check this file into version control. next/link and next/router type definitions have been augmented to verify your application's routes. No more broken links, and you get route autocompletion 🙌.

In development, whenever your routes change, your @types/nextjs-routes.d.ts file will automatically update.

If you would prefer to generate the route types file outside of next dev or next build you can also invoke the cli directly: npx nextjs-routes.

Examples 🛠

$3

Link's href prop is now typed based on your application routes:

`tsx
import Link from "next/link";

href={{
pathname: "/foos/[foo]",
query: { foo: "bar" },
}}
>
Bar
;
`

If the route doesn't require any parameters, you can also use a path string:

`tsx
Foo
`

$3

useRouter's returned router instance types for push, replace and query are now typed based on your application routes.

Identical to Link, push and replace now expect a UrlObject or path string:

#### push

`tsx
import { useRouter } from "next/router";

const router = useRouter();
router.push({ pathname: "/foos/[foo]", query: { foo: "test" } });
`

#### replace

`tsx
import { useRouter } from "next/router";

const router = useRouter();
router.replace({ pathname: "/" });
`

#### query

`tsx
import { useRouter } from "next/router";

// query is typed as a union of all query parameters defined by your application's routes
const { query } = useRouter();
`

By default, query will be typed as the union of all possible query parameters defined by your application routes. If you'd like to narrow the type to fewer routes or a single page, you can supply a type argument:

`tsx
import { useRouter } from "next/router";

const router = useRouter<"/foos/[foo]">();
// query is now typed as { foo?: string | undefined }
router.query;
`

You can further narrow the query type by checking the router's isReady property.

`tsx
import { useRouter } from "next/router";

const router = useRouter<"/foos/[foo]">();
// query is typed as { foo?: string | undefined }
router.query;

if (router.isReady) {
// query is typed as { foo: string }
router.query;
}
`

Checking isReady is necessary because of Next's Automatic Static Optimization. The router's query object will be empty for pages that are Automatic Static Optimized. After hydration, Next.js will trigger an update to your application to provide the route parameters in the query object. See Next's documentation for more information. isReady will always return true for server rendered pages.

$3

If you want to use the generated Route type in your code, you can import it from nextjs-routes:

`ts
import type { Route } from "nextjs-routes";
`

$3

If you want a type for all possible pathnames you can achieve this via Route:

`ts
import type { Route } from "nextjs-routes";

// '/' | '/foos/[foo]' | 'other-route' | ...
type Pathname = Route["pathname"];
`

$3

If you want to use the generated Query for a given Route, you can import it from nextjs-routes:

`ts
// Query | Query & { foo: string } | ...
import type { RoutedQuery } from "nextjs-routes";
`

By default, query will be typed as the union of all possible query parameters defined by your application routes. If you'd like to narrow the type to fewer routes or a single page, you can supply the path as a type argument:

`ts
// Query & { foo: string }
type FooRouteQuery = RoutedQuery<"/foos/[foo]">;
`

$3

If you're using getServerSideProps consider using GetServerSidePropsContext from nextjs-routes. This is nearly identical to GetServerSidePropsContext from next, but further narrows types based on nextjs-route's route data.

`ts
import type { GetServerSidePropsContext } from "nextjs-routes";

export function getServerSideProps(
context: GetServerSidePropsContext<"/foos/[foo]">,
) {
// context.params will include foo as a string;
const { foo } = context.params;
}
`

$3

If you're using getServerSideProps and TypeScript 4.9 or later, you can combine the satisfies operator with GetServerSideProps from nextjs-routes. This is nearly identical to GetServerSideProps from next, but further narrows types based on nextjs-route's route data.

`ts
import type { GetServerSideProps } from "nextjs-routes";

export const getServerSideProps = (async (context) => {
// context.params will include foo as a string;
const { foo } = context.params;
}) satisfies GetServerSideProps<{}, "/foos/[foo]">;
`

How does this work? 🤔

nextjs-routes generates types for the pathname and query for every page in your pages directory. The generated types are written to @types/nextjs-routes.d.ts which is automatically referenced by your Next project's tsconfig.json. @types/nextjs-routes.d.ts redefines the types for next/link and next/router and applies the generated route types.

What if I need a runtime?

There are some cases where you may want to generate a type safe path from a Route object, such as when fetching from an API route or serving redirects from getServerSideProps. These accept strings instead of the Route object that Link and useRouter accept. Because these do not perform the same string interpolation for dynamic routes, runtime code is required instead of a type only solution.

For these cases, you can use route from nextjs-routes:

$3

`ts
import { route } from "nextjs-routes";

fetch(route({ pathname: "/api/foos/[foo]", query: { foo: "foobar" } }));
`

$3

`ts
import { route, type GetServerSidePropsContext } from "nextjs-routes";

export function getServerSideProps(context: GetServerSidePropsContext) {
return {
redirect: {
destination: route({ pathname: "/foos/[foo]", query: { foo: "foobar" } }),
permanent: false,
},
};
}
`

route optionally accepts a trailingSlash:

`ts
// api/foos/foobar/
fetch(
route(
{ pathname: "/api/foos/[foo]", query: { foo: "foobar" } },
{ trailingSlash: true },
),
);
`

$3

nextjs-routes refines Link and useRouter based on your Nextjs i18n configuration.

The following next.config.js:

`js
module.exports = withRoutes({
i18n: {
defaultLocale: "de-DE",
locales: ["de-DE", "en-FR", "en-US"],
},
});
`

Will type Link and useRouter's locale as 'de-DE' | 'en-FR' | 'en-US'. All other i18n properties (defaultLocale, domainLocales and locales) are also typed.

If you want to use the generated Locale type, you can import it from nextjs-routes:

`ts
import { Locale } from "nextjs-routes";
`

Configuration

You can pass the following options to nextRoutes in your next.config.js:

`js
const nextRoutes = require("nextjs-routes/config");
const withRoutes = nextRoutes({
outDir: "types",
cwd: __dirname,
});
`

- outDir: The file path indicating the output directory where the generated route types should be written to (e.g.: "types"). The default is to create the file in the same folder as your next.config.js file.

- cwd: The path to the directory that contains your next.config.js file. This is only necessary for non standard project structures, such as nx. If you are an nx user getting the Could not find a Next.js pages directory error, use cwd: __dirname.

Troubleshooting

$3

Non standard project structures, such as those using nx, require that users supply a path to their next.config.js. For nx, this is because nx introduces wrapping layers that invoke commands differently than using the next cli directly.

Solution:

`diff
const nextRoutes = require("nextjs-routes/config");
const withRoutes = nextRoutes({
+ cwd: __dirname
});
`

Contributing 👫

PR's and issues welcomed! For more guidance check out CONTRIBUTING.md

Are you interested in bringing a nextjs-routes` like experience to another framework? Open an issue and let's collaborate.

Licensing 📃

See the project's MIT License.