প্রথম Application — সম্পূর্ণ টেকনিক্যাল ডিপ-ডাইভ (Series 1, Episode 02)
Episode 01-এ আমরা একটি গভীর mental model তৈরি করেছিলাম — TanStack Start আসলে কী, কেন এটি দরকার, এবং CSR, SSR, Hydration, Server Function-এর মতো ধারণাগুলো কীভাবে একসাথে কাজ করে।
এই Episode-এ আমরা তত্ত্ব থেকে বাস্তবে চলে যাচ্ছি। আমরা হাতে-কলমে একটি TanStack Start project তৈরি করব, প্রতিটি ফাইল কেন আছে এবং কী করে তা গভীরভাবে বুঝব, এবং শেষে Server Function ব্যবহার করে একটি ছোট, বাস্তব কাজ করা feature (Counter) বানাব — যা সরাসরি official documentation থেকে নেওয়া।
এই Episode শেষে আপনি যা করতে পারবেন:
router.tsx, __root.tsx,
routeTree.gen.ts, vite.config.ts) কী কাজ করে তা ব্যাখ্যা করাপ্রজেক্ট শুরু করার আগে আপনার সিস্টেমে নিচের জিনিসগুলো থাকা দরকার।
| প্রয়োজনীয়তা | কেন লাগবে |
|---|---|
| Node.js (একটি recent LTS ভার্সন) | Vite dev server এবং build tool চালানোর জন্য |
| একটি Package Manager (npm, pnpm, বা yarn) | Dependency install ও script চালানোর জন্য |
| Basic React ও JSX জ্ঞান | Route-গুলো মূলত React Component |
| Basic TypeScript পরিচিতি | TanStack Start-এর Type-safety পুরোপুরি উপভোগ করার জন্য (official docs TypeScript strongly recommend করে) |
| একটি Code Editor (যেমন VS Code) | TypeScript autocomplete ও error checking-এর সুবিধার জন্য |
TanStack-এর official documentation অনুযায়ী, একটি নতুন TanStack Start project শুরু করার কয়েকটি স্বীকৃত উপায় আছে। এই অংশে আমরা সবগুলো সংক্ষেপে দেখব, তারপর দুটো সবচেয়ে সহজ পথ গভীরভাবে অনুসরণ করব।
| উপায় | কখন ব্যবহার করবেন |
|---|---|
| TanStack Builder (AI-first setup flow) | দ্রুত, guided ভাবে একটি working project পেতে চাইলে |
TanStack CLI (npx @tanstack/cli@latest create) |
Locally scaffold করতে চাইলে, package manager ও add-on (Tailwind, ESLint) বেছে নিতে চাইলে |
Official Example ক্লোন করা (gitpick) |
একটি প্রস্তুত, কাজ করা codebase থেকে শুরু করতে চাইলে |
| Build from scratch | প্রতিটি ধাপ নিজে হাতে করে ভেতরের কাঠামো সম্পূর্ণ বুঝতে চাইলে |
Terminal খুলে যেই ফোল্ডারে project রাখতে চান সেখানে গিয়ে নিচের কমান্ড চালান:
package.json, vite.config.ts, src/routes/ সবকিছু আগে থেকেই
সঠিকভাবে configured থাকবে।
Episode 01-এ আমরা যে start-basic example দেখেছিলাম, সেটি সরাসরি ক্লোন করেও শুরু করা যায়।
এর জন্য gitpick নামের একটি টুল ব্যবহার করা হয়, যা GitHub-এর একটি বড়
repository থেকে শুধুমাত্র নির্দিষ্ট একটি subfolder ডাউনলোড করে আনে।
TanStack/router) একসাথে রাখা।
পুরো repository clone করলে অনেক অপ্রয়োজনীয় ফাইল চলে আসবে। gitpick দিয়ে আমরা শুধুমাত্র
আমাদের প্রয়োজনীয় example folder-টুকু নিয়ে আসতে পারি।
প্রতিটি লাইন কী করছে:
| লাইন | কাজ |
|---|---|
npx gitpick ... start-basic |
GitHub থেকে start-basic example folder-টি ডাউনলোড করে, একই নামের একটি নতুন
local folder তৈরি করে |
cd start-basic |
নতুন তৈরি হওয়া project folder-এর ভিতরে ঢোকা |
npm install |
package.json-এ উল্লেখিত সব dependency (React, TanStack Router/Start, Vite
ইত্যাদি) ডাউনলোড করা |
npm run dev |
Vite-এর dev server চালু করা |
start-basic এর জায়গায় অন্য কোনো official example slug (যেমন
start-basic-react-query, start-counter) দিয়েও একই কমান্ড ব্যবহার করা
যায় — TanStack-এর documentation-এ পুরো তালিকা পাওয়া যায়।
যে পথেই project তৈরি করে থাকুন (CLI বা clone), শেষে npm run dev চালানোর পর terminal-এ
একটি URL দেখানো হবে — সাধারণত:
এই URL ব্রাউজারে খুললে আপনি Episode 01-এ দেখা সেই "Welcome Home!!!" লেখাটি দেখতে পাবেন।
src/routes/ ফোল্ডার স্কেন করে Route Tree তৈরি করেছে, এবং / Route-টি
Server-এ render করে (SSR) আপনার Browser-এ পাঠিয়েছে — ঠিক যেমনটা আমরা Episode 01-এর Request
Lifecycle অংশে বিস্তারিত দেখেছিলাম।
একটি সাধারণ TanStack Start project-এর সবচেয়ে গুরুত্বপূর্ণ ফাইলগুলো নিচের মতো সাজানো থাকে (official "Build from scratch" গাইড অনুযায়ী মূল কাঠামো):
প্রতিটি ফাইলের ভূমিকা সংক্ষেপে:
| ফাইল | ভূমিকা |
|---|---|
src/routes/__root.tsx |
পুরো application-এর সবচেয়ে বাইরের layout — HTML shell, meta tag, সব Route-এর common wrapper |
src/routes/index.tsx |
"/" URL-এর জন্য একটি নির্দিষ্ট Route এবং তার component |
src/router.tsx |
Router instance তৈরি করার জায়গা — caching, preloading, scroll restoration ইত্যাদি configure হয় এখানে |
src/routeTree.gen.ts |
Framework স্বয়ংক্রিয়ভাবে তৈরি করে; সব Route মিলিয়ে বানানো Route Tree এখানে থাকে |
vite.config.ts |
Vite build tool এবং TanStack Start-এর plugin এখানে configure করা হয় |
router.tsx ফাইলটি বলে দেয় — TanStack Router ঠিক কীভাবে আচরণ করবে। এটি official
"Build from scratch" গাইড থেকে নেওয়া একটি বাস্তব উদাহরণ:
লাইন ধরে ধরে ব্যাখ্যা:
import { routeTree } from './routeTree.gen'createRouter({ routeTree, ... })scrollRestoration: trueexport function getRouter()
src/routeTree.gen.ts ফাইলটি বিশেষ — এটি আপনি নিজে লেখেন না। TanStack Start-এর Vite
plugin, src/routes/ ফোল্ডার স্কেন করে স্বয়ংক্রিয়ভাবে এই ফাইলটি তৈরি ও আপডেট করে।
routeTree.gen.ts ফাইলটি হাতে এডিট করা উচিত না।
আপনি যখনই src/routes/-এ নতুন file যুক্ত/মুছে ফেলবেন, dev server চলমান থাকলে এই ফাইল
নিজে থেকেই re-generate হয়ে যাবে।
Link-এ ভুল path দিলে বা ভুল URL parameter ব্যবহার করলে
editor-এই ধরা পড়ে যায়।
সহজভাবে বলা যায়: src/routes/ ফোল্ডার হলো "source of truth" (মূল সত্য), আর
routeTree.gen.ts হলো তার থেকে তৈরি হওয়া একটি compiled/generated প্রতিফলন।
__root.tsx হলো প্রতিটি TanStack Start project-এর সবচেয়ে গুরুত্বপূর্ণ ফাইলগুলোর একটি।
এটি Episode 01-এর অংশ ৮-এ আলোচিত Route Tree-এর সবচেয়ে উপরের (root) Route। নিচে official গাইড থেকে
নেওয়া উদাহরণ:
এবার প্রতিটি অংশ আলাদা করে বুঝি:
createRootRoute({ ... })createFileRoute-এর মতোই, কিন্তু এটি বিশেষভাবে সবচেয়ে বাইরের Root Route তৈরি করার জন্য।
এখানে কোনো URL path লাগে না, কারণ এটি সব Route-এর "parent"।head: () => ({ meta: [...] })<head>-এ কী কী meta tag থাকবে (charset, viewport, title) তা এখানে
define করা হয়।<HeadContent />head config অনুযায়ী আসল <meta>/<title>
ট্যাগগুলো এই জায়গায় render হয়। এটি একটি বিশেষ component যা TanStack Router নিজেই দেয়।<Outlet />index.tsx-এর Home) render হয়ে বসবে।<Scripts /><script> ট্যাগ এখানে যুক্ত হয়। এটাই সেই
script যা Episode 01-এর Request Lifecycle-এ Hydration শুরু করে।
<html>, <head>,
<body> ট্যাগ লেখা হচ্ছে। এর কারণ, TanStack Start-এ Root Route পুরো HTML document-এর
জন্য দায়ী — অন্য কোনো normal Route-এ এগুলো লেখার দরকার নেই, তারা শুধু <Outlet />-এর
ভিতরে বসে।
TanStack Start, Vite (বা Rsbuild)-এর একটি plugin হিসেবে কাজ করে। নিচে official গাইডের একটি সরলীকৃত configuration:
tanstackStart()src/routes/ ফোল্ডার স্কেন করে Route Tree তৈরি করে,
Server Function-গুলোর জন্য Client/Server bundle আলাদা করে দেয় (Episode 01-এর অংশ ১৩-এ আলোচিত
"network boundary"), এবং SSR entry point তৈরি করে।viteReact()tanstackStart()-এর পরে রাখতে হয়, কারণ plugin-গুলো একটি নির্দিষ্ট ক্রমে
কাজ করে।resolve: { tsconfigPaths: true }tsconfig.json-এ define করা path alias (যদি থাকে) Vite যেন বুঝতে পারে তা নিশ্চিত করে।
এখন পর্যন্ত আমরা যা দেখেছি তা মূলত static content। এবার Episode 01-এর অংশ ১৩-এ আলোচিত Server Function বাস্তবে কীভাবে ব্যবহার হয় তা দেখি — TanStack-এর official "Build from scratch" গাইডের একটি সম্পূর্ণ, কাজ করা উদাহরণ দিয়ে।
চলুন এই কোডটি অংশ ধরে ধরে বুঝি — এটি এই Episode-এর সবচেয়ে গুরুত্বপূর্ণ code walkthrough।
import * as fs from 'node:fs'readCount()count.txt ফাইল থেকে বর্তমান সংখ্যাটি পড়ে আনে। ফাইল না থাকলে 0 ধরে নেয়।
getCount — createServerFn({ method: 'GET' })method: 'GET' বলছে
এটি শুধু data নিয়ে আসার জন্য (কোনো data পরিবর্তন করে না)।updateCount — createServerFn({ method: 'POST' })method: 'POST' ব্যবহার করা হয়েছে।.validator((d: number) => d)number আশা করছি"। এটি Server Function-এর input-এর জন্য একটি নিরাপত্তা স্তর।.handler(async ({ data }) => { ... })data ব্যবহার করে বর্তমান count-এর সাথে যোগ করে
ফাইলে লিখে রাখা হয়।
loader: async () => await getCount()getCount() (একটি Server Function) call হয়ে count-টি নিয়ে আসা হচ্ছে।
const state = Route.useLoaderData()loader-এর মাধ্যমে আনা data এই hook দিয়ে component-এর ভিতরে পাওয়া যায়।const router = useRouter()onClick={() => { updateCount({ data: 1 }).then(...) }}updateCount Server Function call হচ্ছে — দেখতে সাধারণ একটি async
function call-এর মতো, কিন্তু ভেতরে ভেতরে এটি Episode 01-এর অংশ ১৩-এ আলোচিত network boundary পার
হয়ে Server-এ গিয়ে ফাইল আপডেট করে আসছে।router.invalidate()getCount()) নতুন, আপডেট হওয়া count নিয়ে
আসে এবং UI নতুন সংখ্যা দেখায়।
Dev server চলার সময় কোনো Route ফাইল পরিবর্তন করে save করলে, Browser সম্পূর্ণভাবে reload না হয়েই পরিবর্তন দেখায়। এই প্রক্রিয়ার নাম HMR (Hot Module Replacement)।
src/routes/about.tsx), TanStack Start-এর plugin এটি
চিহ্নিত করে routeTree.gen.ts স্বয়ংক্রিয়ভাবে re-generate করে দেয় — আপনাকে কিছু করতে হয়
না, শুধু dev server চালু রাখতে হয়।
| সমস্যা | সম্ভাব্য কারণ ও সমাধান |
|---|---|
"routeTree.gen.ts ফাইল খুঁজে পাচ্ছি না / নেই" |
Dev server (npm run dev) অন্তত একবার চালাতে হবে, কারণ এই ফাইল প্রথম রান-এই
generate হয়। ম্যানুয়ালি তৈরি করার চেষ্টা করবেন না। |
| "পোর্ট (port) already in use" জাতীয় error | অন্য কোনো process আগে থেকেই সেই port (যেমন 3000) ব্যবহার করছে। আগের terminal/process বন্ধ
করুন, বা vite.config.ts-এ port পরিবর্তন করুন। |
| Route পরিবর্তন করেও ব্রাউজারে কিছু দেখাচ্ছে না | Route file export ঠিকমতো হয়েছে কিনা (export const Route = ...) এবং
component সঠিকভাবে assign করা হয়েছে কিনা যাচাই করুন। |
| TypeScript-এ অনেক red underline / error দেখাচ্ছে | tsconfig.json-এ প্রয়োজনীয় options (যেমন moduleResolution: "Bundler")
ঠিকমতো সেট করা আছে কিনা দেখুন; editor restart করাও অনেক সময় সাহায্য করে। |
| Server Function call করলে কিছু হচ্ছে না / error আসছে | .handler() ঠিকমতো লেখা হয়েছে কিনা, এবং method (GET/POST) সঠিকভাবে
ব্যবহারের জায়গার সাথে মিলছে কিনা দেখুন। |
router.tsx, routeTree.gen.ts,
__root.tsx, vite.config.ts — এর ভূমিকা গভীরভাবে বুঝলামcreateRootRoute, Outlet, HeadContent, Scripts
— এই building block-গুলো কীভাবে একসাথে পুরো HTML document তৈরি করে তা দেখলামloader,
createServerFn, validator, useRouter,
router.invalidate()এখন আমাদের হাতে একটি চলমান TanStack Start project আছে, এবং আমরা এর প্রতিটি core file কেন এবং কীভাবে কাজ করে তা জানি। পরের Episode-এ আমরা Routing System আরও গভীরভাবে explore করব।
$postId এর মতো) ব্যবহার করব, এবং Link component দিয়ে Type-safe navigation
করে দেখাব।