Skip to content

Commit a2424c0

Browse files
tannerlinsleySeanCassiereschiller-manuelIngramzautofix-ci[bot]
authored
feat: optional path params (#4597)
Co-authored-by: Sean Cassiere <[email protected]> Co-authored-by: Manuel Schiller <[email protected]> Co-authored-by: Indrek Ardel <[email protected]> Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
1 parent db1331f commit a2424c0

File tree

16 files changed

+4249
-62
lines changed

16 files changed

+4249
-62
lines changed

‎AI.md

Lines changed: 348 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,348 @@
1+
# AI.md
2+
3+
This file provides guidance to AI assistants when working with the TanStack Router codebase.
4+
5+
## Project Overview
6+
7+
TanStack Router is a type-safe router with built-in caching and URL state management for React and Solid applications. This monorepo contains two main products:
8+
9+
- **TanStack Router** - Core routing library with type-safe navigation, search params, and path params
10+
- **TanStack Start** - Full-stack framework built on top of TanStack Router
11+
12+
## Repository Structure
13+
14+
### Core Packages
15+
16+
**Router Core:**
17+
18+
- `router-core/` - Framework-agnostic core router logic
19+
- `react-router/` - React bindings and components
20+
- `solid-router/` - Solid bindings and components
21+
- `history/` - Browser history management
22+
23+
**Tooling:**
24+
25+
- `router-cli/` - CLI tools for code generation
26+
- `router-generator/` - Route generation utilities
27+
- `router-plugin/` - Universal bundler plugins (Vite, Webpack, ESBuild, Rspack)
28+
- `router-vite-plugin/` - Vite-specific plugin wrapper
29+
- `virtual-file-routes/` - Virtual file routing system
30+
31+
**Developer Experience:**
32+
33+
- `router-devtools/` - Router development tools
34+
- `router-devtools-core/` - Core devtools functionality
35+
- `react-router-devtools/` - React-specific devtools
36+
- `solid-router-devtools/` - Solid-specific devtools
37+
- `eslint-plugin-router/` - ESLint rules for router
38+
39+
**Adapters:**
40+
41+
- `zod-adapter/` - Zod validation adapter
42+
- `valibot-adapter/` - Valibot validation adapter
43+
- `arktype-adapter/` - ArkType validation adapter
44+
45+
**Start Framework:**
46+
47+
- `start/` - Core start framework
48+
- `react-start/` - React Start framework
49+
- `solid-start/` - Solid Start framework
50+
- `start-*` packages - Various start framework utilities
51+
52+
### Documentation
53+
54+
Documentation is organized in `docs/`:
55+
56+
- `docs/router/` - Router-specific documentation
57+
- `docs/start/` - Start framework documentation
58+
- Each has `framework/react/` and `framework/solid/` subdirectories
59+
60+
### Examples
61+
62+
Extensive examples in `examples/`:
63+
64+
- `examples/react/` - React router examples
65+
- `examples/solid/` - Solid router examples
66+
- Examples range from basic usage to complex applications
67+
68+
### Testing
69+
70+
- `e2e/` - End-to-end tests organized by framework
71+
- Individual packages have `tests/` directories
72+
- Uses Playwright for e2e testing
73+
74+
## Essential Commands
75+
76+
### Development
77+
78+
```bash
79+
# Install dependencies
80+
pnpm install
81+
82+
# Build all packages (affected only)
83+
pnpm build
84+
85+
# Build all packages (force all)
86+
pnpm build:all
87+
88+
# Development mode with watch
89+
pnpm dev
90+
91+
# Run all tests
92+
pnpm test
93+
94+
# Run tests in CI mode
95+
pnpm test:ci
96+
```
97+
98+
### Testing
99+
100+
```bash
101+
# Run unit tests
102+
pnpm test:unit
103+
104+
# Run e2e tests
105+
pnpm test:e2e
106+
107+
# Run type checking
108+
pnpm test:types
109+
110+
# Run linting
111+
pnpm test:eslint
112+
113+
# Run formatting check
114+
pnpm test:format
115+
116+
# Fix formatting
117+
pnpm prettier:write
118+
```
119+
120+
### Targeted Testing with Nx
121+
122+
```bash
123+
# Target specific package
124+
npx nx run @tanstack/react-router:test:unit
125+
npx nx run @tanstack/router-core:test:types
126+
npx nx run @tanstack/history:test:eslint
127+
128+
# Target multiple packages
129+
npx nx run-many --target=test:eslint --projects=@tanstack/history,@tanstack/router-core
130+
131+
# Run affected tests only (compares to main branch)
132+
npx nx affected --target=test:unit
133+
134+
# Exclude certain patterns
135+
npx nx run-many --target=test:unit --exclude="examples/**,e2e/**"
136+
137+
# List all available projects
138+
npx nx show projects
139+
```
140+
141+
### Granular Vitest Testing
142+
143+
For even more precise test targeting within packages:
144+
145+
```bash
146+
# Navigate to package directory first
147+
cd packages/react-router
148+
149+
# Run specific test files
150+
npx vitest run tests/link.test.tsx
151+
npx vitest run tests/ClientOnly.test.tsx tests/Scripts.test.tsx
152+
153+
# Run tests by name pattern
154+
npx vitest run tests/ClientOnly.test.tsx -t "should render fallback"
155+
npx vitest run -t "navigation" # Run all tests with "navigation" in name
156+
157+
# Exclude test patterns
158+
npx vitest run --exclude="**/*link*" tests/
159+
160+
# List available tests
161+
npx vitest list tests/link.test.tsx
162+
npx vitest list # List all tests in package
163+
164+
# Through nx (passes args to vitest)
165+
npx nx run @tanstack/react-router:test:unit -- tests/ClientOnly.test.tsx
166+
npx nx run @tanstack/react-router:test:unit -- tests/link.test.tsx tests/Scripts.test.tsx
167+
```
168+
169+
### Example Development
170+
171+
```bash
172+
# Navigate to an example
173+
cd examples/react/basic
174+
175+
# Run the example
176+
pnpm dev
177+
```
178+
179+
## Development Workflow
180+
181+
1. **Setup**: `pnpm install` and `pnpm exec playwright install`
182+
2. **Build**: `pnpm build:all` or `pnpm dev` for watch mode
183+
3. **Test**: Make changes and run relevant tests (use nx for targeted testing)
184+
4. **Examples**: Navigate to examples and run `pnpm dev` to test changes
185+
186+
### Nx-Powered Development
187+
188+
This repository uses Nx for efficient task execution:
189+
190+
- **Caching**: Nx caches task results - repeated commands are faster
191+
- **Affected**: Only runs tasks for changed code (`nx affected`)
192+
- **Targeting**: Run tasks for specific packages or combinations
193+
- **Parallel Execution**: Multiple tasks run in parallel automatically
194+
- **Dependency Management**: Nx handles build order and dependencies
195+
196+
## Code Organization
197+
198+
### Monorepo Structure
199+
200+
This is a pnpm workspace with packages organized by functionality:
201+
202+
- Core packages provide the fundamental router logic
203+
- Framework packages provide React/Solid bindings
204+
- Tool packages provide development utilities
205+
- Start packages provide full-stack framework capabilities
206+
207+
### Key Patterns
208+
209+
- **Type Safety**: Extensive use of TypeScript for type-safe routing
210+
- **Framework Agnostic**: Core logic separated from framework bindings
211+
- **Plugin Architecture**: Universal bundler plugins using unplugin
212+
- **File-based Routing**: Support for both code-based and file-based routing
213+
- **Search Params**: First-class support for type-safe search parameters
214+
215+
## Documentation Guidelines
216+
217+
- **Internal Links**: Always write relative to `docs/` folder (e.g., `./guide/data-loading`)
218+
- **Examples**: Each major feature should have corresponding examples
219+
- **Type Safety**: Document TypeScript patterns and type inference
220+
- **Framework Specific**: Separate docs for React and Solid when needed
221+
222+
## Critical Quality Checks
223+
224+
**During prompt-driven development, always run unit and type tests to ensure validity. If either of these fail, do not stop or proceed (unless you have repeatedly failed and need human intervention).**
225+
226+
**You can run these (or the ones you are working on) after each big change:**
227+
228+
```bash
229+
pnpm test:eslint # Linting
230+
pnpm test:types # TypeScript compilation
231+
pnpm test:unit # Unit tests
232+
pnpm test:build # Build verification
233+
```
234+
235+
**For comprehensive testing:**
236+
237+
```bash
238+
pnpm test:ci # Full CI test suite
239+
pnpm test:e2e # End-to-end tests
240+
```
241+
242+
**For targeted testing (recommended for efficiency):**
243+
244+
```bash
245+
# Test only affected packages
246+
npx nx affected --target=test:unit
247+
npx nx affected --target=test:types
248+
npx nx affected --target=test:eslint
249+
250+
# Test specific packages you're working on
251+
npx nx run @tanstack/react-router:test:unit
252+
npx nx run @tanstack/router-core:test:types
253+
254+
# Test specific files/functionality you're working on
255+
cd packages/react-router
256+
npx vitest run tests/link.test.tsx -t "preloading"
257+
npx vitest run tests/useNavigate.test.tsx tests/useParams.test.tsx
258+
```
259+
260+
**Pro Tips:**
261+
262+
- Use `npx vitest list` to explore available tests before running
263+
- Use `-t "pattern"` to focus on specific functionality during development
264+
- Use `--exclude` patterns to skip unrelated tests
265+
- Combine nx package targeting with vitest file targeting for maximum precision
266+
267+
## Package Dependencies
268+
269+
The monorepo uses workspace dependencies extensively:
270+
271+
- Core packages are dependencies of framework packages
272+
- Framework packages are dependencies of start packages
273+
- All packages use workspace protocol (`workspace:*`)
274+
275+
## Environment Setup
276+
277+
- **Node.js**: Required for development
278+
- **pnpm**: Package manager (required for workspace features)
279+
- **Playwright**: Required for e2e tests (`pnpm exec playwright install`)
280+
281+
## Common Tasks
282+
283+
### Adding New Routes
284+
285+
- Use file-based routing in `src/routes/` directories
286+
- Or use code-based routing with route definitions
287+
- Run route generation with CLI tools
288+
289+
### Testing Changes
290+
291+
- Build packages: `pnpm build` or `pnpm dev`
292+
- Run example apps to test functionality
293+
- Use devtools for debugging router state
294+
295+
**Available Test Targets per Package:**
296+
297+
- `test:unit` - Unit tests with Vitest
298+
- `test:types` - TypeScript compilation across multiple TS versions
299+
- `test:eslint` - Linting with ESLint
300+
- `test:build` - Build verification (publint + attw)
301+
- `test:perf` - Performance benchmarks
302+
- `build` - Package building
303+
304+
**Granular Test Targeting Strategies:**
305+
306+
1. **Package Level**: Use nx to target specific packages
307+
2. **File Level**: Use vitest directly to target specific test files
308+
3. **Test Level**: Use vitest `-t` flag to target specific test names
309+
4. **Pattern Level**: Use vitest exclude patterns to skip certain tests
310+
311+
Example workflow:
312+
313+
```bash
314+
# 1. Test specific package
315+
npx nx run @tanstack/react-router:test:unit
316+
317+
# 2. Test specific files within package
318+
cd packages/react-router && npx vitest run tests/link.test.tsx
319+
320+
# 3. Test specific functionality
321+
npx vitest run tests/link.test.tsx -t "preloading"
322+
```
323+
324+
### Documentation Updates
325+
326+
- Update relevant docs in `docs/` directory
327+
- Ensure examples reflect documentation
328+
- Test documentation links and references
329+
330+
## Framework-Specific Notes
331+
332+
### React
333+
334+
- Uses React Router components and hooks
335+
- Supports React Server Components (RSC)
336+
- Examples include React Query integration
337+
338+
### Solid
339+
340+
- Uses Solid Router components and primitives
341+
- Supports Solid Start for full-stack applications
342+
- Examples include Solid Query integration
343+
344+
## References
345+
346+
- Main Documentation: https://tanstack.com/router
347+
- GitHub Repository: https://github.com/TanStack/router
348+
- Discord Community: https://discord.com/invite/WrRKjPJ

0 commit comments

Comments
 (0)