react-router-routes 0.2.0

Generate strongly-typed Python helpers (TypedDict param classes + path/url builders) from a React Router v6+ route tree so Python code can build frontend URLs safely.

Generate Typed Python URL helpers from React Router routes

Generate strongly-typed Python helpers (TypedDict param objects + overloads) from a React Router v6+ route tree. This is useful when a Python backend, worker, or test suite needs to construct URLs that stay in sync with a JavaScript/TypeScript frontend using React Router.

What you get

Given a React Router project, the CLI either:

• Runs pnpm react-router routes --json (if you pass --directory), or
• Reads a pre-generated JSON file (if you pass --json-file)

It walks the returned route objects and produces a Python module containing:

• RoutePaths Literal of every concrete route pattern (e.g. /users/:userId?, /files/*).
• Per-route TypedDict classes containing snake_case parameter keys.
• Overloaded react_router_path() to build a relative path with validation + percent-encoding.
• Overloaded react_router_url() to prepend a base URL (explicit argument or BASE_URL env var).

Installation

Requires Python 3.11+.

Using uv (recommended):

uv add react-router-routes

Or with pip:

pip install react-router-routes

Prerequisites

Your JS project must have react-router and the pnpm react-router routes --json command available (React Router v6+ data APIs). The Python process must run inside (or have access to) that project directory so the CLI can execute the command.

CLI Usage

The script entry point is named react-router-routes (see pyproject.toml).

Two ways to supply routes:

1. Have the tool invoke pnpm react-router routes --json by providing a directory:

react-router-routes ./routes_typing.py --directory ./frontend

1. Provide an existing JSON file (output of pnpm react-router routes --json):

react-router-routes ./routes_typing.py --json-file tests/react-router.json

Then import the generated module in Python code:

from routes_typing import react_router_path, react_router_url, RoutePaths

react_router_path('/users/:userId', {'user_id': 123})  # -> '/users/123'
react_router_url('/files/*', {'splat': 'docs/readme.md'}, base_url='https://example.com')

Environment Variables

• BASE_URL (optional) – If set and you omit base_url when calling react_router_url, this value is prepended. If missing the function returns the path and logs a warning.
• LOG_LEVEL (optional) – Standard Python logging level (INFO, DEBUG, etc.).

Development

Clone and install dev deps:

uv sync --group dev

Run tests:

uv run pytest

Release process

This project uses uv for building and publishing. Adjust version in pyproject.toml, then build and publish as desired.

License

MIT (see repository).