Migrating from Vite

Bu kılavuz, mevcut bir Vite uygulamasını Next.js'ye taşımanıza yardımcı olacaktır.

Why Switch?

Vite'dan Next.js'ye geçmek istemeniz için çeşitli nedenler vardır:

Slow initial page loading time

Uygulamanızı React için varsayılan Vite eklentisi ile oluşturduysanız , uygulamanız tamamen istemci taraflı bir uygulamadır. Tek sayfalı uygulamalar (SPA'lar) olarak da bilinen yalnızca istemci tarafı uygulamalar, genellikle yavaş ilk sayfa yükleme süresiyle karşılaşır. Bunun birkaç nedeni vardır:

  1. Kodunuzun bazı verileri yüklemek için istek gönderebilmesi için tarayıcının React kodunun ve tüm uygulama paketinizin indirilmesini ve çalışmasını beklemesi gerekir.
  2. Uygulama kodunuz, eklediğiniz her yeni özellik ve ekstra bağımlılıkla birlikte büyür.

No automatic code splitting

Önceki yavaş yükleme süreleri sorunu kod bölme ile bir şekilde yönetilebilir. Ancak, kod bölmeyi manuel olarak yapmaya çalışırsanız, genellikle performansı daha da kötüleştirirsiniz. Kod bölmeyi manuel olarak yaparken yanlışlıkla ağ şelaleleri oluşturmak kolaydır. Next.js, yönlendiricisinde yerleşik olarak otomatik kod bölme sağlar.

Network waterfalls

Düşük performansın yaygın bir nedeni, uygulamalar veri almak için sıralı istemci-sunucu istekleri yaptığında ortaya çıkar. Bir SPA'da veri getirme için yaygın bir model, başlangıçta bir yer tutucu oluşturmak ve ardından bileşen yüklendikten sonra veri getirmektir. Ne yazık ki bu, veri getiren bir alt bileşenin, üst bileşen kendi verilerini yüklemeyi bitirene kadar veri getirmeye başlayamayacağı anlamına gelir. Next.js ile bu sorun Sunucu Bileşenlerinde veri getirilerek çözülmüştür.

Fast and intentional loading states

Suspense ile Akış için yerleşik destek sayesinde Next.js ile, ağ şelaleleri oluşturmadan kullanıcı arayüzünüzün hangi bölümlerinin önce ve hangi sırayla yüklenmesini istediğiniz konusunda daha bilinçli olabilirsiniz. Bu, daha hızlı yüklenen sayfalar oluşturmanızı ve ayrıca düzen kaymalarını ortadan kaldırmanızı sağlar .

Choose the data fetching strategy

Next.js, ihtiyaçlarınıza bağlı olarak veri getirme stratejinizi sayfa ve bileşen bazında seçmenize olanak tanır. Verileri derleme zamanında, sunucuda istek zamanında veya istemcide getirmeye karar verebilirsiniz. Örneğin, CMS'nizden veri getirebilir ve blog yazılarınızı derleme zamanında oluşturabilir ve daha sonra bir CDN'de verimli bir şekilde önbelleğe alabilirsiniz.

Middleware

Next.js Middleware, bir istek tamamlanmadan önce sunucuda kod çalıştırmanıza olanak tanır. Bu özellikle, kullanıcı sadece kimliği doğrulanmış bir sayfayı ziyaret ettiğinde, kullanıcıyı bir oturum açma sayfasına yönlendirerek kimliği doğrulanmamış içeriğin yanıp sönmesini önlemek için kullanışlıdır. Ara katman yazılımı ayrıca deneme ve uluslararasılaştırma için de kullanışlıdır.

Built-in Optimizations

Görüntüler, yazı tipleri ve üçüncü taraf komut dosyaları genellikle bir uygulamanın performansı üzerinde önemli etkiye sahiptir. Next.js, bunları sizin için otomatik olarak optimize eden yerleşik bileşenlerle birlikte gelir.

Migration Steps

Bu geçişle amacımız, Next.js özelliklerini aşamalı olarak benimseyebilmeniz için mümkün olduğunca çabuk çalışan bir Next.js uygulaması elde etmektir. Başlangıç olarak, mevcut yönlendiricinizi taşımadan tamamen istemci tarafı bir uygulama (SPA) olarak tutacağız. Bu, geçiş işlemi sırasında sorunlarla karşılaşma olasılığını en aza indirmeye yardımcı olur ve birleştirme çakışmalarını azaltır.

Step 1: Install the Next.js Dependency

Yapmanız gereken ilk şey next adresini bir bağımlılık olarak yüklemektir:

Terminal
npm install next@latest

Step 2: Create the Next.js Configuration File

Projenizin kök dizininde bir next.config.mjs dosyası oluşturun. Bu dosyaNext.js yapılandırma seçeneklerinizi tutacaktır.

next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // Outputs a Single-Page Application (SPA).
  distDir: './dist', // Changes the build output directory to `./dist/`.
}
 
