Günümüz yazılım geliştirme dünyasında, karmaşık tam yığın (full-stack) uygulamaları hızlı ve verimli bir şekilde hayata geçirmek büyük bir meydan okumadır. Ancak, yapay zeka destekli kodlama araçları, güçlü arka uç servisleri ve modern ön uç çerçevelerinin birleşimiyle bu süreç artık çok daha erişilebilir. Bu rehberde, Cursor’ın yapay zeka yeteneklerini, Appwrite’ın sağlam arka uç hizmetlerini ve TanStack Start’ın yenilikçi ön uç mimarisini kullanarak nasıl eksiksiz bir not uygulaması geliştirebileceğimizi adım adım inceleyeceğiz.
Modern web uygulamaları geliştirmek, genellikle front-end, back-end ve veritabanı gibi birçok farklı bileşeni bir araya getirmeyi gerektirir. Geliştiriciler bu süreçte sürekli yeni teknolojiler öğrenmek, altyapıyı kurmak ve maintain etmek gibi zorluklarla karşılaşır. İşte tam da bu noktada, akıllı teknoloji seçimleri devreye girerek hem geliştirme hızını artırır hem de nihai ürünün kalitesini yükseltir. Cursor, Appwrite ve TanStack Start üçlüsü, bu zorlukların üstesinden gelmek için tasarlanmış, birbirini tamamlayan araçlar ve platformlardan oluşur. Her biri kendi alanında çığır açıcı yenilikler sunarak geliştiricilere benzersiz avantajlar sağlar.
Örneğin, bir not uygulaması geliştirdiğimizi düşünelim. Kullanıcıların notlarını güvenle saklaması, bunlara erişmesi, güncellemesi ve silmesi gerekir. Ayrıca, uygulamanın farklı cihazlarda ve ekran boyutlarında sorunsuz çalışması, hızlı tepki vermesi ve modern bir kullanıcı deneyimi sunması beklenir. Geleneksel yaklaşımlarla tüm bu gereksinimleri karşılamak haftalar sürebilirken, bu teknoloji yığını ile geliştirme süresi önemli ölçüde kısalabilir. Cursor, tekrarlayan kod yazma görevlerini otomatize ederken, Appwrite sunucu tarafı mantığına odaklanmanızı engellemeden kimlik doğrulama, veritabanı ve depolama gibi kritik arka uç fonksiyonlarını yönetir. Öte yandan, TanStack Start, React ekosisteminin gücünü kullanarak performans odaklı, SEO dostu ve kolay ölçeklenebilir ön uçlar inşa etmenizi sağlar. Dolayısıyla, bu üçlüyü tercih etmek, projenizi sıfırdan oluştururken karşılaşabileceğiniz karmaşıklığı azaltır ve size uygulamanızın temel mantığına odaklanma fırsatı verir. Bu sinerjik yaklaşım, geliştirme sürecini daha keyifli ve verimli hale getirirken, aynı zamanda daha sağlam ve ölçeklenebilir uygulamalar yaratmanıza olanak tanır.
Not Uygulamamız İçin Temel Taşlar: Cursor, Appwrite ve TanStack Start’ı Tanıyalım
Tam yığın bir uygulama geliştirmeden önce, kullandığımız her bir teknolojinin temelini ve bize ne gibi avantajlar sunduğunu anlamak kritik öneme sahiptir. Bu bölümde, projemizin temel yapı taşları olan Cursor, Appwrite ve TanStack Start’ı yakından tanıyacağız.
Cursor: AI Destekli Kodlama Deneyimi Nasıl Fark Yaratır?
Yapay zeka, yazılım geliştirme alanında hızla kendine yer ediniyor ve Cursor bu dönüşümün öncülerinden biri. Cursor, VS Code tabanlı bir IDE olup, geliştiricilerin kod yazma, hata ayıklama ve refactoring süreçlerini yapay zeka ile destekler. Geleneksel IDE’lerin ötesine geçerek, doğrudan kodunuzun içinde veya yeni dosya oluştururken bağlamı anlayan ve buna göre öneriler sunan bir yapay zeka asistanı olarak çalışır. Örneğin, belirli bir işlevselliği açıklamanız yeterlidir; Cursor sizin için uygun kod bloğunu oluşturabilir.
Bir not uygulaması bağlamında, Cursor’ın faydaları saymakla bitmez. Appwrite SDK’sını kullanarak notları veritabanına kaydetme veya getirme gibi karmaşık API çağrıları için boilerplate kodları hızlıca oluşturabilirsiniz. Veya belirli bir React bileşeni için kullanıcı arayüzü taslağına ihtiyacınız olduğunda, Cursor’a ne istediğinizi söylemeniz yeterlidir; saniyeler içinde size bir başlangıç noktası sunar. Bu, özellikle tekrar eden veya standart görevler için harcanan zamanı önemli ölçüde azaltır. Ayrıca, yazdığınız kodu optimize etme, olası hataları tespit etme veya daha açıklayıcı yorumlar ekleme gibi konularda da aktif olarak destek sağlar. Bu sayede, geliştiriciler daha çok problem çözmeye ve inovasyona odaklanabilirken, AI asistanı kodlama yükünün bir kısmını üstlenir. Cursor, kodlama pratiğinizi dönüştürerek sizi daha üretken ve verimli bir geliştirici yapar.
Appwrite: Arka Uç Geliştirmeyi Basitleştiren Güçlü Bir Platform
Appwrite, modern bir açık kaynak BaaS (Backend as a Service) platformudur. Geliştiricilerin, arka uç oluşturmakla uğraşmak yerine doğrudan uygulamalarının çekirdek özelliklerine odaklanmasını sağlar. Kimlik doğrulama, veritabanları, depolama, fonksiyonlar ve gerçek zamanlı güncellemeler gibi temel arka uç hizmetlerini tek bir çatı altında sunar. Geliştiriciler, Appwrite’ı kendi sunucularına kurarak veya bulut tabanlı bir servis olarak kullanarak uygulamalarının arka ucunu dakikalar içinde hazır hale getirebilirler. Bu esneklik, Appwrite’ı küçük projelerden büyük ölçekli uygulamalara kadar geniş bir yelpazede kullanılabilir kılar.
Not uygulamamız için Appwrite, vazgeçilmez bir bileşendir. Kullanıcıların güvenli bir şekilde hesap oluşturup oturum açmasını sağlayan kimlik doğrulama sistemi (Authentication) sunar. Notlarımızı depolayacağımız NoSQL veritabanı (Databases) ile kolayca etkileşim kurabiliriz. Her bir notun başlığı, içeriği, oluşturulma tarihi gibi bilgileri burada saklanır. Ayrıca, eğer notlarımızla birlikte resim veya dosya eklemek istersek, Appwrite’ın depolama servisini (Storage) kullanabiliriz. Gerçek zamanlı özellikler sayesinde, birden fazla cihazda aynı anda bir notu düzenleyen kullanıcıların değişiklikleri anında görmesi sağlanabilir. Appwrite’ın kullanımı kolay SDK’ları ve kapsamlı API’si, ön uç geliştiricilerinin arka uç ile sorunsuz bir şekilde entegrasyon kurmasını sağlar. Bu sayede, karmaşık sunucu mantığı yazmak yerine, yalnızca API çağrıları yaparak uygulamanızın arka uç ihtiyaçlarını karşılayabilirsiniz.
TanStack Start: React Ekosisteminde Tam Yığın Gelişimin Yeni Yıldızı
TanStack Start, React ekosisteminde tam yığın uygulamalar geliştirmek için tasarlanmış yenilikçi bir çerçevedir. Dosya tabanlı yönlendirme (file-based routing), sunucu bileşenleri (server components) ve güçlü veri çekme (data fetching) mekanizmaları gibi modern React özelliklerini bir araya getirir. Amacı, hem geliştirici deneyimini iyileştirmek hem de son kullanıcıya yüksek performanslı, SEO dostu ve hızlı uygulamalar sunmaktır. Next.js, Remix gibi popüler çerçevelerle benzerlikler gösterse de, TanStack kütüphanelerinin (React Query, React Table vb.) yaratıcıları tarafından geliştirilmesiyle kendi özgün avantajlarını sunar.
Not uygulamamızda TanStack Start kullanmak, bize birçok avantaj sağlar. Öncelikle, dosya tabanlı yönlendirme sayesinde, her bir not sayfası, not listesi veya kullanıcı paneli gibi rotaları tanımlamak çok kolaylaşır; sadece uygun klasör yapısını oluşturmanız yeterlidir. Sunucu bileşenleri, veri çekme işlemlerini doğrudan sunucuda gerçekleştirerek, client tarafındaki JavaScript yükünü azaltır ve uygulamanın ilk yüklenme süresini (TTFB) hızlandırır. Bu, özellikle mobil kullanıcılar için kritik bir performans artışıdır. Ayrıca, yerleşik veri yönetim mekanizmaları, Appwrite’dan notları çekme, önbelleğe alma ve güncellemeleri yönetme süreçlerini basitleştirir. TanStack Start’ın modüler yapısı, gelecekte uygulamanıza yeni özellikler eklerken veya mevcut bileşenleri ölçeklendirirken size büyük esneklik sağlar. Bu çerçeve, React geliştiricilerine tanıdık bir ortam sunarken, tam yığın geliştirmenin getirdiği zorlukları modern çözümlerle aşmalarına yardımcı olur.
Kurulum ve Proje Başlatma: İlk Adımlar Nelerdir?
Herhangi bir yazılım geliştirme projesinde, doğru başlangıç yapmak ve uygun geliştirme ortamını kurmak, projenin geri kalanının başarısı için temel teşkil eder. Not uygulamamız için Cursor, Appwrite ve TanStack Start’ı entegre etmeye başlamadan önce, gerekli araçları kurmalı ve projelerimizi başlatmalıyız. Bu bölüm, tüm bu ilk adımları adım adım açıklayacaktır.
- Node.js ve npm/Yarn Kurulumu: TanStack Start, Node.js tabanlı bir çerçeve olduğu için, öncelikle sisteminizde Node.js’in kurulu olması gerekir. Node.js’in resmi web sitesinden (nodejs.org) en son LTS (Uzun Süreli Destek) sürümünü indirip kurabilirsiniz. Kurulumla birlikte npm (Node Package Manager) de otomatik olarak yüklenecektir. İsterseniz alternatif olarak Yarn veya pnpm gibi farklı paket yöneticilerini de kullanabilirsiniz.
-
TanStack Start Projesi Başlatma: Gerekli paket yöneticisi kurulduktan sonra, TanStack Start projenizi başlatmak için komut satırınızı açın ve aşağıdaki komutu çalıştırın:
npm create tanstack-start@latest my-notes-app --template react-tsBu komut,
my-notes-appadında yeni bir dizin oluşturacak ve içerisine temel bir TanStack Start projesi kuracaktır.--template react-ts, TypeScript destekli React şablonunu kullanacağımızı belirtir, ki bu da modern ve daha güvenli bir geliştirme deneyimi için önerilir. Kurulum tamamlandığında, projenin dizinine gidin ve bağımlılıkları yükleyin:cd my-notes-app npm installProjenin düzgün çalıştığından emin olmak için geliştirme sunucusunu başlatabilirsiniz:
npm run devTarayıcınızda
http://localhost:5173adresine giderek örnek sayfayı görmeniz gerekir. -
Appwrite Bulut Hesabı ve Proje Oluşturma:
- Öncelikle, Appwrite Cloud adresine gidin ve yeni bir hesap oluşturun veya mevcut hesabınızla oturum açın.
- Kontrol panelinize ulaştığınızda, "Create Project" butonuna tıklayın ve projenize "My Notes App" gibi anlamlı bir isim verin.
- Projeniz oluşturulduktan sonra, projenizin ana sayfasında size özel "Project ID" ve "API Endpoint" bilgilerini göreceksiniz. Bu bilgiler, uygulamanızın Appwrite ile iletişim kurması için gerekli olacaktır. Bu değerleri bir yere not edin.
- Son olarak, uygulamanızın Appwrite ile güvenli bir şekilde iletişim kurabilmesi için "Platforms" bölümüne giderek yeni bir Web platformu eklemeniz gerekecek. "Add Platform" ve ardından "Web" seçeneğini tıklayın. "Host Name" alanına
localhostve "Port" alanına5173(TanStack Start'ın varsayılan portu) yazın. Geliştirme ortamınızda uygulamanızın Appwrite'a erişmesine izin verecektir.
-
Cursor IDE Kurulumu: Cursor, VS Code tabanlı bir düzenleyici olduğundan, kurulumu oldukça basittir. Cursor'ın resmi web sitesinden (cursor.sh) işletim sisteminize uygun sürümü indirin ve yükleyin. Kurulumdan sonra,
my-notes-appprojenizi Cursor içinde açın. İlk kez kullandığınızda, Cursor size yapay zeka özelliklerini nasıl etkinleştireceğinize dair talimatlar sunacaktır. Bu adımları takip ederek Cursor'ın tam potansiyelinden yararlanmaya hazır hale gelebilirsiniz. Cursor, sizin için otomatik olarak uzantıları önerebilir ve kod tamamlama, kod oluşturma gibi özellikleri entegre edecektir.
Bu adımları tamamladıktan sonra, not uygulamamızı geliştirmeye başlamak için gerekli tüm araçlara ve projelere sahip olacaksınız. Her bir bileşenin doğru şekilde kurulduğundan emin olmak, ileride yaşanabilecek potansiyel sorunların önüne geçecektir.
Appwrite ile Arka Uç Kurulumu: Veritabanı ve Kimlik Doğrulama Nasıl Yapılır?
Not uygulamamızın temel işlevselliği, kullanıcıların notlarını güvenli bir şekilde saklamasına ve yönetmesine dayanır. Bu işlevselliği sağlamak için Appwrite'ın veritabanı ve kimlik doğrulama servislerini kullanacağız. Bu bölümde, Appwrite panelinde gerekli yapılandırmaları nasıl yapacağımızı ve bunları TanStack Start projemizle nasıl entegre edeceğimizi adım adım göstereceğiz.
1. Kimlik Doğrulama (Authentication) Kurulumu
Appwrite, kullanıcı yönetimi için güçlü ve esnek bir kimlik doğrulama sistemi sunar. Kullanıcıların e-posta ve şifre ile kayıt olmasını ve oturum açmasını sağlayacağız.
- Appwrite Panelinde: Projenizin kontrol panelinde sol menüden "Auth" bölümüne gidin. Varsayılan olarak "Email/Password" sağlayıcısı etkin olmalıdır. Değilse, bunu etkinleştirin. Gerekirse, yeni kullanıcıların otomatik olarak doğrulandığı "Users" sekmesindeki "Self Registration" ayarlarını kontrol edebilirsiniz. Genellikle, not uygulamaları için e-posta doğrulama gereksinimi başlangıçta kapatılabilir ve daha sonra eklenebilir.
2. Veritabanı ve Koleksiyon (Collection) Oluşturma
Notlarımızı depolamak için Appwrite'ın veritabanı servisini kullanacağız. Her bir not, bir "document" olarak saklanacak ve bu document'lar bir "collection" içinde yer alacak.
- Veritabanı Oluşturma: Appwrite kontrol panelinde sol menüden "Databases" bölümüne gidin. "Create database" butonuna tıklayın ve veritabanınıza "NotesDB" gibi bir isim verin. Oluşturulan veritabanına tıklayarak içine girin.
- Koleksiyon Oluşturma: "Create collection" butonuna tıklayın. Koleksiyonunuza "notes" adını verin.
-
Öznitelikler (Attributes) Tanımlama: Koleksiyonunuzun içine girdikten sonra "Attributes" sekmesine gidin. Notlarımız için gerekli öznitelikleri tanımlamamız gerekiyor:
title: String, Gerekli (Required), Maksimum 255 karakter.content: String, Gerekli (Required), Uzun metinler için daha büyük boyut (örneğin 10000 karakter).userId: String, Gerekli (Required), Notun hangi kullanıcıya ait olduğunu belirtir. Bu öznitelik, Appwrite'ın kullanıcı kimliklerini saklayacaktır.createdAt: Datetime, Gerekli (Required), Varsayılan değer olarakCurrent Timeseçilebilir.
Her özniteliği eklerken, ilgili veri tipini (String, Datetime vb.) ve gerekli olup olmadığını (Required) doğru şekilde seçtiğinizden emin olun.
-
İzinler (Permissions) Ayarlama: "Permissions" sekmesine gidin. Bu kısım çok önemlidir. Kimin not oluşturabileceğini, okuyabileceğini, güncelleyebileceğini ve silebileceğini belirleyeceğiz.
- Create:
role:member(Sadece oturum açmış kullanıcılar not oluşturabilir). - Read:
user:[USER_ID](Her kullanıcı sadece kendi notlarını okuyabilir). - Update:
user:[USER_ID](Her kullanıcı sadece kendi notlarını güncelleyebilir). - Delete:
user:[USER_ID](Her kullanıcı sadece kendi notlarını silebilir).
Bu ayarlar, kullanıcı gizliliğini ve veri güvenliğini sağlamak için kritik öneme sahiptir.
- Create:
3. TanStack Start Projesine Appwrite SDK Entegrasyonu
Şimdi Appwrite SDK'sını TanStack Start projemize eklememiz ve Appwrite ile iletişim kuracak temel bir servis oluşturmamız gerekiyor.
-
Appwrite SDK Kurulumu: Projenizin kök dizininde terminali açın ve Appwrite SDK'sını yükleyin:
npm install appwrite -
Appwrite İstemci Oluşturma:
src/lib/appwrite.tsgibi bir dosya oluşturarak Appwrite istemcisini ve servislerini yapılandırın.// src/lib/appwrite.ts import { Client, Account, Databases } from 'appwrite'; const client = new Client(); client .setEndpoint(import.meta.env.VITE_APPWRITE_ENDPOINT) // Your Appwrite Endpoint .setProject(import.meta.env.VITE_APPWRITE_PROJECT_ID); // Your project ID export const account = new Account(client); export const databases = new Databases(client); export default client;import.meta.envile erişilen değişkenler, Vite'ın ortam değişkenlerini kullanma şeklidir. Bu değişkenleri tanımlamak için projenizin kök dizininde bir.envdosyası oluşturmanız gerekecek:# .env VITE_APPWRITE_ENDPOINT="[Appwrite API Endpoint]" # Örnek: https://cloud.appwrite.io/v1 VITE_APPWRITE_PROJECT_ID="[Your Project ID]" # Örnek: 654321abcdef VITE_APPWRITE_DATABASE_ID="[Your Database ID]" # Oluşturduğunuz veritabanının ID'si VITE_APPWRITE_COLLECTION_ID="[Your Collection ID]" # Oluşturduğunuz koleksiyonun ID'siAppwrite panelinden veritabanı ve koleksiyon ID'lerini almayı unutmayın. Bu adımları tamamladığınızda, TanStack Start uygulamanız Appwrite ile güvenli ve verimli bir şekilde etkileşime girmeye hazır olacaktır. Arka uç tarafında yapılması gereken temel kurulumları başarıyla tamamlamış bulunmaktayız.
TanStack Start ile Ön Uç Geliştirme: Notları Yönetmek İçin UI Nasıl Oluşturulur?
Arka uç altyapımızı Appwrite ile kurduktan sonra, sıra kullanıcıların notlarını görüntüleyebileceği, oluşturabileceği, düzenleyebileceği ve silebileceği ön uç arayüzünü geliştirmeye geldi. TanStack Start'ın sunduğu dosya tabanlı yönlendirme ve React bileşenlerini kullanarak modern ve etkileşimli bir arayüz inşa edeceğiz. Bu kısım, uygulamanızın kullanıcılarla doğrudan etkileşim kurduğu yerdir, bu nedenle kullanıcı deneyimine özen göstermek önemlidir.
1. Temel Uygulama Yapısı ve Yönlendirme
TanStack Start, src/routes dizini altındaki dosya ve klasör yapısına göre otomatik olarak yönlendirme (routing) yapar. Not uygulamamız için aşağıdaki gibi bir yapı oluşturabiliriz:
src/
├── routes/
│ ├── _auth/ // Kimlik doğrulama ile ilgili rotalar
│ │ ├── register.tsx
│ │ ├── login.tsx
│ │ └── route.tsx // Auth layout'u (örneğin header/footer olmadan)
│ ├── _dashboard/ // Oturum açmış kullanıcıların göreceği rotalar
│ │ ├── index.tsx // Not listesi sayfası
│ │ ├── new.tsx // Yeni not oluşturma sayfası
│ │ ├── $noteId.tsx // Not detay/düzenleme sayfası
│ │ └── route.tsx // Dashboard layout'u (örneğin sidebar, header ile)
│ └── index.tsx // Ana sayfa (varsayılan olarak _auth/login'e yönlendirebilir)
└── components/
│ ├── NoteCard.tsx
│ └── AuthForm.tsx
└── lib/
│ └── appwrite.ts
└── utils/
└── authMiddleware.ts // Rota koruması için
Bu yapı, hem okunabilirliği artırır hem de uygulamanın genişlemesini kolaylaştırır. Örneğin, _auth/route.tsx dosyası, kayıt ve giriş sayfaları için ortak bir düzen (layout) sağlayabilirken, _dashboard/route.tsx oturum açmış kullanıcılar için farklı bir düzen sunar. $noteId.tsx ise dinamik bir rota oluşturarak URL'deki ID'ye göre belirli bir notu getirmemizi sağlar.
2. Kimlik Doğrulama Arayüzleri (Kayıt ve Giriş)
Öncelikle kullanıcıların kayıt olabileceği ve giriş yapabileceği sayfaları oluşturalım. src/routes/_auth/register.tsx ve src/routes/_auth/login.tsx dosyalarında basit formlar oluşturacağız.
// src/routes/_auth/login.tsx
import { account } from '../../lib/appwrite';
import { useNavigate } from '@tanstack/react-router';
import React, { useState } from 'react';
export default function LoginPage() {
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');
const navigate = useNavigate();
const handleSubmit = async (e: React.FormEvent) => {
e.preventDefault();
try {
await account.createEmailPasswordSession(email, password);
navigate({ to: '/dashboard' }); // Giriş başarılı, dashboard'a yönlendir
} catch (error) {
console.error('Login error:', error);
alert('Giriş başarısız oldu: ' + error.message);
}
};
return (
);
}
Kayıt sayfası (register.tsx) benzer bir yapıya sahip olacak, ancak account.create() metodunu kullanacaktır.
3. Not Listesi ve Yeni Not Oluşturma
Kullanıcı giriş yaptıktan sonra /dashboard sayfasına yönlendirilecek. Bu sayfada kullanıcının notlarını listeleyecek ve yeni not eklemesi için bir düğme sunacağız. Notları çekerken TanStack Start'ın veri çekme mekanizmalarından yararlanabiliriz.
// src/routes/_dashboard/index.tsx
import { createFileRoute, Link } from '@tanstack/react-router';
import { databases, account } from '../../lib/appwrite';
import { Query } from 'appwrite';
import { useQuery } from '@tanstack/react-query'; // TanStack Query'yi kullanıyoruz
// Bu, TanStack Start'ın veri çekme tanımını içerir
export const Route = createFileRoute('/_dashboard/')({
loader: async () => {
const user = await account.get(); // Aktif kullanıcıyı al
if (!user) return { notes: [] }; // Kullanıcı yoksa boş döndür
const response = await databases.listDocuments(
import.meta.env.VITE_APPWRITE_DATABASE_ID,
import.meta.env.VITE_APPWRITE_COLLECTION_ID,
[Query.equal('userId', user.$id), Query.orderDesc('createdAt')] // Sadece kullanıcının notlarını çek
);
return { notes: response.documents };
},
});
export default function NotesListPage() {
const { notes } = Route.useLoaderData();
return (
Notlarım
Yeni Not Ekle
{notes.length === 0 ? (
Henüz hiç notunuz yok. Yeni bir not ekleyin!
) : (
{notes.map((note) => (
/dashboard/${note.$id}} key={note.$id} className="block">
{note.title}
{note.content}
{new Date(note.createdAt).toLocaleDateString()}
))}
)}
);
}
new.tsx sayfası, bir not başlığı ve içeriği girmek için bir form içerecek ve bu verileri Appwrite'a gönderecektir. Appwrite SDK'sının databases.createDocument() metodunu kullanacağız.
4. Not Detay ve Düzenleme
src/routes/_dashboard/$noteId.tsx dosyası, belirli bir notun detaylarını göstermek ve düzenlemek için kullanılacak. URL'den $noteId parametresini alarak Appwrite'dan ilgili notu çekeceğiz.
// src/routes/_dashboard/$noteId.tsx
import { createFileRoute, useNavigate } from '@tanstack/react-router';
import { databases, account } from '../../lib/appwrite';
import { useState } from 'react';
export const Route = createFileRoute('/_dashboard/$noteId')({
loader: async ({ params }) => {
const user = await account.get();
if (!user) throw new Error("Unauthorized");
const note = await databases.getDocument(
import.meta.env.VITE_APPWRITE_DATABASE_ID,
import.meta.env.VITE_APPWRITE_COLLECTION_ID,
params.noteId
);
if (note.userId !== user.$id) throw new Error("Forbidden"); // Notun kullanıcıya ait olduğunu kontrol et
return { note };
},
});
export default function NoteDetailPage() {
const { note } = Route.useLoaderData();
const [title, setTitle] = useState(note.title);
const [content, setContent] = useState(note.content);
const navigate = useNavigate();
const handleUpdate = async (e: React.FormEvent) => {
e.preventDefault();
try {
await databases.updateDocument(
import.meta.env.VITE_APPWRITE_DATABASE_ID,
import.meta.env.VITE_APPWRITE_COLLECTION_ID,
note.$id,
{ title, content }
);
navigate({ to: '/dashboard' });
} catch (error) {
console.error('Not güncelleme hatası:', error);
alert('Not güncellenirken bir hata oluştu.');
}
};
const handleDelete = async () => {
if (!confirm('Bu notu silmek istediğinizden emin misiniz?')) return;
try {
await databases.deleteDocument(
import.meta.env.VITE_APPWRITE_DATABASE_ID,
import.meta.env.VITE_APPWRITE_COLLECTION_ID,
note.$id
);
navigate({ to: '/dashboard' });
} catch (error) {
console.error('Not silme hatası:', error);
alert('Not silinirken bir hata oluştu.');
}
};
return (
);
}
Bu kod blokları, TanStack Start ve Appwrite SDK'sını kullanarak not uygulamamızın temel ön uç işlevselliğini nasıl oluşturacağımıza dair size sağlam bir başlangıç noktası sunar. Bu yapıyı genişleterek daha karmaşık özellikler (örneğin, not arama, etiketleme) ekleyebilirsiniz.
Yapay Zeka Desteği ile Kodlama: Cursor Not Uygulamanıza Nasıl Yardımcı Olur?
Şimdiye kadar Appwrite ile arka ucu ve TanStack Start ile ön ucu manuel olarak inşa ettik. Ancak, Cursor gibi bir yapay zeka destekli kodlama aracı, bu süreçleri çok daha verimli hale getirebilir. Cursor, kod yazma, hata ayıklama ve mevcut kodu iyileştirme konusunda size rehberlik ederek geliştirme hızınızı artırır.
1. Boilerplate Kod Oluşturma
Not uygulaması gibi standart CRUD (Create, Read, Update, Delete) operasyonları içeren projelerde, belirli bir yapıyı takip eden birçok tekrarlayan kod bloğu bulunur. Cursor, bu tür boilerplate kodları saniyeler içinde oluşturarak size zaman kazandırabilir.
Vaka Analizi: Yeni Not Formu Oluşturma
src/routes/_dashboard/new.tsx dosyasında yeni bir not oluşturma formu yazmanız gerektiğini varsayalım. Cursor'ı kullanarak bu süreci hızlandırabiliriz:
new.tsxdosyasını açın.- Cursor'ın sohbet arayüzünü (genellikle Ctrl/Cmd + K tuş kombinasyonuyla açılır) açın.
- Şu komutu girin: "Appwrite SDK kullanarak bir not oluşturma formu için React bileşeni oluştur. Formda başlık ve içerik alanları olsun. Başarılı olursa kullanıcıyı /dashboard'a yönlendir."
Cursor, büyük olasılıkla aşağıdaki gibi bir kod iskeleti üretecektir. Üretilen kodun tam olarak Appwrite SDK'sına entegre olması için küçük düzenlemeler yapmanız gerekebilir, ancak başlangıç için harika bir temel sunar:
// Cursor tarafından üretilen taslak
import React, { useState } from 'react';
import { useNavigate } from '@tanstack/react-router';
// Buraya Appwrite import'larınızı ve fonksiyonlarınızı eklemelisiniz
import { databases, account } from '../../lib/appwrite';
import { ID } from 'appwrite'; // Appwrite ID'si için
export default function NewNotePage() {
const [title, setTitle] = useState('');
const [content, setContent] = useState('');
const navigate = useNavigate();
const handleSubmit = async (e: React.FormEvent) => {
e.preventDefault();
try {
const user = await account.get(); // Aktif kullanıcıyı al
if (!user) {
alert("Lütfen giriş yapın.");
return;
}
await databases.createDocument(
import.meta.env.VITE_APPWRITE_DATABASE_ID,
import.meta.env.VITE_APPWRITE_COLLECTION_ID,
ID.unique(), // Otomatik ID oluştur
{
title,
content,
userId: user.$id,
createdAt: new Date().toISOString(),
}
);
navigate({ to: '/dashboard' });
} catch (error) {
console.error('Not oluşturma hatası:', error);
alert('Not oluşturulurken bir hata oluştu: ' + error.message);
}
};
return (
);
}
2. Hata Ayıklama (Debugging) ve Kod İyileştirme
Cursor, sadece kod yazmakla kalmaz, aynı zamanda mevcut kodunuzdaki hataları bulmanıza ve iyileştirmeler yapmanıza da yardımcı olur. Uygulamanızda bir hata ile karşılaştığınızda (örneğin, notların listelenmemesi), Cursor'a sorunu açıklayarak çözüm önerileri alabilirsiniz.
Vaka Analizi: Not Listeleme Hatasını Ayıklama
Diyelim ki not listeleme sayfanızda notlar görünmüyor ve konsolda bir hata alıyorsunuz. Cursor'ı kullanarak bu sorunu çözmeye çalışalım:
- Hata veren kod bloğunu seçin (
NotesListPagebileşeni veyaloaderfonksiyonu). - Cursor'ın sohbet arayüzünü açın.
- Şu komutu girin: "Bu kod neden notları listelemiyor? Konsolda 'Error: Permission denied' hatasını görüyorum."
Cursor, Appwrite izin ayarlarınızı kontrol etmenizi, userId filtresinin doğru olduğundan emin olmanızı veya Appwrite SDK çağrılarının hatasız olduğundan emin olmanızı önerebilir. Ayrıca, kodu daha verimli hale getirmek için farklı sorgu yaklaşımları veya veri önbellekleme stratejileri önerebilir.
Örneğin, not listeleme loader'ındaki Query.equal('userId', user.$id) kısmını gözden geçirmenizi ve Appwrite koleksiyonunuzdaki izinlerin (ACL) doğru bir şekilde user:[USER_ID] olarak ayarlandığından emin olmanızı önerebilir. Eğer userId alanı yanlış tanımlanmışsa veya Appwrite'ta eksik izin varsa, Cursor bu tür sorunları hızlıca tespit etmenize yardımcı olabilir.
3. Kod Refactoring ve Optimizasyon
Uygulama büyüdükçe kodunuzu yeniden yapılandırmak (refactoring) ve optimize etmek önemlidir. Cursor, bu süreçte de size destek olabilir.
Vaka Analizi: Yardımcı Fonksiyon Oluşturma
Appwrite veritabanı ID'si ve koleksiyon ID'si gibi bilgileri her yerde tekrarlamak yerine, bunları merkezi bir yere taşıyan bir yardımcı fonksiyon oluşturmak isteyebilirsiniz:
- İlgili Appwrite çağrılarını içeren bir kodu seçin.
- Cursor'a "Bu Appwrite çağrılarını basitleştirmek için bir yardımcı fonksiyon oluşturabilir misin? Veritabanı ve koleksiyon ID'leri ortam değişkenlerinden gelsin." deyin.
Cursor, src/utils/appwriteHelpers.ts gibi bir dosyada şu tür bir fonksiyon önerebilir:
// src/utils/appwriteHelpers.ts
import { databases, account } from '../lib/appwrite';
import { ID, Query } from 'appwrite';
const DB_ID = import.meta.env.VITE_APPWRITE_DATABASE_ID;
const COLLECTION_ID = import.meta.env.VITE_APPWRITE_COLLECTION_ID;
export async function getNotesForCurrentUser() {
try {
const user = await account.get();
if (!user) return [];
const response = await databases.listDocuments(
DB_ID,
COLLECTION_ID,
[Query.equal('userId', user.$id), Query.orderDesc('createdAt')]
);
return response.documents;
} catch (error) {
console.error('Kullanıcı notları getirilirken hata oluştu:', error);
return [];
}
}
export async function createNote(title: string, content: string) {
try {
const user = await account.get();
if (!user) throw new Error("Kullanıcı girişi yapılmadı.");
const newNote = await databases.createDocument(
DB_ID,
COLLECTION_ID,
ID.unique(),
{
title,
content,
userId: user.$id,
createdAt: new Date().toISOString(),
}
);
return newNote;
} catch (error) {
console.error('Not oluşturulurken hata oluştu:', error);
throw error;
}
}
// Diğer CRUD fonksiyonları (updateNote, deleteNote) da buraya eklenebilir.
Ardından, ön uç bileşenlerinizde bu yardımcı fonksiyonları içe aktararak kodunuzu daha temiz ve yönetilebilir hale getirebilirsiniz. Cursor, bu tür yapısal iyileştirmeler için size akıllıca öneriler sunarak kod kalitenizi artırmanıza yardımcı olur. Yapay zeka desteğiyle, geliştiriciler daha hızlı prototip oluşturabilir, daha az hata yapabilir ve daha yüksek kaliteli kod yazabilirler.
İleri Düzey Optimizasyonlar ve En İyi Uygulamalar
Uygulamamızın temel işlevselliğini oluştursak da, gerçek dünya senaryolarında bir uygulamanın sadece çalışması yeterli değildir. Performans, kullanıcı deneyimi, güvenlik ve ölçeklenebilirlik gibi faktörler, bir uygulamanın başarısı için hayati öneme sahiptir. Bu bölümde, not uygulamamızı daha ileriye taşımak için bazı optimizasyonlar ve en iyi uygulamaları inceleyeceğiz.
1. Performans ve Kullanıcı Deneyimi İçin İpuçları
-
Veri Önbellekleme (Caching) ve Tekrar Doğrulama (Revalidation): TanStack Start, React Query (eski adıyla TanStack Query) ile derinlemesine entegredir. Not listesini çektiğimizde, bu veriler varsayılan olarak önbelleğe alınır. Ancak, notlar güncellendiğinde veya silindiğinde önbelleği geçersiz kılmak ve verileri yeniden çekmek önemlidir. Appwrite'ın gerçek zamanlı (realtime) özellikleri, bu süreci otomatikleştirmek için kullanılabilir. Appwrite'ın real-time API'sini kullanarak, bir not güncellendiğinde veya silindiğinde ön uçta ilgili önbelleği geçersiz kılabiliriz.
// Appwrite gerçek zamanlı dinleyici örneği (kısmi) import { client } from '../../lib/appwrite'; import { QueryClient } from '@tanstack/react-query'; // Eğer react-query kullanıyorsanız const queryClient = new QueryClient(); // Önbelleği yönetmek için client.subscribe(databases.${import.meta.env.VITE_APPWRITE_DATABASE_ID}.collections.${import.meta.env.VITE_APPWRITE_COLLECTION_ID}.documents, (response) => { if (response.events.includes('databases.*.collections.*.documents.*.update') || response.events.includes('databases.*.collections.*.documents.*.delete')) { queryClient.invalidateQueries(['notes']); // 'notes' sorgusunun önbelleğini geçersiz kıl } });Bu, kullanıcıların her zaman en güncel veriyi görmesini sağlar ve gereksiz API çağrılarını önler.
-
Sayfalama (Pagination) ve Sonsuz Kaydırma (Infinite Scrolling): Eğer kullanıcının çok fazla notu varsa, hepsini aynı anda yüklemek performansı düşürebilir. Appwrite'ın
listDocumentsmetodu,limitveoffset(veyacursor) seçenekleriyle sayfalama yapmayı destekler. Not listeleme sayfanızda bu özelliklerden yararlanarak sadece belirli sayıda notu yükleyebilir, kullanıcı daha fazla not görmek istediğinde ek notları çekebilirsiniz. Bu, uygulamanın daha hızlı yüklenmesini ve daha akıcı bir kullanıcı deneyimi sunmasını sağlar.// Sayfalama örneği (loader içinde) // [Query.limit(10), Query.offset(0)] // İlk 10 notu getir // Bir sonraki 10 not için offset'i 10 artırın. - Optimistik Güncellemeler (Optimistic Updates): Kullanıcı bir notu güncellediğinde veya sildiğinde, API çağrısı tamamlanmadan önce UI'ı güncellemek, uygulamayı daha duyarlı hissettirir. İşlem başarılı olmazsa, UI eski durumuna geri döndürülebilir. React Query bu tür optimistik güncellemeler için harika araçlar sunar.
2. Mobil Uyumluluk: Responsive Tasarımı Nasıl Sağlarsınız?
Günümüzde mobil cihazlardan erişim, masaüstü erişiminden çok daha yaygın hale gelmiştir. Bu nedenle not uygulamamızın her türlü cihazda harika görünmesi ve çalışması kritik öneme sahiptir.
-
Meta Viewport Etiketi: HTML'inizin
bölümüne aşağıdaki meta etiketini eklemek, tarayıcının sayfayı cihazın genişliğine göre doğru bir şekilde ölçeklendirmesini sağlar: -
Esnek Düzenler ve Akışkan Birimler: CSS Flexbox ve Grid, responsive düzenler oluşturmak için mükemmel araçlardır. Bileşenlerinizin genişliklerini yüzde (%) birimleri,
vw/vhveyarem/emgibi akışkan birimlerle tanımlayın. -
Medya Sorguları (Media Queries): Belirli ekran boyutlarına göre farklı stiller uygulamak için medya sorgularını kullanın. Örneğin, küçük ekranlarda not kartlarının tek sütunlu olmasını, daha büyük ekranlarda ise birden fazla sütuna yayılmasını sağlayabilirsiniz.
Yukarıdaki örnekte Tailwind CSS sınıflarını kullanmasak da, temel prensibi anlamak önemlidir. Tailwind CSS gibi çerçeveler, bu medya sorgularını utility sınıfları aracılığıyla zaten soyutlayarak geliştirme sürecini daha da kolaylaştırır (örneğin,
grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3).
3. Güvenlik Önlemleri ve Appwrite İpuçları
-
Appwrite İzinleri (ACL - Access Control List): Not koleksiyonumuzda belirlediğimiz izinler (
user:[USER_ID]), her kullanıcının sadece kendi notlarına erişmesini sağlayarak temel veri güvenliğini sağlar. Bu, en önemli güvenlik önlemlerinden biridir ve dikkatlice ayarlanmalıdır. Asla frontend'den gelebilecek verilere körü körüne güvenmeyin; Appwrite'ın arka uç izin mekanizması her zaman devrede olmalıdır. - Sunucu Tarafı Doğrulama (Server-Side Validation): Frontend tarafında form doğrulama yapmak iyi bir kullanıcı deneyimi sağlasa da, nihai doğrulama her zaman arka uçta yapılmalıdır. Appwrite, koleksiyon özniteliklerini tanımlarken belirlediğimiz veri tipleri ve gereklilik kısıtlamaları (required, max length vb.) ile otomatik doğrulama yapar. Bu, geçersiz veya kötü niyetli verilerin veritabanına kaydedilmesini önler.
-
Ortam Değişkenlerinin Güvenliği: Appwrite API endpoint ve proje ID'si gibi hassas bilgileri doğrudan kodunuzda bırakmak yerine,
.envdosyaları veya sunucu tarafı ortam değişkenleri aracılığıyla yönetin. Vite (TanStack Start'ın kullandığı araç),import.meta.envile bu değişkenlere erişmenizi sağlar. Ancak bu değişkenler client tarafında görünür olacağından, API gizli anahtarlarını asla bu şekilde kullanmayın. Client-side SDK'lar için sadece public ID'ler kullanılmalıdır. - HTTPS Kullanımı: Uygulamanızın canlıya alındığında her zaman HTTPS üzerinden yayınlandığından emin olun. Appwrite Cloud otomatik olarak HTTPS kullanır. Kendi sunucunuzda Appwrite kuruyorsanız, bir ters proxy (Nginx, Caddy) ile SSL/TLS sertifikalarını yapılandırmalısınız.
Bu ileri düzey konulara odaklanarak, sadece çalışan değil, aynı zamanda hızlı, güvenli ve kullanıcı dostu bir not uygulaması geliştirebilirsiniz.
Sonuç: Geleceğin Uygulamalarını Bugün İnşa Etmek
Bu kapsamlı rehber boyunca, Cursor'ın yapay zeka destekli kodlama yeteneklerini, Appwrite'ın güçlü ve yönetimi kolay arka uç servislerini ve TanStack Start'ın modern ön uç mimarisini bir araya getirerek nasıl eksiksiz bir tam yığın not uygulaması geliştirebileceğimizi adım adım inceledik. Geleneksel geliştirme süreçlerinin karmaşıklığını basitleştirerek, bu teknoloji yığınının geliştiricilere sağladığı hızı, verimliliği ve ölçeklenebilirliği net bir şekilde gördük.
Başlangıçta temel kavramları tanıdık, ardından Appwrite üzerinde güvenli kimlik doğrulama ve veritabanı yapısını kurduk. Sonrasında, TanStack Start'ın esnek yönlendirme ve veri çekme yetenekleriyle kullanıcı arayüzünü inşa ettik. En önemlisi, Cursor'ın yapay zeka desteğiyle boilerplate kodları nasıl hızla oluşturabileceğimizi, hata ayıklama süreçlerini nasıl kolaylaştırabileceğimizi ve kodumuzu nasıl iyileştirebileceğimizi deneyimledik. Bu sinerjik yaklaşım, sadece geliştirme süresini kısaltmakla kalmaz, aynı zamanda daha az hatayla daha kaliteli kod yazmamıza olanak tanır. İleri düzey optimizasyonlar ve güvenlik ipuçlarıyla da uygulamanın gerçek dünya standartlarında bir performans ve güvenliğe sahip olmasını sağladık. Artık, bu bilgiler ışığında kendi yaratıcı fikirlerinizi hayata geçirmek için güçlü bir temeliniz var.
Sıkça Sorulan Sorular
-
S: Cursor kullanmak zorunlu mu? Kodu kendim yazamaz mıyım?
C: Hayır, Cursor kullanmak zorunlu değildir. Makale boyunca gösterilen tüm kodları kendiniz de yazabilirsiniz. Cursor, bir yapay zeka kod asistanı olarak, geliştirme hızınızı artırmak ve tekrarlayan görevleri otomatikleştirmek için bir araçtır. Özellikle yeni bir teknoloji öğrenirken veya hızlı prototipleme yaparken çok faydalı olabilir.
-
S: Appwrite yerine başka bir BaaS (Backend as a Service) kullanabilir miyim?
C: Evet, Appwrite açık kaynaklı ve güçlü bir BaaS alternatifi olsa da, Firebase, Supabase veya AWS Amplify gibi diğer BaaS platformlarını da kullanabilirsiniz. Ancak, Appwrite'ın sunduğu özellikler ve SDK'lar bu makalede gösterildiği gibi sorunsuz bir entegrasyon sağlar. Farklı bir BaaS seçmeniz durumunda, SDK entegrasyon kodlarını ve Appwrite panelindeki yapılandırmaları o servisin dokümantasyonuna göre ayarlamanız gerekecektir.
-
S: TanStack Start neden Next.js veya Remix gibi diğer React çerçevelerine tercih edilmeli?
C: TanStack Start, henüz yeni bir çerçeve olmasına rağmen, TanStack ekosisteminin (React Query, React Table vb.) yaratıcıları tarafından geliştirildiği için bu kütüphanelerle derinlemesine entegrasyon sunar. Dosya tabanlı yönlendirme ve sunucu bileşenleri gibi modern yaklaşımlara sahiptir. Next.js ve Remix de harika seçeneklerdir; seçim genellikle projenizin spesifik gereksinimlerine, ekip tercihlerine ve ekosistemdeki yeniliklere ne kadar açık olduğunuza bağlıdır. TanStack Start, React Query'ye aşina olanlar için özellikle çekici olabilir.
-
S: Uygulamayı canlıya nasıl alabilirim (deploy)?
C: TanStack Start ile geliştirilen uygulamalar, genellikle Vercel, Netlify veya Render gibi modern statik site barındırma platformlarında kolayca dağıtılabilir. TanStack Start'ın dağıtım dokümantasyonunu inceleyerek, projenizi nasıl derleyeceğinizi (
npm run build) ve seçtiğiniz platforma nasıl yükleyeceğinizi öğrenebilirsiniz. Appwrite Cloud kullanıyorsanız, arka ucunuz zaten canlıdadır ve doğrudan uygulamalarınızdan erişilebilir. -
S: Not uygulamasına daha fazla özellik eklemek istersem ne yapmalıyım?
C: Not uygulamasına etiketleme, arama, notları paylaşma, zengin metin düzenleyici entegrasyonu gibi birçok özellik ekleyebilirsiniz. Appwrite'ın fonksiyonları (Functions) servisini kullanarak sunucu tarafında özel mantık çalıştırabilir, depolama (Storage) servisi ile notlara görseller ekleyebilir veya Appwrite'ın gerçek zamanlı yeteneklerini daha derinlemesine kullanarak anlık bildirimler gönderebilirsiniz. TanStack Start'ın modüler yapısı ve React ekosisteminin geniş kütüphane desteği, bu tür genişletmeleri kolayca yapmanıza olanak tanır.