Skip to content
Source
Sign inSign up
TanStack/router
Open History to see the last commit

CONTRIBUTING.md

152 lines6.8 KB

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:
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.