route-codegen

route-codegen

This library generates route modules which can be used to manage client-side ( e.g. react-router, NextJS, etc. ) and server-side routing ( normal <a />).

Given a route pattern, automatically detect and generate link components to go to routes in the same app via client-side routing or routes in a different app via server-side routing. Typescript interfaces and helper functions / hooks are generated as well to make routing safe and easy.

This library can help you avoid routing errors like this:

Supports

• NextJS v9.3.4^
• React router v5^

Installation

Single app project

If you only have one app, you can install at project root:

yarn add route-codegen

Or

npm i route-codegen

Add route-codegen.yml to project root. Example:

apps:
  client:
    routes:
      login: /login
      logout: /logout
      user: /user/:id/:subview(profile|pictures)?
    routingType: ReactRouterV5 # "ReactRouterV5", "NextJS" or "Default" ( normal <a />)
    destinationDir: client/src/routes

More details about config file.

Monorepo / multi-app project

Example mono repo

If you have more than one app and want to manage all routes in one config file, you will need to run the cli command at project root. Run the following at project root or in a route manager package:

yarn add -D route-codegen

Or

npm i --save-dev route-codegen

The library contains some utility functions for the generated files. Therefore, it also needs to be installed in each app:

yarn add route-codegen

Or

npm i route-codegen

Add route-codegen.yml to project root / route manager package. Example:

apps:
  client:
    routes:
      login: /login
      logout: /logout
      user: /user/:id/:subview(profile|pictures)?
    routingType: ReactRouterV5 # "ReactRouterV5", "NextJS" or "Default" ( normal <a />)
    destinationDir: client/src/routes

  client-seo:
    routes:
      home: /
    routingType: NextJS
    destinationDir: client-seo/src/routes

  # An app without `routes` is still valid.
  # In this case, this app can still generate url to other apps
  # `generateLinkComponent`, `generateUseParams`, `generateRedirectComponent` and `generateUseRedirect` should be false to avoid generating unncessary files
  express-server:
    generateLinkComponent: false
    generateRedirectComponent: false
    generateUseParams: false
    generateUseRedirect: false
    destinationDir: server/src/routes

  # Leave out `destinationDir` if no route needs to be generated.
  # Other apps still generates routes to navigate to this app
  legacy:
    routes:
      legacyApp: /legacy/app

  # Origin can be used to prefix the URL path of certain apps.
  # ${...} Can be used to pass environment variables to the config yml
  externalApp:
    origin: https://${SUB_DOMAIN}.external.com
    routes:
      externalAppHome: /

More details about config file.

Configuration

Path parameters

Path parameter patterns are a subset of https://github.com/pillarjs/path-to-regexp:

• :path: This matches any string.
• :path?: This matches an optional string.
• :path(enum1|enum2): This only matches if path value is enum1 or enum2 for React Router V5. For others, it matches any string.
• :path(enum1|enum2)?: This only matches if path value is enum1 or enum2 for React Router V5. For others, it matches any string. This param is optional.

Customising links

If you have custom links ( e.g. to apply styling on top of underlying link components ), check out the link options doc.

Generating route modules

yarn route-codegen

Or

npx route-codegen

CLI Options

Name	Default	Description
config	route-codegen.yml	The name of the config file.
stacktrace	false	Turn on stack trace. Used to debug errors if they occur.
verbose	false	Turn on infos and logs. Used to see more information about the current run.

Example

yarn route-codegen --verbose --stacktrace --config path/to/routegen.yml

Generated files

Pattern file

Example

This file contains the pattern of a route and typescript interfaces that come with it.

Generate URL file

Exampe

This file contains a function to generate the URL of a particular route. Interfaces from the pattern files are used here to ensure type safety. This function is used in other components / functions of the route module to ensure URLs are generated the same way.

Link component

react-router v5 example

NextJS example

Default anchor example

Each routing framework has different API for their link. The generated Link component is an abstraction that handles:

• destination of a link
• URL origin e.g. https://domain.com
• path parameters
• query strings
• client-side vs server-side routing

// react-router v5 ( client-side )
<Link to="/users/100/profile?from=home" />

// NextJS ( client-side )
<Link href="/users/100/profile?from=home" />

// Normal anchor ( server-side )
<a href="/users/100/profile?from=home" />

The generated Link component has the same props so you can do the following in any app:

// Works in any app
<LinkUser path={{ id: "100" }} urlQuery={{ from: "home" }} />

Or with origin:

<LinkUser path={{ id: "100" }} urlQuery={{ from: "home" }} origin="https://domain.com" />

Redirect component

Similar to the Link component but redirects the user when mounted.

Other files

• useParams: Get dynamic params in the URL. Available for react-router and NextJS. Example

• useRedirect: Creates a function to redirect the user to a route. Example

Development

If you want to see how the codegen works, check out the development guide.