holodepth

Three.js · Geliştirme ortamı

Modern iş akışına giriş: Neden Vite?

Geleneksel web geliştirme yöntemlerinde Three.js, bir <script> etiketiyle sayfaya dahil edilirdi. Ancak projeler büyüdükçe bu yöntem yönetilemez hale gelir. İşte burada modern araçlar devreye giriyor.

Modern iş akışına giriş

Neden Vite'ı seçiyoruz?

  • Hız (The Speed) Vite, tarayıcının yerleşik ES Modules desteğini kullanır. Bu, projeniz ne kadar büyük olursa olsun, geliştirme sunucusunun milisaniyeler içinde açılması demektir.
  • HMR (Hot Module Replacement) Three.js ile çalışırken bir ışığın yoğunluğunu veya bir materyalin rengini değiştirdiğinizde, Vite tüm sayfayı yenilemek yerine sadece o değişikliği sahneye "enjekte" eder. Bu, yaratıcı süreci kesintiye uğratmaz.
  • Akıllı varlık (asset) yönetimi 3D dünyalar ağırdır. Vite; .gltf modellerini, .hdr çevre haritalarını ve dokuları (textures) otomatik olarak optimize eder, önbelleğe alır ve en hızlı şekilde tarayıcıya sunar.

Geleneksel ve modern geliştirme karşılaştırması

Özellik Geleneksel (<script> etiketi) Modern (Vite + ESM)
Yükleme hızı Tüm kütüphane tek seferde iner. Sadece kullanılan modüller iner (tree-shaking).
Geliştirme deneyimi Kod her değiştiğinde manuel sayfa yenileme. HMR ile anlık, sayfayı koruyan güncellemeler.
Organizasyon Tek dosya veya karmaşık küresel değişkenler. Temiz, modüler ve import/export tabanlı yapı.
Performans Optimizasyon manuel ve zordur. Otomatik asset optimizasyonu ve bundle yönetimi.
Hata denetimi Çalışma anında (runtime) hataları görme. TypeScript ve IntelliSense ile yazım anında hata tespiti.

Kurulum ve paket yönetimi

Bir Three.js projesinin kalbi package.json dosyasıdır. Burada sadece kodları değil, projenin tüm yaşam döngüsünü yönetiriz.

Adım adım başlangıç

Proje iskeleti: Aşağıdaki komutu kullandığımızda Vite temiz bir klasör yapısı sunar. "Vanilla JavaScript" seçeneği, Three.js'in saf gücünü anlamak için iyi bir başlangıçtır.

npm create vite@latest

Komut çalıştıktan sonra Vite etkileşimli olarak birkaç soru sorar. Verdiğiniz yanıtlar, oluşacak klasörü, package.json içeriğini ve hangi şablon dosyaların (saf JS mi, TypeScript mi, hangi çatı ile mi) üretileceğini belirler.

  • Project name — Proje klasörünün adıdır (örneğin my-three-app). Bu isimle yeni bir dizin oluşturulur; bağımlılık kurulumu ve npm run dev gibi komutları hep bu dizinin içinden çalıştırırsınız.
  • Select a framework — Vanilla seçtiğinizde ekstra UI çatısı olmadan düz JavaScript düzeni kurulur; Three.js'i doğrudan import ederek sahneyi öğrenmek için bu rehberle uyumludur. React, Vue veya Svelte seçerseniz bileşen tabanlı uygulama iskeleti gelir; Three.js genelde bu çatının yaşam döngüsü ve durum yönetimiyle entegre edilir (örneğin React tarafında sıkça @react-three/fiber ekosistemi).
  • Select a variant — JavaScript ile kaynaklar .js olarak gelir; derleyici ve tip katmanı olmadan hızlı başlangıç sağlar. TypeScript seçerseniz .ts dosyaları ve tip denetimi devreye girer; büyüyen projelerde IDE desteği ve refaktör güveni artar (bu sayfada anlatılan saf öğrenme yolu için JavaScript yeterlidir).

Proje klasörüne girme: Sorular tamamlandıktan sonra terminalde oluşan proje dizinine geçin. Aşağıdaki my-three-app yerine Project name adımında yazdığınız klasör adını kullanın; yalnızca o klasörün içindeyken bir sonraki bölümdeki npm install komutları doğru yere kurulum yapar.

cd my-three-app

Kütüphanelerin dahil edilmesi

npm install three
npm install --save-dev @types/three

@types/three, VS Code kullanıyorsanız IntelliSense sağlayarak hata riskini azaltır.

Dizin hiyerarşisi

  • src/ — Tüm JavaScript/TypeScript dosyaları, shader'lar ve uygulama mantığı.
  • public/ — Modeller (.glb), sesler ve görseller. Vite bu klasöre kök üzerinden doğrudan erişim sağlar.

Node.js ve NPM ekosistemi