export default nextConfig

Bilmekte fayda var: Next.js yapılandırma dosyanız için .js veya .mjs adreslerini kullanabilirsiniz.

Step 3: Update TypeScript Configuration

TypeScript kullanıyorsanız, Next.js ile uyumlu hale getirmek için tsconfig.json dosyanızı aşağıdaki değişikliklerle güncellemeniz gerekir. TypeScript kullanmıyorsanız, bu adımı atlayabilirsiniz.

  1. Proje referansını adresinden kaldırın. tsconfig.node.json
  2. ./dist/types/**/*.ts ve ./next-env.d.ts adreslerini include dizisine ekleyin
  3. ./node_modules adresini exclude dizisine ekleyin
  4. { "name": "next" } adresini compilerOptions adresindekiplugins dizisine ekleyin: "plugins": [{ "name": "next" }]
  5. Set esModuleInteroptrue adresine: "esModuleInterop": true
  6. Set jsxpreserve adresine: "jsx": "preserve"
  7. Set allowJstrue adresine: "allowJs": true
  8. Set forceConsistentCasingInFileNamestrue adresine: "forceConsistentCasingInFileNames": true
  9. Set incrementaltrue adresine: "incremental": true

İşte bu değişikliklerle çalışan bir tsconfig.json örneği:

tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "preserve",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "allowJs": true,
    "forceConsistentCasingInFileNames": true,
    "incremental": true,
    "plugins": [{ "name": "next" }]
  },
  "include": ["./src", "./dist/types/**/*.ts", "./next-env.d.ts"],
  "exclude": ["./node_modules"]
}

TypeScript'i yapılandırma hakkında daha fazla bilgiyiNext.js dokümanlarında bulabilirsiniz.

Step 4: Create the Root Layout

Bir Next.js App Router uygulaması, uygulamanızdaki tüm sayfaları saracak bir React Sunucu Bileşeniolan birkök düzendosyası içermelidir. Bu dosya appdizininin en üst seviyesinde tanımlanır.

Bir Vite uygulamasındaki kök düzen dosyasına en yakın eşdeğer,<html>, <head> ve <body> etiketlerinizi içerenindex.html dosyasıdır.

Bu adımda, index.html dosyanızı bir kök düzen dosyasına dönüştüreceksiniz:

  1. src dizininizde yeni bir app dizini oluşturun.
  2. Bu app dizini içinde yeni bir layout.tsx dosyası oluşturun:
app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return null
}

Bilmekte fayda var: .js Düzen dosyaları için , .jsx veya .tsx uzantıları kullanılabilir.

  1. index.html dosyanızın içeriğini önceden oluşturulmuş <RootLayout> bileşenine kopyalayın ve body.div#root ve body.script etiketlerini <div id="root">{children}</div> ile değiştirin:
app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <link rel="icon" type="image/svg+xml" href="/icon.svg" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>My App</title>
        <meta name="description" content="My App is a..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}
  1. Next.js zaten varsayılan olarakmeta charset vemeta viewport etiketlerini içerir, bu nedenle bunları <head> adresinizden güvenle kaldırabilirsiniz:
app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <head>
        <link rel="icon" type="image/svg+xml" href="/icon.svg" />
        <title>My App</title>
        <meta name="description" content="My App is a..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}
  1. favicon.ico, icon.png, robots.txt gibi meta veri dosyaları, app dizininin en üst seviyesine yerleştirdiğiniz sürece otomatik olarak<head> etiketine eklenir.Desteklenen tüm dosyaları app dizinine taşıdıktan sonra <link> etiketlerini güvenle silebilirsiniz:
