OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.
We use Sentry for watching for errors in our deployed application, as well as for instrumentation of our application.
## Error collection
Error collection is automatic and configured in `src/router.tsx`.
## Instrumentation
We want our server functions instrumented. So if you see a function name like `createServerFn`, you can instrument it with Sentry. You'll need to import `Sentry`:
```tsx
import * as Sentry from '@sentry/tanstackstart-react'
```
And then wrap the implementation of the server function with `Sentry.startSpan`, like so:
```tsx
Sentry.startSpan({ name: 'Requesting all the pokemon' }, async () => {
// Some lengthy operation here
await fetch('https://api.pokemon.com/data/')
})
```
# shadcn instructions
Use the latest version of Shadcn to install new components, like this command to add a button component:
```bash
pnpx shadcn@latest add button
```
# TanStack Router v1 — Routing Concepts (React) Cheat Sheet
> Quick, copy‑pastable reference for file‑based routing in TanStack Router v1 (React).
## TL;DR
* **Root route** is always matched; it wraps everything.
* **createFileRoute(path)** defines a route; the path is auto‑managed by the bundler/CLI.
* **Index routes** use a **trailing slash** (`/posts/`) to target the exact parent path.
* **Dynamic segments** use `$param` (e.g. `/posts/$postId`).
* **Splat (catch‑all)** route is a lone `$` segment, exposing `params._splat`.
* **Optional segments** use `{-$param}`.
* **Layout routes** are normal routes that render an `<Outlet/>` for children.
* **Pathless layout routes** start with `_` (e.g. `/_settingsShell`), wrap children but don’t match URL segments.
* **Non‑nested** routes suffix a segment with `_` to un-nest (e.g. `posts_.$postId.edit.tsx`).
* Prefix files/folders with `-` to **exclude** them from routing (colocation).
* Use `(group)` folders to **group** files only (no path impact).
---
## 1) Anatomy of a Route
```tsx
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/')({
component: PostsComponent,
})
```
* `createFileRoute(path)` → declare a route for this file.
* Path string is auto‑written/maintained by the bundler/CLI for type safety.
### Root Route
```tsx
import { createRootRoute } from '@tanstack/react-router'
export const Route = createRootRoute()
```
* No path; always matched; can host loaders, components, search param validation, etc.
**With context**:
```tsx
import { createRootRouteWithContext } from '@tanstack/react-router'
import type { QueryClient } from '@tanstack/react-query'
export interface MyRouterContext { queryClient: QueryClient }
export const Route = createRootRouteWithContext<MyRouterContext>()
```
---
## 2) Basic Routes
```tsx
// routes/about.tsx
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/about')({
component: () => <div>About</div>,
})
```
* Exact path match. Renders `component`.
### Index Routes (trailing slash)
```tsx
// routes/posts.index.tsx OR routes/posts/ index file
export const Route = createFileRoute('/posts/')({
component: () => <div>Please select a post!</div>,
})
```
* Matches **exactly** `/posts`. The **trailing `/`** denotes an index.
---
## 3) Dynamic Segments
```tsx
// routes/posts.$postId.tsx
export const Route = createFileRoute('/posts/$postId')({
loader: ({ params }) => fetchPost(params.postId),
component: PostComponent,
})
function PostComponent() {
const { postId } = Route.useParams()
return <div>Post ID: {postId}</div>
}
```
* `$postId` captures `123` for `/posts/123` → `{ postId: '123' }`.
* You can chain: `/posts/$postId/$revisionId` → `{ postId, revisionId }`.
### Splat / Catch‑All
```tsx
// routes/files/$.tsx
export const Route = createFileRoute('/files/$')({ component: Files })
```
* Captures the rest of the path into `params._splat` (e.g. `documents/hello-world`).
### Optional Parameters
```tsx
// routes/posts.{-$category}.tsx
export const Route = createFileRoute('/posts/{-$category}')({ component: Posts })
function Posts() {
const { category } = Route.useParams()
return <div>{category ? `Posts in ${category}` : 'All Posts'}</div>
}
```
* Matches `/posts` and `/posts/tech`.
* **Priority note:** routes with optional params are ranked lower than exact matches (e.g. `/posts/featured` beats `/posts/{-$category}`).
---
## 4) Layout & Pathless Layout Routes
### Layout Routes
```tsx
// routes/app.tsx
import { Outlet, createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/app')({ component: AppLayout })
function AppLayout() {
return (
<div>
<h1>App</h1>
<Outlet />
</div>
)
}
```
**Rendering matrix**
* `/app` → `<AppLayout>`
* `/app/dashboard` → `<AppLayout><Dashboard/>`
* `/app/settings` → `<AppLayout><Settings/>`
### Pathless Layout Routes (no URL segment)
```tsx
// routes/_shell.tsx
import { Outlet, createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/_shell')({ component: Shell })
function Shell() {
return (
<div>
<Header/>
<Outlet />
</div>
)
}
```
* File/folder name starts with `_` → doesn’t match a URL segment; wraps children.
* **Cannot** include dynamic `$param` in the pathless segment name. Use a real `$param` directory **beside** your `_shell` if needed:
```
routes/
├─ $postId/
├─ _postShell/
```
---
## 5) Non‑Nested Routes ("un-nesting")
Append `_` after a segment name to un-nest a file so it renders its own tree:
```
routes/
├─ posts.tsx
├─ posts.$postId.tsx
├─ posts_.$postId.edit.tsx // un-nested
```
**Resulting renders**
* `/posts` → `<Posts>`
* `/posts/123` → `<Posts><Post id=123>`
* `/posts/123/edit` → `<PostEditor id=123>` (not wrapped by `<Posts>`)
---
## 6) Excluding Files & Colocation
Prefix with `-` to exclude from route generation and safely colocate utilities:
```
routes/
├─ posts.tsx
├─ -posts-table.tsx // ignored
├─ -components/ // ignored
│ ├─ header.tsx // ignored
│ └─ footer.tsx // ignored
```
```tsx
import { PostsTable } from './-posts-table'
```
* Excluded entries are not added to the generated `routeTree.gen.ts`.
---
## 7) Pathless Route Group Directories
Group routes for organization only using `(group)` folders — no effect on paths or nesting:
```
routes/
├─ index.tsx
├─ (app)/
│ ├─ dashboard.tsx
│ ├─ settings.tsx
│ └─ users.tsx
├─ (auth)/
│ ├─ login.tsx
│ └─ register.tsx
```
**URLs render as** `/dashboard`, `/settings`, `/users`, `/login`, `/register`.
---
## 8) Useful APIs & Hooks
* `Route.useParams()` — typed path params for the current file route.
* `Route.useLoaderData()` — typed data returned from the current route’s `loader`.
* `<Outlet/>` — placeholder for child routes.
* (See docs for: search param validation, data loading, mutations, type safety, preloading, SSR, etc.)
---
## 9) Common File Naming Patterns (file‑based routing)
* `__root.tsx` — root route file.
* `index.tsx` or trailing `/` in `createFileRoute` — index under a segment.
* `$param.tsx` — dynamic segment.
* `$.tsx` — splat (catch‑all) segment.
* `{-$param}.tsx` — optional segment.
* `_segment.tsx` or `/_segment/route.tsx` — pathless layout route.
* `segment_.tsx` — un-nest that segment from parents.
* `-utils.tsx`, `-components/` — excluded from routing.
* `(group)/` — pathless grouping-only folder.
---
## 10) Quick Reference Examples
```tsx
// Simple loader + params + component
export const Route = createFileRoute('/users/$userId')({
loader: ({ params }) => getUser(params.userId),
component: () => {
const { userId } = Route.useParams()
const user = Route.useLoaderData()
return <UserCard id={userId} data={user} />
},
})
```
```tsx
// Layout
export const Route = createFileRoute('/dashboard')({ component: Layout })
function Layout() {
return <>
<Sidebar />
<Outlet />
</>
}
```
```tsx
// Optional + Splat combo (illustrative)
export const Route = createFileRoute('/docs/{-$section}/$')({ component: Docs })
```
---
## 11) Gotchas & Tips
* Prefer **file‑based** routing for less boilerplate and excellent type safety.
* Remember the **trailing slash** for index routes.
* Optional routes are **lower priority** than exact matches.
* Pathless layout routes **cannot** be dynamic.
* Use `-` prefix liberally to colocate non‑route code near routes.
* Use `(group)` folders to tame big route directories.
---
### Further Reading
* Route Trees, Route Matching, File‑Based Routing, Outlets, Path/Search Params, Data Loading, SSR, etc.
Happy routing! 🚦