Open History to see the last commit
1# Contributing to TanStack Router
2β
3TanStack Router is a community project. Contributions to both TanStack Router and TanStack Start are welcome.
4β
5## Setup
6β
71. Clone the repository:
8β
9 ```sh
10 gh repo clone TanStack/router
11 ```
12β
132. Install [Node.js](https://nodejs.org/en/) and [pnpm](https://pnpm.io/installation). This repository requires pnpm `11.x.x` or newer.
143. Install dependencies:
15β
16 ```sh
17 pnpm install
18 ```
19β
20 This installs dependencies for the entire monorepo, including examples. Workspace dependencies are linked automatically.
21β
224. Install the Playwright browsers if you will run end-to-end tests:
23β
24 ```sh
25 pnpm exec playwright install
26 ```
27β
285. Create a branch for your changes:
29β
30 ```sh
31 git checkout -b my-new-branch
32 ```
33β
34## Before you start
35β
36- Search the [open and closed issues](https://github.com/TanStack/router/issues?q=is%3Aissue) before reporting a bug. If it has not already been reported, use the [bug report template](https://github.com/TanStack/router/issues/new?template=bug_report.yml).
37- Search the [open and closed pull requests](https://github.com/TanStack/router/pulls?q=is%3Apr) before starting work to avoid duplicating an existing contribution.
38- Pull requests that require API changes must first be proposed as an issue and receive maintainer sign-off before implementation begins.
39β
40## Pull request guidelines
41β
42Every pull request must follow the [TanStack Router pull request template](.github/pull_request_template.md). Complete its description and checklist without removing or bypassing the required sections.
43β
44- Keep each pull request focused on one change or topic. Pull requests that combine unrelated changes will be closed with a request to split them into separately reviewable contributions.
45- Write a concise description that clearly explains what changed and why. Follow the sections in the pull request template; a long, unstructured description makes a contribution harder to review.
46- Every change that affects a published package must include a changeset. Create it with `pnpm changeset`; documentation, CI, examples, and development-only changes do not require one.
47β
48## Development
49β
50- `pnpm build:all` builds all packages.
51- `pnpm build` runs the cached Nx build for affected packages.
52- `pnpm dev` builds the packages and starts the development watcher.
53β
54To run an example application, move into its directory and start its development server. For example:
55β
56```sh
57cd examples/react/basic
58pnpm dev
59```
60β
61## Testing and linting
62β
63Run the checks relevant to your changes while developing:
64β
65- `pnpm test:eslint` checks linting for affected packages.
66- `pnpm test:types` checks types for affected packages.
67- `pnpm test:unit` runs unit tests for affected packages.
68- `pnpm test:build` checks builds for affected packages.
69- `pnpm test:e2e` runs end-to-end tests and requires the Playwright browsers.
70β
71Before opening a pull request, run at least:
72β
73```sh
74pnpm test:eslint
75pnpm test:types
76pnpm test:unit
77```
78β
79To run the full CI test suite, use `pnpm test:ci`. For faster feedback, use an Nx target for a specific package or pass a test file or test name after `--`. For example:
80β
81```sh
82pnpm nx run @tanstack/react-router:test:unit -- tests/link.test.tsx
83pnpm nx run @tanstack/react-router:test:unit -- tests/link.test.tsx -t "preloading"
84```
85β
86Add appropriate unit tests for isolated behavior and end-to-end tests for browser or application workflows. Test relevant example applications when the change affects them.
87β
88## Documentation
89β
90Update the relevant documentation for user-facing changes. Documentation lives in the `docs/` directory, with separate sections for Router and Start. Use relative links within the `docs/` directory, such as `./guide/data-loading`.
91β
92The documentation sites are hosted on [tanstack.com](https://tanstack.com), which is a [TanStack Start application](https://github.com/TanStack/tanstack.com). To preview documentation changes locally, clone both repositories as siblings:
93β
94> [!NOTE]
95> The website fetches the doc pages from GitHub in production, and searches for them at `../router/docs` in development. Your local clone of `TanStack/router` needs to be in the same directory as the local clone of `TanStack/tanstack.com`.
96β
97You can follow these steps to set up the docs for local development:
98β
991. Make a new directory called `tanstack`.
100β
101```sh
102mkdir tanstack
103```
104β
1052. Enter that directory and clone the [`TanStack/router`](https://github.com/TanStack/router) and [`TanStack/tanstack.com`](https://github.com/TanStack/tanstack.com) repos.
106β
107```sh
108cd tanstack
109git clone git@github.com:TanStack/router.git
110# We probably don't need all the branches and commit history
111# from the `tanstack.com` repo, so let's just create a shallow
112# clone of the latest version of the `main` branch.
113# Read more about shallow clones here:
114# https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/#user-content-shallow-clones
115git clone git@github.com:TanStack/tanstack.com.git --depth=1 --single-branch --branch=main
116```
117β
118> [!NOTE]
119> Your `tanstack` directory should look like this:
120>
121> ```text
122> tanstack/
123> |
124> +-- router/ (<-- this directory cannot be called anything else!)
125> |
126> +-- tanstack.com/
127> ```
128β
1293. Enter the `tanstack/tanstack.com` directory, install the dependencies and run the app in dev mode:
130β
131```sh
132cd tanstack.com
133pnpm i
134# The app will run on https://localhost:3000 by default
135pnpm dev
136```
137β
1384. Now you can visit http://localhost:3000/router/latest/docs/framework/react/overview in the browser and see the changes you make in `tanstack/router/docs` there.
139β
140> [!WARNING]
141> You will need to update the `docs/(router or start)config.json` file (in `TanStack/router`) if you add a new documentation page!
142β
143## AI-assisted contributions
144β
145AI tools can be useful for exploring the codebase, drafting changes, and writing tests. They do not replace the contributor's responsibility for the result.
146β
1471. **Keep the contribution in your own voice**. Review and rewrite generated code comments, issue reports, and pull request descriptions so they reflect what you actually mean.
1482. **Keep ownership of technical decisions**. Understand every change, verify its behavior with the appropriate tests and documentation, and be ready to explain it during review.
1493. **Do not paste LLM output verbatim into the codebase or a contribution**. Treat generated text and code as a draft: check its claims, adapt it to the repository, and remove anything you cannot justify. Issues or pull requests that appear to contain unreviewed LLM output may be closed without further review.
1504. **Do not mass-submit unrelated or low-quality AI-generated pull requests**. We treat that behavior as spam and may close the pull requests, block the contributor, and report the GitHub account.
151β
152AI-assisted contributions follow the same standards for correctness, testing, documentation, and review as every other contribution.