Vite'ın komut satırı aracı (npm create vite, npm run dev) Node.js üzerinde çalışır; geliştirme sunucusu ve üretim derlemesi bu yüzden makinenizde Node kurulu olmalıdır. npm (Node Package Manager) bağımlılıkları package.json'a yazar ve indirir; aynı işi pnpm veya Yarn ile de yapabilirsiniz — hangi aracı seçtiğiniz ekip tercihi ve kilit dosyası uyumu meselesidir.

Tarayıcı uyumluluğu ve WebGL kontrolü

Modern tarayıcıların neredeyse tamamı WebGL sunsa da, "benim makinede çalışıyor" varsayımıyla ilerlemek risklidir. Üretim öncesi veya yeni bir cihazda, WebGL'in gerçekten etkin olduğunu doğrulamak iyi bir alışkanlıktır (örneğin üçgen bir sahne açıp konsolda hata olmaması, THREE.WebGLRenderer'ın oluşturulması veya tarayıcı geliştirici araçlarında WebGL bağlamının görünmesi). Bu, özellikle kurumsal ortamda donanım hızlandırması kısıtlı makinelerde sorun çıkmadan yakalamanıza yardım eder.

Vite konfigürasyonu (vite.config.js)

Çoğu küçük proje varsayılan Vite ayarıyla yeterlidir. Shader dosyalarını (.glsl) doğrudan import ile string olarak almak, özel varlık yolları veya eklenti tabanlı dönüşümler istiyorsanız kök dizinde bir vite.config.js (veya .ts) tanımlarsınız. Örneğin GLSL içe aktarımı için toplulukta sık kullanılan vite-plugin-glsl benzeri bir eklenti eklemek, shader dosyalarını modül gibi yönetmenizi sağlar — tek dosyalık demolar için şart değildir; daha büyük veya shader ağırlıklı sahnelerde profesyonel bir adımdır.

Modül yapısı ve modern standartlar

Three.js artık devasa bir kütüphanedir. Her şeyi aynı anda yüklemek, açılış hızını düşürür; modern modül yapısı bu sorunu çözer.

ES Modules (ESM) ve tree shaking

import * as THREE from 'three' ifadesiyle ihtiyaç duyulan parçaları seçerek kullanma yolunu açarsınız.

Tree shaking: Üretim (build) aşamasında Vite, kullanılmayan Three.js parçalarını (örneğin hiç sis eklemediyseniz Fog sınıfını) ayıklar; son kullanıcı daha küçük paket indirir.

Import maps

Import maps, tarayıcıya paketlerin nerede olduğunu tarif eder. Karmaşık ../../node_modules/... yolları yerine doğrudan isimlerle temiz import yazmanızı kolaylaştırır — geleceğe dönük bir standarttır.

İlk render testi: "Merhaba evren"

Ortamın hazır olduğunu anlamanın en iyi yolu ekrana bir şey çizdirmektir. Bu sadece bir küp değil; Three.js'in üç temel direğinin birleşimidir:

  • Sahne (Scene)

    Her şeyin içinde bulunduğu boşluk.

  • Kamera (Camera)

    Boşluğa hangi açıdan bakılacağı; genelde PerspectiveCamera.

  • Render motoru (Renderer)

    3D dünyayı ekranın piksellerine dönüştüren işlemci.

Geliştirici yardımcıları (dev tools)

  • OrbitControls — Sahnenin etrafında fareyle dönme; geliştirmede "gözünüz" olur.
  • Stats.js — FPS göstergesi; performans optimizasyonu için sık kullanılır.
  • Lil-gui — Kod yazmadan sahnede canlı renk/pozisyon gibi parametreleri oynatmanızı sağlayan küçük panel.

Uygulamalı kurulum rehberi

Video notu: Bu rehberde modern ES Modules yapısı kullanılmıştır. Sürecin sorunsuz ilerlemesi için bilgisayarınızda Node.js (LTS önerilir) kurulu olmalıdır. Terminalde node -v yazarak kurulumu kontrol edebilirsiniz.

Olası sorunlar ve çözümleri

PowerShell "execution policy" hatası

Sorun: Terminalde npm run dev yazdığınızda "scripts cannot be loaded because running scripts is disabled on this system" benzeri bir hata alabilirsiniz.

Çözüm: PowerShell'in varsayılan güvenlik politikası script çalıştırmayı engelleyebilir. Terminali yönetici olarak açıp
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser komutunu çalıştırmak bu sorunu genelde kalıcı olarak çözer.

"Node" veya "npm" tanınmıyor

Sorun: command not found veya komutun bulunamadığı mesajı.

Çözüm: Node.js kurulumunda "Add to PATH" seçeneğinin işaretlenmemiş olması sık görülür. Node.js'i yeniden kurarak PATH'e ekleyin veya ortam değişkenlerine manuel olarak ekleyin.

Port çakışması (EADDRINUSE)

Sorun: Vite varsayılan olarak 5173 portunu kullanır; başka bir süreç bu portu kullanıyorsa hata oluşabilir.

Çözüm: Vite çoğu zaman başka bir boş porta geçer. İsterseniz manuel olarak npm run dev -- --port 8080 ile farklı bir port belirtebilirsiniz.