Melvynx/saveit.now / .agents/skills/tanstack-migration
tanstack-migration
VerifiedUse when migrating SaveIt.now from the old Next.js app directory to TanStack Start, restoring route parity, UI parity, API parity, and verification without leaving Next.js runtime code.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.1 KB |
SKILL.md
View on GitHub---
name: tanstack-migration
description: Use when migrating SaveIt.now from the old Next.js app directory to TanStack Start, restoring route parity, UI parity, API parity, and verification without leaving Next.js runtime code.
---
# TanStack Migration
## Objective
Finish the SaveIt.now migration so `apps/web` is fully TanStack Start/Vite, with every previous route from `HEAD:apps/web/app` migrated to `apps/web/src/routes` or equivalent `src` modules.
## Hard Rules
- Do not restore `apps/web/app`, `.next`, `next.config.*`, `next-env.d.ts`, or any Next.js runtime.
- Do not add `next`, `next/link`, `next/image`, `next/navigation`, `next/server`, `next/cache`, `next-mdx-remote-client/rsc`, `next-themes`, `next-safe-action`, or `next-zod-route`.
- Do not approximate the UI. Read the old file from git history and preserve the same layout, text, components, and behavior.
- Do not leave broken footer/header links. If a visible route links to a page, that page must exist or the link must be intentionally replaced with an existing equivalent.
- Do not use em dash characters in code, copy, comments, or reports. Use a regular hyphen or rewrite the sentence.
- Do not edit unrelated files outside the assigned scope unless typecheck proves the shared file is required.
- Never revert user changes or broad migration work already present in the worktree.
## Required Inventory
Use the old Next app as source of truth:
```bash
git ls-tree -r --name-only HEAD -- apps/web/app | rg 'page\.(tsx|ts)$'
git ls-tree -r --name-only HEAD -- apps/web/app/api | rg 'route\.(tsx|ts)$'
```
Use current TanStack routes as destination:
```bash
rg --files apps/web/src/routes
```
## Migration Patterns
- `apps/web/app/(landing)/page.tsx` and `apps/web/app/(landing)/landing/page.tsx` become `apps/web/src/routes/index.tsx`.
- `apps/web/app/(landing)/pricing/page.tsx` becomes `apps/web/src/routes/pricing.tsx`.
- `apps/web/app/(landing)/tools/page.tsx` becomes `apps/web/src/routes/tools.tsx`.
- `apps/web/app/(landing)/tools/<name>/page.tsx` becomes `apps/web/src/routes/tools.<name>.tsx`, using dot route syntax.
- Dynamic routes use TanStack file params, for example `posts.$slug.tsx`, `docs.$slug.tsx`, `u.$slug.tsx`, `p.$bookmarkId.tsx`.
- API routes use TanStack server route files, for example `api.bookmarks.ts`, `api.bookmarks.$bookmarkId.ts`.
- Server-only data fetching belongs in route loaders or server route handlers, not in client components.
- Convert `Link` from `next/link` to plain `<a>` or TanStack `Link` when route params/search preservation is required.
- Convert `next/image` to `<img>` with equivalent sizing classes and alt text.
- Convert `notFound()` to a rendered not-found state or a thrown router not-found when the local pattern exists.
- Convert `redirect()` to TanStack redirect helpers in loaders or client navigation in components.
- Convert `NextRequest` and `NextResponse` to standard `Request` and `Response.json`.
- Server-only data access should use Convex functions or server helpers; do not introduce browser-only modules into server routes.
## Verification
Every migration slice must run:
```bash
cd apps/web
pnpm ts
pnpm lint
pnpm build
```
Run strict no-Next scans from repo root:
```bash
rg -n "NEXT_PUBLIC_|Next\.js|Nextjs|nextjs|next js|next/|@next|next-|better-auth/next-js|next-themes|next-zod-route|next-safe-action|NextRequest|NextResponse|from \"next|from 'next" . --glob '!node_modules/**' --glob '!.git/**' --glob '!apps/web/.output/**' --glob '!apps/web/dist/**' | rg -v "eslint-disable-next-line"
find apps/web -maxdepth 2 \( -name 'next.config.*' -o -name 'next-env.d.ts' -o -name '.next' -o -name 'app' \) -print
pnpm --filter web why next
```
Browser verify every migrated visible route in the assigned scope:
- route returns HTTP 200 or intentionally redirects when authenticated.
- page title/main heading and visible sections match the old route.
- browser console has no React runtime errors.
- linked actions still call migrated APIs.
## Report Format
Return:
- migrated routes and files
- API routes added or fixed
- verification commands and results
- browser routes checked
- remaining route gaps in the assigned scope
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |