tldr;

fp-ts-routing is a typesafe router (an alternative to react-router, @angular/router, vue.js router, etc). video tutorial here (react)

Introduction

fp-ts-routing is a type safe string parsing library inspired by purescript-routing. It's part of the fp-ts (functional programming with type script) ecosystem.

Motivation

Framework Agnostic

fp-ts-routing has no dependence on the browser. This means that it can be used with any framework that has access to the browser window (e.g. react, angular, vue.js).

Prevents typos

react-router, @angular/router and vue.js router use string for matching route paths. They also use string for rerouting (react-router, @angular/router, vue.js router). This invites typos and leads to misbehavior when these strings don't match.

fp-ts-routing parses routes into sum types, which are validated at compile time. This eliminates the possibility of mismatches or misspellings.

Pattern Matching

With routes represented as sum types, it's easy to render according to a pattern match.

This gives users exhaustiveness checking - a helpful compile time error if users fail to render every route.

Parses Route Params to Arbitrary Types

react-router, @angular/router and vue.js router all use string for route params and queries.

fp-ts-routing allows users to parse any type they want for route params and queries - strings, integers, anything really (by way of io-ts)

Accessibility (React)

Because react-router's <Link> composes <a>, eslint-plugin-jsx-a11y (included in create-react-app) is unable to provide <Link> users proper <a> warnings (validity, content). Rather than enforce these warnings statically, the react-router team made the (understandable) decision to ignore them.

Because fp-ts-routing has no dependence on the DOM, users are able to use plain <a> tags, which can give the proper accessibility warnings.

Simplicity & Clarity of Purpose

fp-ts-routing does very little - it can parse a string to a sum type, and back again. In this author's opinion, this makes it easier to learn than, for example, react-router, which has 4 hooks, an HOC, 11 components, esoteric and strange matching logic, and many distinct but similar usages of route params.

Usage of fp-ts-routing requires learning about sum types and the browser window api. It can be an interesting case study for io-ts. These are fundamentals, and in this author's opinion, learning about them is more fruitful than learning a routing framework's arbitrary rules.

Video Tutorial

I've put together an fp-ts-routing video tutorial (38 min). It's for beginners, so don't worry, you don't need to know anything about fp-ts or io-ts. If you know basic typescript and basic react you'll be able to follow along.

The tutorial covers:

1. window.location.pathname & <a> (video)
2. window.history.pushState & popstate (video)
3. union types (video)
4. tagged union types (video)
5. fp-ts-routing (video)
6. @morphic-ts/adt (video)
7. morphic-ts-routing (video)

There are also bonus videos that cover:

• window.location.hash & history state (video)
• fp-ts-routing param & query types (video)
• @morphic-ts/adt verified (video)
• a brief history of typescript adt libraries (video)

The tutorial is free. Please consider donating if you'd like to support future planned tutorials.

If you are an experienced developer and you'd prefer to skip the tutorial, here's code for an example application that mirrors this react-router example app.