app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <head>
        <title>My App</title>
        <meta name="description" content="My App is a..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}
  1. Son olarak Next.js,Metadata API ile son <head> etiketlerinizi yönetebilir. Son meta veri bilgilerinizi dışa aktarılan birmetadata nesnesine taşıyın:
app/layout.tsx
import type { Metadata } from 'next'
 
export const metadata: Metadata = {
  title: 'My App',
  description: 'My App is a...',
}
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}

Yukarıdaki değişikliklerle, her şeyi index.html adresinizde bildirmekten Next.js'nin çerçevede yerleşik olan kural tabanlı yaklaşımını(Metadata API) kullanmaya geçtiniz. Bu yaklaşım, sayfalarınızın SEO'sunu ve web'de paylaşılabilirliğini daha kolay geliştirmenizi sağlar.

Step 5: Create the Entrypoint Page

Next.js'de bir page.tsx dosyası oluşturarak uygulamanız için bir giriş noktası bildirirsiniz. Bu dosyanın Vite'daki en yakın karşılığı main.tsx dosyanızdır. Bu adımda, uygulamanızın giriş noktasını ayarlayacaksınız.

  1. app dizininizde bir [[...slug]] dizini oluşturun.

Bu kılavuzda ilk olarak Next.js'imizi bir SPA (Tek Sayfa Uygulaması) olarak kurmayı hedeflediğimizden, uygulamanızın tüm olası rotalarını yakalamak için sayfa giriş noktanıza ihtiyacınız vardır. Bunun için app dizininizde yeni bir [[...slug]] dizini oluşturun.

Bu dizin,isteğe bağlı her şeyi yakalayan rota segmenti olarak adlandırılır. Next.js,rotaları tanımlamak için dizinlerin kullanıldığı dosya sistemi tabanlı bir yönlendirici kullanır. Bu özel dizin, uygulamanızın tüm rotalarının page.tsx dosyasını içeren dosyaya yönlendirilmesini sağlayacaktır.

  1. app/[[...slug]] dizini içinde aşağıdaki içeriğe sahip yeni bir page.tsx dosyası oluşturun:
app/[[...slug]]/page.tsx
'use client'
 
import dynamic from 'next/dynamic'
import '../../index.css'
 
const App = dynamic(() => import('../../App'), { ssr: false })
 
export default function Page() {
  return <App />
}

Bilmekte fayda var: .js Sayfa dosyaları için , .jsx veya .tsx uzantıları kullanılabilir.

Bu dosya, 'use client'yönergesi tarafındanİstemci Bileşeni olarak işaretlenen bir <Page> bileşeni içerir. Bu yönerge olmasaydı, bileşen birSunucu Bileşeni olurdu.

Next.js'de, İstemci Bileşenleri istemciye gönderilmeden önce sunucuda HTML'ye önceden oluşturulur, ancak ilk olarak tamamen istemci tarafı bir uygulamaya sahip olmak istediğimizden, Next.js'ye ssr seçeneğini false olarak ayarlayarak dinamik olarak içe aktararak <App> bileşeni için ön oluşturmayı devre dışı bırakmasını söylemeniz gerekir:

const App = dynamic(() => import('../../App'), { ssr: false })

Step 6: Update Static Image Imports

Next.js, statik görüntü içe aktarımlarını Vite'dan biraz farklı şekilde ele alır. Vite ile, bir görüntü dosyası içe aktarıldığında, genel URL'si bir dize olarak döndürülür:

App.tsx
import image from './img.png' // `image` will be '/assets/img.2d8efhg.png' in production
 
export default function App() {
  return <img src={image} />
}

Next.js ile statik görüntü içe aktarımları bir nesne döndürür. Nesne daha sonra doğrudan Next.js <Image> bileşeniyle kullanılabilir veya nesneninsrc özelliğini mevcut <img> etiketinizle kullanabilirsiniz.

