السلسلة: هذا الدرس جزء من سلسلة TanStack. اقرأ المقال الرئيسي.
TanStack Start v1 دخل Release Candidate في ربيع 2026 ويُقدّم أخيراً جواباً حديثاً، type-safe ومبنياً على Vite لرفع React SSR، بلا ثقل Next.js وبلا سحر Remix الخفي. هذا الدرس يُوجَّه لمطوّر يعرف React لكنه لم يلمس TanStack Router أو Start من قبل. ستثبّت starter رسمي، تفهم البنية، تكتب أول route، تطلق dev server، تتحقق من HTML بـ curl، ثم تنتج build إنتاجي.
المتطلبات
- Node.js 20.19+ أو Node 22 LTS موصى به (
node -v) - npm 10+، pnpm 9+ أو bun 1.1+
- محرّر بدعم TypeScript أصلي
- المستوى: مرتاح مع React، JSX، npm scripts
- 35-50 دقيقة
الخطوة 1 — تحقّق من Node والـ package manager
RC لـ TanStack Start يتطلب Node 20.19 أدنى بسبب modules ESM التي يستخدمها Vite 7. كثير من البيئات لا تزال على Node 18 — يولّد أخطاء غامضة في أول npm run dev.
node -v
npm -v
# إن كان Node < 20.19، حدّث عبر nvm
nvm install 22
nvm use 22الخطوة 2 — إنشاء المشروع بـ CLI الرسمي
الطريقة الموصى بها في 2026 هي create-tanstack:
npm create tanstack@latest boutique-appالأداة تطرح أسئلة تفاعلية: اختر React، Start (لا Router وحده)، TypeScript مفعَّل، Vite، واقبل تضمين TanStack Query.
الخطوة 3 — قراءة وفهم البنية المولَّدة
boutique-app/
├── src/
│ ├── routes/
│ │ ├── __root.tsx # Layout جذر
│ │ └── index.tsx # Route /
│ ├── router.tsx # إنشاء instance router
│ ├── routeTree.gen.ts # مولَّد، لا تعدّل
│ ├── client.tsx # دخول client (hydration)
│ └── ssr.tsx # دخول خادم
├── public/
├── vite.config.ts
├── tsconfig.json
├── package.json
└── app.config.ts # اختياري حسب الإصدارالقاعدة الذهبية: تكتب routes في src/routes، لا تلمس أبداً routeTree.gen.ts. الملحق يُعيد توليده عند كل حفظ. الفصل client.tsx وssr.tsx هو ما يميّز Start عن Router بسيط جانب العميل.
الخطوة 4 — فحص package.json وvite.config.ts
{
"name": "boutique-app",
"private": true,
"type": "module",
"scripts": {
"dev": "vite dev --port 3000",
"build": "vite build",
"start": "node .output/server/index.mjs"
},
"dependencies": {
"@tanstack/react-router": "^1.169.0",
"@tanstack/react-start": "^1.167.0",
"react": "^19.0.0",
"react-dom": "^19.0.0"
},
"devDependencies": {
"@tanstack/router-plugin": "^1.167.0",
"@vitejs/plugin-react": "^4.3.0",
"@tanstack/react-router-devtools": "^1.169.0",
"typescript": "^5.6.0",
"vite": "^7.0.0"
}
}// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { tanstackRouter } from '@tanstack/router-plugin/vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
export default defineConfig({
plugins: [
tanstackRouter({ target: 'react', autoCodeSplitting: true }),
tanstackStart(),
react(),
],
})ترتيب الـ plugins مهمّ. tanstackRouter يجب تسجيله قبل react() وإلا توليد شجرة routes قد يفقد ملفات. autoCodeSplitting: true يُفعّل تقسيم آلي لكل route.
الخطوة 5 — كتابة route الجذر __root.tsx
// src/routes/__root.tsx
import { createRootRoute, Outlet, HeadContent, Scripts } from '@tanstack/react-router'
export const Route = createRootRoute({
head: () => ({
meta: [
{ charSet: 'utf-8' },
{ name: 'viewport', content: 'width=device-width, initial-scale=1' },
{ title: 'Boutique App' },
],
}),
component: RootComponent,
})
function RootComponent() {
return (
<html lang="fr">
<head>
<HeadContent />
</head>
<body>
<Outlet />
<Scripts />
</body>
</html>
)
}HeadContent يعرض العنوان وmeta المُعلَنة. Scripts يحقن scripts الـ hydration. Outlet هو slot حيث تُعرَض routes الأبناء. بدون Scripts، HTML يُخدَم لكن لا تفاعلية React تنطلق على العميل.
الخطوة 6 — إنشاء أول route index.tsx
// src/routes/index.tsx
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/')({
component: HomePage,
})
function HomePage() {
return (
<main style={{ padding: '2rem', fontFamily: 'system-ui' }}>
<h1>Bonjour depuis TanStack Start</h1>
<p>Premier rendu SSR fonctionnel.</p>
</main>
)
}الاصطلاح واضح: index.tsx يخريط إلى جذر route الأمّ. الـ route تُنشَأ عبر createFileRoute الذي يأخذ المسار كسلسلة typée.
الخطوة 7 — إطلاق خادم التطوير
npm run devالمخرَج المنتظر:
VITE v7.0.x ready in 842 ms
➜ Local: http://localhost:3000/
➜ Network: use --host to exposeافتح URL. ترى العنوان «Bonjour depuis TanStack Start». تأكيد أن router وSSR وhydration تعمل. إن كانت الصفحة بيضاء، افتح console — في 9 حالات من 10، import مفقود في __root.tsx أو typo في مسار createFileRoute.
الخطوة 8 — التحقق من SSR بـ curl
لا يكفي أن تُعرَض الصفحة في المتصفّح — يجب التأكد من رفع HTML خادمياً. curl لا يعرف تنفيذ JavaScript. إن احتوى HTML المُرسَل عنوانك، SSR يعمل.
curl -s http://localhost:3000/ | head -40يجب أن ترى في المخرَج سطر يحوي <h1>Bonjour depuis TanStack Start</h1>. دليل رسمي أن الخادم عرض المكوّن HTML قبل إرساله للعميل.
الخطوة 9 — إنتاج build إنتاجي
npm run build
ls .output/
# server/ public/ nitro.jsonالمجلد .output/server يحوي مدخل Node index.mjs، .output/public يستقبل assets ثابتة تُخدَم مباشرة من CDN. لتشغيل خادم الإنتاج محلياً:
node .output/server/index.mjs
# Listening on http://0.0.0.0:3000الخطوة 10 — للتعمق
عندك الآن مشروع TanStack Start v1 شغّال، مُتحقَّق منه SSR، وقادر على إنتاج build. الخطوة التالية: file-based routing مع TanStack Router للتنقل المتقدم، وQuery SSR وhydration لطبقة البيانات.
أخطاء شائعة
| الخطأ | السبب | الحل |
|---|---|---|
Cannot find module '@tanstack/react-start' |
تثبيت ناقص | احذف node_modules وpackage-lock.json، أعد npm install |
SyntaxError: Unexpected token '?' |
Node قديم (< 20.19) | حدّث Node عبر nvm |
| صفحة بيضاء، console فارغ | Scripts منسي في __root.tsx |
استورد وضع <Scripts /> في نهاية <body> |
routeTree.gen.ts غير مولَّد |
الملحق tanstackRouter سيئ الترتيب |
ضعه قبل react() في vite.config.ts |
| HMR لا يُعيد تحميل routes | ملف خارج src/routes |
تحقّق من المسار وroutesDirectory في الملحق |
| Build OK لكن 404 في prod | base URL سيء أو reverse proxy | عرّف base في vite.config.ts |
أسئلة شائعة
الفرق بين Router وStart؟ Router routeur جانب العميل (مع SSR اختياري). Start framework كامل يضيف خادم Vite، SSR، server functions، طبقة build. SPA صرف → Router يكفي. SSR → Start مطلوب.
هل React 19 إلزامي؟ Start v1 يستهدف React 19 افتراضياً ويستفيد من APIs الخادم الجديدة. على 18.3 يُقلِع لكن بعض الميزات (Suspense streaming محسَّن) لن تكون متاحة.
pnpm أو bun بدل npm؟ الثلاثة مدعومون. pnpm create tanstack@latest أو bun create tanstack@latest.
كيف ننشر build؟ مجلد .output هو livrable Nitro معياري. قابل للنشر على VPS كلاسيكي مع PM2، في container Docker، أو على Fly.io، Render، Railway، Cloudflare Workers.
هل Start جاهز للإنتاج 2026؟ RC رسمياً في الربيع 2026، API مستقرّ، إصدارات شبه يومية. كثير من الفرق تستخدمه إنتاجياً، لكن على مشروع حرج اقرأ changelog قبل ترقية ثانوية.