@gamesome/route-builder

Have you ever been frustrated by not having a good way to manage your application's routes in a type-safe manner? Are you resorting to magic strings scattered throughout your codebase, and constantly breaking prod when your api server tries to redirect to a non-existing route?

@gamesome/route-builder is here to help!

You can now build your application's routes in a type-safe way with support for dynamic segments like so:

import { buildRoutes } from '@gamesome/route-builder';

const routes = buildRoutes({
  $: '/',
    user: {
      $: '/users',
      id: (userId: string) => `/${userId}`,
    },
});

routes.$; // "/"
routes.user.$; // "/users"
routes.user.id('123'); // "/users/123"

You can also get fancy by creating a branded type like so:

type UserId = string & { __brand: 'UserId' };

const routes = buildRoutes({
  user: {
    id: (userId: string) => `/${userId as UserId}`,
  },
});

routes.user.id('123'); // "/users/${UserId}"

If you need base urls in your routes you can do that as well. You configure this in the second argument to buildRoutes by passing an object with a baseUrl property. If you want both relative and absolute urls you can set inSeparateBranch to true in the same object. Per default the base url will be represented as BaseUrl in typehints, but if you want the actual string you can set fullBaseUrlInTypeHints to true.

const routes = buildRoutes(
  {
	$: '/',
	about: {
	  $: '/about',
	},
  },
  {
	baseUrl: 'https://example.com',
	inSeparateBranch: true,
	fullBaseUrlInTypeHints: true,
  }
);

routes.$; // "/"
routes.about.$; // "/about"
routes.withBaseUrl.$; // "https://example.com/"
routes.withBaseUrl.about.$; // "https://example.com/about"

Type hints

In your IDE you will see autocompletion for both static and dynamic routes. as well as hints indicating what will be generated.

Preview of the entire route tree

Preview of an entry

Custom base url

Shortened custom base url

Use cases

• More ergonomic way of routing in your frontend application
• Create a stable contract between your frontend and backend regarding frontend pages and their parameters
• Organise your ts-rest api routes in a type-safe manner (if you for some reason don't use ts-rest yet, you really should check it out! Probably works in other setups as well though)

Installation

npm install @gamesome/route-builder
# or
yarn add @gamesome/route-builder

Setup, contributing and releasing

Setup

This project uses nix. Do direnv allow in the root directory after cloning to enable the nix shell automatically. This will ensure you have the correct Node.js version and other dependencies installed.

This project uses pnpm and nx as monorepo manager. To install dependencies, run (in the root folder):

pnpm install

The project has githooks set up to make sure code is formatted and tests are run before committing. This is mainly to keep the robots in check and avoid unnecessary CI runs.

Contributing

Feel free to open issues or submit pull requests! We welcome contributions of all kinds, whether it's bug fixes, new features, or documentation improvements.

Releasing

To release a new version of the package, run the following command in the root folder:

nx release --skip-publish
nx release publish --otp=<your-npm-2fa-code>

The first command will bump the version, generate changelogs and create a git tag. The second command will publish the package to npm. Make sure to replace <your-npm-2fa-code> with your actual npm 2FA code if you have 2FA enabled on your npm account.

If you unsuccessfully run the first command, and it creates a git tag, you can delete the tag before pushing with:

git tag --delete <tag-name>

Tag name will be something like v0.0.1