<Image> bileşeniotomatik görüntü optimizasyonunun ek avantajlarına sahiptir. <Image> bileşeni, ortaya çıkan <img> 'un width ve height niteliklerini görüntünün boyutlarına göre otomatik olarak ayarlar. Bu, görüntü yüklendiğinde düzen kaymalarını önler. Ancak, uygulamanızda boyutlarından yalnızca biri auto olarak stilize edilmemiş görüntüler varsa bu durum sorunlara neden olabilir. auto olarak stilize edilmediğinde, boyut varsayılan olarak <img> boyut özniteliğinin değerini alır ve bu da görüntünün bozuk görünmesine neden olabilir.

<img> etiketini korumak, uygulamanızdaki değişiklik miktarını azaltacak ve yukarıdaki sorunları önleyecektir. Ancak, otomatik optimizasyonlardan yararlanmak için daha sonra <Image> bileşenine geçmek isteyeceksiniz.

  1. /public adresinden içe aktarılan görüntüler için mutlak içe aktarma yollarını göreli içe aktarmalara dönüştürün:
// Before
import logo from '/logo.png'
 
// After
import logo from '../public/logo.png'
  1. <img> etiketinize tüm resim nesnesi yerine src özelliğini aktarın:
// Before
<img src={logo} />
 
// After
<img src={logo.src} />

Uyarı: TypeScript kullanıyorsanız, srcözelliğine erişirken tür hatalarıyla karşılaşabilirsiniz. Bunları şimdilik görmezden gelebilirsiniz. Bu kılavuzun sonunda düzeltileceklerdir.

Step 7: Migrate the Environment Variables

Next.js, Vite'a benzer şekilde .envortam değişkenleriiçin desteğe sahiptir. Temel fark, istemci tarafında ortam değişkenlerini ortaya çıkarmak için kullanılan önektir.

Vite, Next.js tarafından desteklenmeyen özel import.meta.env nesnesi üzerinde birkaç yerleşik ortam değişkeni sunar. Kullanımlarını aşağıdaki gibi güncellemeniz gerekir:

Next.js ayrıca yerleşik bir BASE_URL ortam değişkeni sağlamaz. Ancak, ihtiyacınız varsa yine de bir tane yapılandırabilirsiniz:

  1. Aşağıdakileri .env dosyanıza ekleyin:
.env
# ...
NEXT_PUBLIC_BASE_PATH="/some-base-path"
  1. next.config.mjs dosyanızda basePath adresini process.env.NEXT_PUBLIC_BASE_PATH olarak ayarlayın:
next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // Outputs a Single-Page Application (SPA).
  distDir: './dist', // Changes the build output directory to `./dist/`.
  basePath: process.env.NEXT_PUBLIC_BASE_PATH, // Sets the base path to `/some-base-path`.
}
 
export default nextConfig
  1. import.meta.env.BASE_URL kullanımlarını şu şekilde güncelleyin process.env.NEXT_PUBLIC_BASE_PATH

Step 8: Update Scripts in package.json

Next.js'ye başarıyla geçip geçmediğinizi test etmek için artık uygulamanızı çalıştırabilmeniz gerekir. Ancak bundan önce, package.json adresinizdeki scripts adresinizi Next.js ile ilgili komutlarla güncellemeniz ve .next ve next-env.d.ts adreslerini .gitignore adresinize eklemeniz gerekir:

package.json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}
.gitignore
# ...
.next
next-env.d.ts

Şimdi npm run dev adresini çalıştırın ve http://localhost:3000. Umarım uygulamanızın Next.js üzerinde çalıştığını görürsünüz.

Uygulamanız geleneksel bir Vite yapılandırmasını takip ediyorsa, uygulamanızın çalışan bir sürümüne sahip olmak için yapmanız gereken tek şey budur.

Örnek: Next.js'ye taşınmış bir Vite uygulamasının çalışan bir örneği için bu çekme isteğine göz atın.

Step 9: Clean Up

Artık kod tabanınızı Vite ile ilgili eserlerden temizleyebilirsiniz:

Next Steps

Her şey planlandığı gibi gittiyse, artık tek sayfalık bir uygulama olarak çalışan, işlevsel bir Next.js uygulamanız var demektir. Bununla birlikte, henüz Next.js'nin avantajlarının çoğundan yararlanmıyorsunuz, ancak şimdi tüm avantajlardan yararlanmak için aşamalı değişiklikler yapmaya başlayabilirsiniz. İşte bundan sonra yapmak isteyebileceğiniz şeyler: