761 lines
21 KiB
Markdown
761 lines
21 KiB
Markdown
---
|
|
description: Migrate Cloudflare Workers applications from any frontend framework to Tanstack Start while preserving infrastructure
|
|
---
|
|
|
|
# Cloudflare Workers Framework Migration to Tanstack Start
|
|
|
|
<command_purpose> Migrate existing Cloudflare Workers applications from any frontend framework (React, Next.js, Vue, Nuxt, Svelte, vanilla JS) to Tanstack Start. Preserves all Cloudflare infrastructure (Workers, bindings, wrangler.toml) while modernizing the application layer. </command_purpose>
|
|
|
|
## Introduction
|
|
|
|
<role>Framework Migration Specialist focusing on Tanstack Start migrations for Cloudflare Workers applications</role>
|
|
|
|
This command analyzes your existing Cloudflare Workers application, identifies the current framework, and creates a comprehensive migration plan to Tanstack Start while preserving all Cloudflare infrastructure.
|
|
|
|
## Prerequisites
|
|
|
|
<requirements>
|
|
- Existing Cloudflare Workers application (already deployed)
|
|
- Cloudflare account with existing bindings (KV/D1/R2/DO)
|
|
- wrangler CLI installed (`npm install -g wrangler`)
|
|
- Git repository for tracking migration
|
|
- Node.js 18+ (for Tanstack Start)
|
|
</requirements>
|
|
|
|
## Migration Source
|
|
|
|
<migration_source> #$ARGUMENTS </migration_source>
|
|
|
|
**Source frameworks supported**:
|
|
- React / Next.js (straightforward React → React migration)
|
|
- Vue 2/3 / Nuxt 2/3/4 (will convert to React)
|
|
- Svelte / SvelteKit (will convert to React)
|
|
- Vanilla JavaScript (will add React structure)
|
|
- jQuery-based apps
|
|
- Custom frameworks
|
|
|
|
**Target**: Tanstack Start (React 19 + TanStack Router + Vite) with Cloudflare Workers
|
|
|
|
**IMPORTANT**: This is a **FRAMEWORK migration** (UI layer), NOT a platform migration. All Cloudflare infrastructure (Workers, bindings, wrangler.toml) will be **PRESERVED**.
|
|
|
|
## Main Tasks
|
|
|
|
### 1. Framework Detection & Analysis
|
|
|
|
<thinking>
|
|
First, identify the current framework to understand what we're migrating from.
|
|
This informs all subsequent migration decisions.
|
|
</thinking>
|
|
|
|
#### Step 1: Detect Current Framework
|
|
|
|
**Automatic detection**:
|
|
|
|
```bash
|
|
# Check package.json for framework dependencies
|
|
if grep -q "\"react\"" package.json; then
|
|
echo "Detected: React"
|
|
FRAMEWORK="react"
|
|
if grep -q "\"next\"" package.json; then
|
|
echo "Detected: Next.js"
|
|
FRAMEWORK="nextjs"
|
|
fi
|
|
elif grep -q "\"vue\"" package.json; then
|
|
VERSION=$(jq -r '.dependencies.vue // .devDependencies.vue' package.json | sed 's/[\^~]//g' | cut -d. -f1)
|
|
echo "Detected: Vue $VERSION"
|
|
FRAMEWORK="vue$VERSION"
|
|
if grep -q "\"nuxt\"" package.json; then
|
|
NUXT_VERSION=$(jq -r '.dependencies.nuxt // .devDependencies.nuxt' package.json | sed 's/[\^~]//g' | cut -d. -f1)
|
|
echo "Detected: Nuxt $NUXT_VERSION"
|
|
FRAMEWORK="nuxt$NUXT_VERSION"
|
|
fi
|
|
elif grep -q "\"svelte\"" package.json; then
|
|
echo "Detected: Svelte"
|
|
FRAMEWORK="svelte"
|
|
if grep -q "\"@sveltejs/kit\"" package.json; then
|
|
echo "Detected: SvelteKit"
|
|
FRAMEWORK="sveltekit"
|
|
fi
|
|
elif grep -q "\"jquery\"" package.json; then
|
|
echo "Detected: jQuery"
|
|
FRAMEWORK="jquery"
|
|
else
|
|
echo "Detected: Vanilla JavaScript"
|
|
FRAMEWORK="vanilla"
|
|
fi
|
|
```
|
|
|
|
#### Step 2: Analyze Application Structure
|
|
|
|
**Discovery tasks** (run in parallel):
|
|
|
|
1. **Inventory pages/routes**
|
|
```bash
|
|
# React/Next.js
|
|
find pages -name "*.jsx" -o -name "*.tsx" 2>/dev/null | wc -l
|
|
find app -name "page.tsx" 2>/dev/null | wc -l
|
|
|
|
# React/Nuxt
|
|
find pages -name "*.vue" 2>/dev/null | wc -l
|
|
|
|
# Vanilla
|
|
find src -name "*.html" 2>/dev/null | wc -l
|
|
```
|
|
|
|
2. **Inventory components**
|
|
```bash
|
|
find components -name "*.jsx" -o -name "*.tsx" -o -name "*.vue" -o -name "*.svelte" 2>/dev/null | wc -l
|
|
```
|
|
|
|
3. **Identify state management**
|
|
```bash
|
|
# Redux/Zustand
|
|
grep -r "createStore\|configureStore\|create.*zustand" src/ 2>/dev/null
|
|
|
|
# React Query/TanStack Query
|
|
grep -r "useQuery\|QueryClient" src/ 2>/dev/null
|
|
|
|
# Zustand/Pinia
|
|
grep -r "createStore\|defineStore" src/ store/ 2>/dev/null
|
|
|
|
# Context API
|
|
grep -r "createContext\|useContext" src/ 2>/dev/null
|
|
```
|
|
|
|
4. **Identify UI dependencies**
|
|
```bash
|
|
# Check for UI frameworks
|
|
jq '.dependencies + .devDependencies | keys[]' package.json | grep -E "bootstrap|material-ui|antd|chakra|@nuxt/ui|shadcn"
|
|
```
|
|
|
|
5. **Verify Cloudflare bindings** (MUST preserve)
|
|
```bash
|
|
# Parse wrangler.toml
|
|
grep -E "^\[\[kv_namespaces\]\]|^\[\[d1_databases\]\]|^\[\[r2_buckets\]\]|^\[\[durable_objects" wrangler.toml
|
|
|
|
# List binding names
|
|
grep "binding =" wrangler.toml | awk '{print $3}' | tr -d '"'
|
|
```
|
|
|
|
#### Step 3: Generate Framework Analysis Report
|
|
|
|
<deliverable>
|
|
Comprehensive report on current framework and migration complexity
|
|
</deliverable>
|
|
|
|
```markdown
|
|
## Framework Migration Analysis Report
|
|
|
|
**Project**: [app-name]
|
|
**Current Framework**: [React / Next.js / Vue / Nuxt / etc.]
|
|
**Target Framework**: Tanstack Start (React 19 + TanStack Router)
|
|
**Cloudflare Deployment**: ✅ Already on Workers
|
|
|
|
### Current Application Inventory
|
|
|
|
**Pages/Routes**: [X] routes detected
|
|
- [List key routes]
|
|
|
|
**Components**: [Y] components detected
|
|
- Shared: [count]
|
|
- Page-specific: [count]
|
|
|
|
**State Management**: [Redux / Zustand / TanStack Query / Context / None]
|
|
**UI Dependencies**: [Material UI / Chakra / shadcn/ui / Custom CSS / None]
|
|
|
|
**API Endpoints**: [Z] server routes/endpoints
|
|
- Backend framework: [Express / Hono / Next.js API / Nuxt server]
|
|
|
|
### Cloudflare Infrastructure (PRESERVE)
|
|
|
|
**Bindings** (from wrangler.toml):
|
|
- KV namespaces: [count] ([list names])
|
|
- D1 databases: [count] ([list names])
|
|
- R2 buckets: [count] ([list names])
|
|
- Durable Objects: [count] ([list classes])
|
|
|
|
**wrangler.toml Configuration**:
|
|
```toml
|
|
[Current wrangler.toml snippet]
|
|
```
|
|
|
|
**CRITICAL**: All bindings and Workers configuration will be PRESERVED. Only the application framework will change.
|
|
|
|
### Migration Complexity
|
|
|
|
**Overall Complexity**: [Low / Medium / High]
|
|
|
|
**Complexity Factors**:
|
|
- Framework paradigm shift: [None / Small / Large]
|
|
- React → Tanstack Start: Low (same paradigm, better tooling)
|
|
- Next.js → Tanstack Start: Medium (different routing)
|
|
- React/Nuxt → Tanstack Start: High (Vue to React conversion)
|
|
- Vanilla → Tanstack Start: Medium (adding framework)
|
|
- Component count: [X components] - [Low / Medium / High]
|
|
- State management migration: [Simple / Complex]
|
|
- UI dependencies: [Easy replacement / Medium / Custom CSS (requires work)]
|
|
- API complexity: [Simple / Keep separate]
|
|
|
|
### Migration Strategy Recommendation
|
|
|
|
[Detailed strategy based on analysis]
|
|
|
|
**Approach**: [Full migration / Incremental / UI-only with separate backend]
|
|
|
|
**Timeline**: [X weeks / days]
|
|
**Estimated Effort**: [Low / Medium / High]
|
|
```
|
|
|
|
### 2. Multi-Agent Migration Planning
|
|
|
|
<thinking>
|
|
Use the tanstack-migration-specialist agent and supporting agents to create
|
|
a comprehensive migration plan.
|
|
</thinking>
|
|
|
|
#### Phase 1: Framework-Specific Analysis
|
|
|
|
1. **Task tanstack-migration-specialist(current framework and structure)**
|
|
- Analyze source framework patterns
|
|
- Map components to React + shadcn/ui equivalents
|
|
- Plan routing migration (TanStack Router file-based routing)
|
|
- Recommend state management approach (TanStack Query + Zustand)
|
|
- Design API strategy (server functions vs separate backend)
|
|
- Generate component mapping table
|
|
- Generate route mapping table
|
|
- Create implementation plan with todos
|
|
|
|
#### Phase 2: Cloudflare Infrastructure Validation (Parallel)
|
|
|
|
2. **Task binding-context-analyzer(existing wrangler.toml)**
|
|
- Parse current wrangler.toml
|
|
- Verify all bindings are valid
|
|
- Document binding usage patterns
|
|
- Ensure compatibility_date is 2025-09-15+
|
|
- Verify `remote = true` on all bindings
|
|
- Generate Env TypeScript interface
|
|
|
|
3. **Task cloudflare-architecture-strategist(current architecture)**
|
|
- Analyze if backend should stay separate or integrate
|
|
- Recommend Workers architecture (single vs multiple)
|
|
- Service binding strategy (if multi-worker)
|
|
- Assess if Tanstack Start server functions can replace existing API
|
|
|
|
#### Phase 3: Code Quality & Patterns (Parallel)
|
|
|
|
4. **Task cloudflare-pattern-specialist(current codebase)**
|
|
- Identify Workers-specific patterns to preserve
|
|
- Detect any Workers anti-patterns
|
|
- Ensure bindings usage follows best practices
|
|
|
|
5. **Task workers-runtime-guardian(current codebase)**
|
|
- Verify no Node.js APIs exist (would break in Workers)
|
|
- Check compatibility with Workers runtime
|
|
- Validate all code is Workers-compatible
|
|
|
|
### 3. Migration Plan Synthesis
|
|
|
|
<deliverable>
|
|
Detailed Tanstack Start migration plan with step-by-step instructions
|
|
</deliverable>
|
|
|
|
<critical_requirement> Present complete migration plan for user approval before starting any code changes. </critical_requirement>
|
|
|
|
The tanstack-migration-specialist agent will generate a comprehensive plan including:
|
|
|
|
**Component Migration Plan**:
|
|
| Old Component | New Component (shadcn/ui or custom) | Effort | Notes |
|
|
|--------------|-------------------------------------|--------|-------|
|
|
| `<Button>` | `<Button>` (shadcn/ui) | Low | Direct mapping |
|
|
| `<UserCard>` | `<Card>` + custom | Medium | Restructure children |
|
|
| `<Modal>` (Vue) | `<Dialog>` (shadcn/ui) | Medium | Vue → React conversion |
|
|
|
|
**Route Migration Plan**:
|
|
| Old Route | New File | Dynamic | Loaders | Notes |
|
|
|----------|---------|---------|---------|-------|
|
|
| `/` | `src/routes/index.tsx` | No | No | Home |
|
|
| `/users/:id` | `src/routes/users.$id.tsx` | Yes | Yes | Detail with data loading |
|
|
| `/api/users` | `src/routes/api/users.ts` | No | N/A | API route (server function) |
|
|
|
|
**State Management Strategy**:
|
|
- Current: [Redux / Context / Zustand / etc.]
|
|
- Target: TanStack Query (server state) + Zustand (client state)
|
|
- Migration approach: [Details]
|
|
|
|
**Data Fetching Strategy**:
|
|
- Current: [useEffect + fetch / Next.js getServerSideProps / Nuxt useAsyncData]
|
|
- Target: TanStack Router loaders + TanStack Query
|
|
- Benefits: Type-safe, automatic caching, optimistic updates
|
|
|
|
**API Strategy**:
|
|
- Current: [Express / Hono / Next.js API / Nuxt server routes]
|
|
- Recommendation: [Tanstack Start server functions / Keep separate]
|
|
- Rationale: [Why]
|
|
|
|
**Styling Strategy**:
|
|
- Current: [Material UI / Chakra / shadcn/ui / Custom CSS]
|
|
- Target: shadcn/ui + Tailwind 4
|
|
- Migration: [Component-by-component replacement]
|
|
|
|
**Implementation Phases**:
|
|
1. Setup Tanstack Start project with Cloudflare Workers preset
|
|
2. Configure wrangler.jsonc for deployment
|
|
3. Setup shadcn/ui components
|
|
4. Migrate layouts (if any)
|
|
5. Migrate routes with loaders (priority order)
|
|
6. Convert components to React (if needed)
|
|
7. Setup TanStack Query + Zustand
|
|
8. Migrate/create server functions
|
|
9. Replace UI with shadcn/ui + Tailwind 4
|
|
10. Update Cloudflare bindings in app context
|
|
11. Test & deploy
|
|
|
|
### 4. User Approval & Confirmation
|
|
|
|
<critical_requirement> MUST get explicit user approval before proceeding with any code changes. </critical_requirement>
|
|
|
|
**Present the migration plan and ask**:
|
|
|
|
```
|
|
📋 Tanstack Start Migration Plan Complete
|
|
|
|
Summary:
|
|
- Source framework: [React / Next.js / Vue / Nuxt / etc.]
|
|
- Target: Tanstack Start (React 19 + TanStack Router)
|
|
- Complexity: [Low / Medium / High]
|
|
- Timeline: [X] weeks/days
|
|
|
|
Key changes:
|
|
1. [Major change 1]
|
|
2. [Major change 2]
|
|
3. [Major change 3]
|
|
|
|
Cloudflare infrastructure:
|
|
✅ All bindings preserved (no changes)
|
|
✅ wrangler.toml configuration maintained
|
|
✅ Workers deployment unchanged
|
|
|
|
Do you want to proceed with this migration plan?
|
|
|
|
Options:
|
|
1. yes - Start Phase 1 (Setup Tanstack Start)
|
|
2. show-details - View detailed component/route mappings
|
|
3. modify - Adjust plan before starting
|
|
4. export - Save plan to .claude/todos/ for later
|
|
5. no - Cancel migration
|
|
```
|
|
|
|
### 5. Automated Migration Execution
|
|
|
|
<thinking>
|
|
Only execute if user approves. Work through phases systematically.
|
|
</thinking>
|
|
|
|
**If user says "yes"**:
|
|
|
|
1. **Create migration branch**
|
|
```bash
|
|
git checkout -b migrate-to-tanstack-start
|
|
git commit -m "chore: Create migration branch for Tanstack Start"
|
|
```
|
|
|
|
2. **Phase 1: Initialize Tanstack Start Project**
|
|
|
|
```bash
|
|
# Create new Tanstack Start app with Cloudflare preset
|
|
pnpm create @tanstack/start@latest temp-tanstack --template start-basic-cloudflare
|
|
|
|
# Copy configuration files
|
|
cp temp-tanstack/vite.config.ts ./
|
|
cp temp-tanstack/app.config.ts ./
|
|
cp temp-tanstack/tsconfig.json ./tsconfig.tanstack.json
|
|
|
|
# Install dependencies
|
|
pnpm add @tanstack/start @tanstack/react-router @tanstack/react-query zustand
|
|
pnpm add -D vinxi vite
|
|
|
|
# Setup shadcn/ui
|
|
pnpx shadcn@latest init
|
|
# Select: Tailwind 4, TypeScript, src/ directory
|
|
```
|
|
|
|
3. **Phase 2: Configure Cloudflare Workers**
|
|
|
|
Create `wrangler.jsonc`:
|
|
```jsonc
|
|
{
|
|
"name": "your-app-name",
|
|
"compatibility_date": "2025-09-15",
|
|
"main": ".output/server/index.mjs",
|
|
|
|
// PRESERVE existing bindings from old wrangler.toml
|
|
"kv_namespaces": [
|
|
// Copy from analysis report
|
|
],
|
|
"d1_databases": [
|
|
// Copy from analysis report
|
|
],
|
|
"r2_buckets": [
|
|
// Copy from analysis report
|
|
]
|
|
}
|
|
```
|
|
|
|
Update `vite.config.ts`:
|
|
```typescript
|
|
import { defineConfig } from 'vite'
|
|
import { TanStackStartVite } from '@tanstack/start/vite'
|
|
|
|
export default defineConfig({
|
|
plugins: [TanStackStartVite()],
|
|
})
|
|
```
|
|
|
|
4. **Phase 3: Migrate Routes**
|
|
|
|
For each route in the migration plan:
|
|
|
|
**Next.js `pages/users/[id].tsx` → Tanstack Start `src/routes/users.$id.tsx`**:
|
|
|
|
```tsx
|
|
// OLD (Next.js)
|
|
export async function getServerSideProps({ params }) {
|
|
const user = await fetchUser(params.id)
|
|
return { props: { user } }
|
|
}
|
|
|
|
export default function UserPage({ user }) {
|
|
return <div>{user.name}</div>
|
|
}
|
|
|
|
// NEW (Tanstack Start)
|
|
import { createFileRoute } from '@tanstack/react-router'
|
|
|
|
export const Route = createFileRoute('/users/$id')({
|
|
loader: async ({ params, context }) => {
|
|
const user = await fetchUser(params.id, context.cloudflare.env)
|
|
return { user }
|
|
},
|
|
component: UserPage,
|
|
})
|
|
|
|
function UserPage() {
|
|
const { user } = Route.useLoaderData()
|
|
return <div>{user.name}</div>
|
|
}
|
|
```
|
|
|
|
**Vue component → React component**:
|
|
|
|
```tsx
|
|
// OLD (Vue)
|
|
<div class="card">
|
|
<h2>{ title}</h2>
|
|
<p>{ description}</p>
|
|
</div>
|
|
|
|
const props = defineProps<{
|
|
title: string
|
|
description: string
|
|
}>()
|
|
|
|
// NEW (React + shadcn/ui)
|
|
import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/card'
|
|
|
|
interface CardComponentProps {
|
|
title: string
|
|
description: string
|
|
}
|
|
|
|
export function CardComponent({ title, description }: CardComponentProps) {
|
|
return (
|
|
<Card>
|
|
<CardHeader>
|
|
<CardTitle>{title}</CardTitle>
|
|
</CardHeader>
|
|
<CardContent>
|
|
<p>{description}</p>
|
|
</CardContent>
|
|
</Card>
|
|
)
|
|
}
|
|
```
|
|
|
|
5. **Phase 4: Setup State Management**
|
|
|
|
**TanStack Query setup** (`src/lib/query-client.ts`):
|
|
```typescript
|
|
import { QueryClient } from '@tanstack/react-query'
|
|
|
|
export const queryClient = new QueryClient({
|
|
defaultOptions: {
|
|
queries: {
|
|
staleTime: 60 * 1000, // 1 minute
|
|
},
|
|
},
|
|
})
|
|
```
|
|
|
|
**Zustand store** (`src/stores/ui-store.ts`):
|
|
```typescript
|
|
import { create } from 'zustand'
|
|
|
|
interface UIStore {
|
|
sidebarOpen: boolean
|
|
toggleSidebar: () => void
|
|
}
|
|
|
|
export const useUIStore = create<UIStore>((set) => ({
|
|
sidebarOpen: false,
|
|
toggleSidebar: () => set((state) => ({ sidebarOpen: !state.sidebarOpen })),
|
|
}))
|
|
```
|
|
|
|
6. **Phase 5: Setup Cloudflare Bindings Context**
|
|
|
|
Create `src/lib/cloudflare.ts`:
|
|
```typescript
|
|
export interface Env {
|
|
// PRESERVE from analysis report
|
|
MY_KV: KVNamespace
|
|
DB: D1Database
|
|
MY_BUCKET: R2Bucket
|
|
}
|
|
```
|
|
|
|
Update `app.config.ts`:
|
|
```typescript
|
|
import { defineConfig } from '@tanstack/start/config'
|
|
|
|
export default defineConfig({
|
|
server: {
|
|
preset: 'cloudflare-module',
|
|
},
|
|
})
|
|
```
|
|
|
|
7. **Phase 6: Migrate Server Functions**
|
|
|
|
```typescript
|
|
// src/routes/api/users.ts
|
|
import { createAPIFileRoute } from '@tanstack/start/api'
|
|
|
|
export const Route = createAPIFileRoute('/api/users')({
|
|
GET: async ({ request, context }) => {
|
|
const { env } = context.cloudflare
|
|
|
|
// Access Cloudflare bindings
|
|
const users = await env.DB.prepare('SELECT * FROM users').all()
|
|
|
|
return Response.json(users)
|
|
},
|
|
})
|
|
```
|
|
|
|
8. **Phase 7: Install shadcn/ui Components**
|
|
|
|
```bash
|
|
# Add commonly used components
|
|
pnpx shadcn@latest add button card dialog form input label
|
|
```
|
|
|
|
9. **Phase 8: Update Package Scripts**
|
|
|
|
Update `package.json`:
|
|
```json
|
|
{
|
|
"scripts": {
|
|
"dev": "vinxi dev",
|
|
"build": "vinxi build",
|
|
"start": "vinxi start",
|
|
"deploy": "wrangler deploy"
|
|
}
|
|
}
|
|
```
|
|
|
|
10. **Phase 9: Testing & Validation**
|
|
|
|
```bash
|
|
# Run development server
|
|
pnpm dev
|
|
|
|
# Build for production
|
|
pnpm build
|
|
|
|
# Deploy to Cloudflare Workers
|
|
wrangler deploy
|
|
```
|
|
|
|
### 6. Post-Migration Validation
|
|
|
|
<thinking>
|
|
Run comprehensive validation after migration is complete.
|
|
</thinking>
|
|
|
|
**Automated validation** (run in parallel):
|
|
|
|
1. **Task workers-runtime-guardian(migrated codebase)**
|
|
- Verify no Node.js APIs introduced
|
|
- Validate Workers runtime compatibility
|
|
- Check bundle size (< 1MB recommended)
|
|
|
|
2. **Task binding-context-analyzer(new wrangler.jsonc)**
|
|
- Verify all bindings preserved
|
|
- Check binding types match Env interface
|
|
- Validate `remote = true` on all bindings
|
|
|
|
3. **Task cloudflare-pattern-specialist(migrated codebase)**
|
|
- Verify bindings accessed correctly via context
|
|
- Check error handling patterns
|
|
- Validate security patterns
|
|
|
|
4. **Run /es-validate**
|
|
- Full validation suite
|
|
- Check for anti-patterns
|
|
- Verify design system compliance
|
|
|
|
### 7. Migration Report
|
|
|
|
<deliverable>
|
|
Final migration report with validation results and next steps
|
|
</deliverable>
|
|
|
|
```markdown
|
|
## Tanstack Start Migration Complete ✅
|
|
|
|
**Project**: [app-name]
|
|
**Migration**: [source] → Tanstack Start
|
|
**Date**: [timestamp]
|
|
|
|
### Migration Summary
|
|
|
|
**Routes migrated**: [X] / [X]
|
|
**Components converted**: [Y] / [Y]
|
|
**Server functions created**: [Z]
|
|
**Tests passing**: [All / Some / None]
|
|
|
|
### Validation Results
|
|
|
|
✅ Workers runtime compatibility verified
|
|
✅ All Cloudflare bindings preserved and functional
|
|
✅ Bundle size: [X]KB (target: < 1MB)
|
|
✅ No Node.js APIs detected
|
|
✅ Security patterns validated
|
|
|
|
### Performance Improvements
|
|
|
|
- Cold start time: [before] → [after]
|
|
- Bundle size: [before] → [after]
|
|
- Type safety: [improved with TanStack Router]
|
|
|
|
### Next Steps
|
|
|
|
1. [ ] Run full test suite: `pnpm test`
|
|
2. [ ] Deploy to preview: `wrangler deploy --env preview`
|
|
3. [ ] Verify all features work in preview
|
|
4. [ ] Deploy to production: `wrangler deploy --env production`
|
|
5. [ ] Monitor Workers metrics
|
|
6. [ ] Update documentation
|
|
|
|
### Files Changed
|
|
|
|
**Added**:
|
|
- [list new files]
|
|
|
|
**Modified**:
|
|
- [list modified files]
|
|
|
|
**Removed**:
|
|
- [list removed files]
|
|
|
|
### Rollback Plan
|
|
|
|
If issues arise:
|
|
```bash
|
|
git checkout main
|
|
git branch -D migrate-to-tanstack-start
|
|
wrangler rollback
|
|
```
|
|
```
|
|
|
|
## Framework-Specific Migration Patterns
|
|
|
|
### React/Next.js → Tanstack Start
|
|
|
|
**Complexity**: Low (same React ecosystem)
|
|
|
|
**Key mappings**:
|
|
- `pages/` → `src/routes/`
|
|
- `getServerSideProps` → Route `loader`
|
|
- `getStaticProps` → Route `loader` (cached)
|
|
- `api/` → `src/routes/api/` (server functions)
|
|
- `useEffect` + fetch → TanStack Query `useQuery`
|
|
- Context API → Zustand (for client state)
|
|
|
|
### React/Nuxt → Tanstack Start
|
|
|
|
**Complexity**: High (Vue to React conversion)
|
|
|
|
**Key mappings**:
|
|
- `{}` interpolation → `{}`
|
|
- `v-if` → `{condition && <Component />}`
|
|
- `v-for` → `.map()`
|
|
- `v-model` → `value` + `onChange`
|
|
- `defineProps` → TypeScript interface + props
|
|
- `ref()` / `reactive()` → `useState()` / `useReducer()`
|
|
- `computed()` → `useMemo()`
|
|
- `watch()` → `useEffect()`
|
|
- `useAsyncData` → TanStack Router `loader` + TanStack Query
|
|
|
|
### Vanilla JS → Tanstack Start
|
|
|
|
**Complexity**: Medium (adding full framework)
|
|
|
|
**Approach**:
|
|
1. Identify pages and routes
|
|
2. Convert HTML templates to React components
|
|
3. Convert event handlers to React patterns
|
|
4. Add type safety with TypeScript
|
|
5. Implement routing with TanStack Router
|
|
6. Add state management where needed
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
**Issue**: "Module not found: @tanstack/start"
|
|
**Solution**: Ensure you're using the correct package manager (pnpm recommended)
|
|
|
|
**Issue**: "wrangler.jsonc not recognized"
|
|
**Solution**: Update wrangler to latest version: `npm install -g wrangler@latest`
|
|
|
|
**Issue**: "Bindings not available in context"
|
|
**Solution**: Verify `app.config.ts` has correct preset: `preset: 'cloudflare-module'`
|
|
|
|
**Issue**: "Build fails with Workers runtime errors"
|
|
**Solution**: Check for Node.js APIs (fs, path, etc.) - use Workers alternatives
|
|
|
|
## Resources
|
|
|
|
- **Tanstack Start Docs**: https://tanstack.com/start/latest
|
|
- **TanStack Router Docs**: https://tanstack.com/router/latest
|
|
- **TanStack Query Docs**: https://tanstack.com/query/latest
|
|
- **shadcn/ui Docs**: https://ui.shadcn.com
|
|
- **Cloudflare Workers Docs**: https://developers.cloudflare.com/workers
|
|
- **Zustand Docs**: https://docs.pmnd.rs/zustand
|
|
|
|
## Success Metrics
|
|
|
|
Track these metrics before and after migration:
|
|
|
|
- ⚡ Cold start time (ms)
|
|
- 📦 Bundle size (KB)
|
|
- 🎯 Type safety coverage (%)
|
|
- 🚀 Lighthouse score
|
|
- 🔒 Security audit results
|
|
- 📊 Workers Analytics (requests/errors/latency)
|
|
|
|
---
|
|
|
|
**Remember**: This is a FRAMEWORK migration only. All Cloudflare infrastructure, bindings, and Workers configuration are preserved throughout the process.
|