File-based routing setup — Vite plugin va route generator
TanStack Router'da fayl asosidagi marshrutlash: TanStackRouterVite plagini, fayl nomlash qoidalari ($parametrlar), routeTree.gen.ts avtomatizatsiyasi va React Router bilan taqqos.
11-dars
File-based routing setup — Vite plugin va route generator
Tasavvur qiling, siz ulkan zamonaviy kutubxonada ishlaysiz. Ilgari har safar yangi kitob kelganda, kutubxonachi uni qo‘lda qalin jurnalga yozib, qaysi javonga qo‘yilganini, muallifini va qidiruv kartasini birma-bir to‘ldirib chiqardi. Agar bitta kartochka yozilmay qolsa, kitobxonlar u kitobni topa olmasdi.
Endi esa kutubxonaga aqlli skaner o‘rnatildi: siz yangi kitobni shunchaki belgilangan javonga qo‘yasiz, tizim uning nomini va joyini darhol skanerlab, butun kutubxonaning elektron qidiruv bazasiga avtomatik qo‘shib qo‘yadi.
TanStack Router’ning File-based routing (faylga asoslangan marshrutlash) tizimi aynan shu aqlli skaner kabi ishlaydi. Siz sahifalar massivini qo‘lda yozib o‘tirmaysiz — shunchaki src/routes papkasiga yangi fayl qo‘shasiz, qolgan barcha ishlarni Vite plagini va Route Generator hal qiladi.
1. Vite plaginining vazifasi (@tanstack/router-vite-plugin)
Loyiha dasturlash rejimida ishga tushganda (npm run dev) yoki kodni tahrirlab saqlaganingizda, Vite plagini orqa fonda tinimsiz quyidagi jarayonlarni bajaradi:
- Doimiy kuzatuv (File Watcher):
src/routespapkasidagi har bir o‘zgarishni (yangi fayl yaratilishi, o‘chirilishi yoki nomi o‘zgarishi) soniyaning ulushlarida aniqlaydi. - Marshrutlar tahlili (AST Parsing): Fayllarning nomlanish qoidalarini o‘rganib, ulardan URL manzillarni va ota-bola munosabatlarini aniqlaydi.
- Avtomatik generatsiya (
routeTree.gen.ts): Butun ilovangiz uchun to‘liq TypeScript turlariga ega bo‘lgan yagona daraxt faylini yangidan shakllantiradi.
flowchart LR
Dev["Dasturchi yangi fayl ochdi: src/routes/posts/$postId.tsx"] --> Watcher["TanStackRouterVite (Watcher)"]
Watcher --> Parser["Route Generator (AST tahlili)"]
Parser --> Gen["src/routeTree.gen.ts yangilandi"]
Gen --> TS["100% Type-safe Autocomplete & Navigatsiya"]
2. vite.config.ts faylida plaginni ulash
File-based routing ishlashi uchun vite.config.ts fayliga @tanstack/router-vite-plugin (yoki eng so‘nggi @tanstack/router-plugin/vite) qo‘shiladi:
// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { TanStackRouterVite } from '@tanstack/router-vite-plugin'
export default defineConfig({
plugins: [
// 1. TanStack Router plagini React plaginidan oldin turgani ma'qul
TanStackRouterVite({
routesDirectory: './src/routes', // Sahifalar joylashgan asosiy papka
generatedRouteTree: './src/routeTree.gen.ts', // Avtomatik yaratiladigan daraxt fayli
quoteStyle: 'single', // Kod generatsiyasida 'single' yoki "double" qo'shtirnoq
}),
react(),
],
})
[!TIP]
routesDirectoryvageneratedRouteTreeparametrlarini berish ixtiyoriy. Agar ko‘rsatmasangiz, standart ravishda./src/routesva./src/routeTree.gen.tsmanzillaridan foydalaniladi.
3. Fayl va papka nomlash qoidalari (Naming Conventions)
TanStack Router papka va fayllar nomidan kelib chiqib URL hosil qiladi. Quyidagi jadvalda eng asosiy qoidalar keltirilgan:
Fayl yo‘li (src/routes/...) |
Hosil bo‘ladigan URL | Turi | Izoh |
|---|---|---|---|
__root.tsx |
— | Ildiz Layout | Barcha sahifalarga umumiy layout (<Outlet /> va DevTools) |
index.tsx |
/ |
Index route | Saytning eng asosiy bosh sahifasi |
about.tsx |
/about |
Statik sahifa | Oddiy mustaqil sahifa |
posts/index.tsx |
/posts |
Bo‘lim indeksi | Postlar ro‘yxati bosh sahifasi |
posts/$postId.tsx |
/posts/:postId |
Dinamik route | $postId — URL parametri (1, abc, ...) |
posts/new.tsx |
/posts/new |
Aniq statik sahifa | Yangi post yaratish shakli |
$.tsx |
/* (Splat) |
Catch-all | Mavjud bo‘lmagan barcha manzillar (404 sahifa) |
Dinamik parametrlarda $ belgisi:
React Router’da URL parametrlari ikki nuqta bilan (:postId) yozilardi. Fayl tizimlarida (ayniqsa Windows operatsion tizimida) fayl nomiga : belgisini qo‘yish taqiqlangan.
Shu sababli TanStack Router’da o‘zgaruvchi parametrlar oldiga $ belgisi qo‘yiladi:
$userId.tsx$\to$/users/:userIdorders/$orderId/invoice.tsx$\to$/orders/:orderId/invoice
4. routeTree.gen.ts fayli nima o'zi?
Loyihangizdagi src/routeTree.gen.ts fayli to‘liq avtomatlashtirilgan bo‘lib, uning eng yuqori qismida quyidagi ogohlantirish turadi:
/* eslint-disable */
// @ts-nocheck
// This file was automatically generated by TanStack Router.
// You should NOT make any changes in this file as it will be overwritten.
[!CAUTION] Oltin qoida: Ushbu faylni hech qachon qo‘lda tahrirlamang! Har qanday o‘zgarish faylni saqlashingiz bilan plagin tomonidan qayta yozib yuboriladi. Marshrutni o‘zgartirmoqchi bo‘lsangiz,
src/routes/ichidagi fayl nomini o‘zgartiring.
Bu fayl nima vazifani bajaradi?
- Barcha fayllardagi
Routeobyektlarini import qilib oladi. - Ularni ota-bola munosabati bo‘yicha ierarxik daraxtga yig‘adi (
rootRoute.addChildren(...)). - Butun loyihada foydalaniladigan global TypeScript turlarini shakllantiradi. Natijada siz
<Link to="/posts/$postId" params={{ postId: '42' }} />deb yozganingizda IDE to‘liq xatosiz yordam beradi.
[!NOTE] Git masalasi:
routeTree.gen.tsfaylini.gitignorega qo‘shish kerakmi? Tavsiya: Uni Git-ga commit qilgan ma'qul. Bu CI/CD muhitida (Netlify, Vercel, Docker) yoki jamoadoshlaringiz kodni tortib olgandabuildjarayoni qo‘shimcha buyruqlarsiz silliq o‘tishini kafolatlaydi.
5. React Router bilan farqi
| Xususiyat | React Router (Code-based) | TanStack Router (File-based) |
|---|---|---|
| Yangi sahifa qo‘shish | Fayl ochib, uni routes massiviga qo‘lda ulab chiqish kerak |
Shunchaki src/routes papkasiga fayl tashlasangiz yetarli |
| URL xatolar ehtimoli | Massivda xato yozib qo‘yish yoki unutish juda oson | Fayl tizimi bilan URL doimo 100% sinxron |
| Parametrlar xavfsizligi | String interpolatsiya (/users/${id}) — xatolarga moyil |
Fayl nomidagi $id orqali to‘liq Type-safe |
| Katta loyihalarda boshqaruv | Bitta router fayli yuzlab qatorga aylanib ketadi | Har bir sahifa o‘z faylida alohida va toza saqlanadi |
Xulosa
- File-based routing — URL tuzilishini to‘g‘ridan-to‘g‘ri papka va fayl tizimiga bog‘laydi.
TanStackRouterViteplaginisrc/routespapkasidagi o‘zgarishlarni real vaqtda kuzatib,routeTree.gen.tsfaylini yangilab turadi.- Dinamik parametrlar uchun
$prefiksidan foydalaniladi ($postId.tsx). routeTree.gen.tsfayli qo‘lda tahrirlanmaydi, lekin CI/CD barqarorligi uchun uni Git-ga qo‘shish tavsiya etiladi.