Documentation Getting Started Flow - auto file gen can get users stuck
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 15.1k
- Forks
- 1.9k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 143
Description
Which project does this relate to?
Router
Describe the bug
New user follows the getting started flow "build from scratch" can get stuck with with dynamic paths "not working" because the posts.tsx which is meant to be a layout route in the example is auto filled with a page code.
There is nothing wrong with the code here it can just lead to a poor first experience of the framework.
Auto Filled posts.tsx
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/posts')({
component: RouteComponent,
})
function RouteComponent() {
return <div>Hello "/posts"!</div>
}
Potential solutions:
- Improve the documentation to clearly explain that users need to adjust the generated posts.tsx with an for dynamic routes to work; or
- Alternatively, change the auto-generated content for layout routes so it better reflects their intended use in the tutorial flow.
This would help prevent misunderstandings for first-time users.
Your Example Website or App
NA
Steps to Reproduce the Bug or Issue
How to reproduce:
- Following getting started guide
- Under Routing / Creating File Routes create the files in the order they are listed
posts.tsx -> posts/index.tsx -> posts/$postId.tsx - Check whether the dev server has auto filled the files with RouteComponents
- Navigate to localhost:3000/posts/10
Expected behavior
When dev app is running the dynamic url (posts/$postId.tsx) does not appear to be working because the posts.tsx captures all requests rather than being a layout route.
This is not a great experience for someone first exposure to the Tanstack framework.
Screenshots or Videos
Platform
NA
Additional context
No response
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the linked Routing / Creating File Routes guide and reproduce the listed file-creation order in the build-from-scratch flow, focusing on the generated posts.tsx and posts/$postId.tsx behavior. Decide whether the documentation or generated content should explain the layout-route requirement, then verify that navigating to /posts/10 is no longer confusing for a first-time user.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- react, typescript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100