--- title: Geliştirme Ortamı description: Local development server ve test ortamı kullanımı --- Uygulamanızı oluşturduktan sonra, geliştirme sunucusunu başlatmak için proje klasörüne geçin ve aşağıdaki komutu çalıştırın: ```bash cd [uygulama-adı] ikas app dev ``` ### Test Mağazası Seçimi `ikas app dev` komutunu **ilk kez** çalıştırdığınızda, uygulamanızı hangi test mağazasında deneyeceğinizi seçmeniz istenir. Bu mağaza, CLI tarafından yetkilendirilir ve sonraki `ikas app dev` çalıştırmalarında varsayılan olarak kullanılır; böylece her seferinde yeniden seçim yapmanız gerekmez. Farklı bir mağazada denemek isterseniz, `ikas app install` yaparak, listeden yeni mağazayı seçebilirsiniz. ### Cloudflare Tunnel ile Geliştirme `ikas app dev` komutu, uygulamanızı ikas platformu ile entegre etmek için otomatik olarak bir Cloudflare tunnel oluşturur. Bu tunnel, yerel geliştirme sunucunuzu internet üzerinden erişilebilir hale getirerek ikas platformunun uygulamanıza güvenli bir şekilde erişmesini sağlar. **Tunnel Neden Gerekli?** - ikas platformu, OAuth kimlik doğrulaması için uygulamanıza erişim sağlamak zorunda - Yerel geliştirme sunucunuz (`localhost:3000`) normalde internetten erişilemez - Cloudflare tunnel, güvenli bir köprü görevi görerek bu sorunu çözer **Teknik Detaylar** - Tunnel otomatik olarak random bir public URL oluşturur (örn: `https://xyz.trycloudflare.com`) - Bu URL, doğrudan `http://localhost:3000` adresinize yönlendirilir - Tüm trafik güvenli HTTPS ile şifrelenir - 8 saat boyunca aktif kalır, sonra yenilenmesi gerekir `ikas app dev` komutu, uygulamanızı seçtiğiniz mağaza üzerinden test edebilmeniz için mağazayı OAuth akışıyla yetkilendirir ve trafik yönlendirmesini hazırlar. Komut çalıştırıldığında: 1. Test mağazası seçimi yapılır ve uygulamanın bağlanacağı mağaza yetkilendirilir 2. Cloudflare tunnel kurulur ve public URL oluşturulur 3. Tarayıcı açılarak ikas admin paneline bağlantı yapılır 4. OAuth kimlik doğrulaması tamamlanır Detaylı kullanım adımları ve ekran görüntüleri için [ikas CLI](/docs/app-development/admin-app-quick-start/ikas-cli#ikas-app-dev) sayfasını inceleyin. ### Dashboard Görünümü `ikas app dev` komutunu çalıştırdıktan sonra, ikas yönetim panelinde uygulamanız aşağıdaki gibi görünecektir: ikas dashboard with localhost tunnel connection Yönetim paneli sağ üst tarafta cihaz bilgilerinizi görüyorsanız, yönetim paneli içerisinde localhost bağlantınız çalışıyor demektir. **Tunnel Yönetimi** - Terminal oturumunu kapatırsanız tunnel bağlantısı kesilir - Tunnel'ın 8 saat sonra otomatik olarak sona erdiğini unutmayın - Bağlantı kesildiğinde `ikas app dev` komutunu tekrar çalıştırın **Güvenlik** - Tunnel sadece ikas platform entegrasyonu için kullanılır - Local development için `pnpm dev` komutu yeterlidir - Tunnel URL'lerini üçüncü şahıslarla paylaşmayın Komut başarıyla çalıştıktan sonra uygulamanız: - ikas admin panelinde "Congratulations!" mesajı gösterir - Test mağazasına OAuth bağlantısı kurar - `http://localhost:3000` adresinde geliştirme için hazır hale gelir Bu noktada AI destekli geliştirme için [AI ile App Oluşturma](/docs/app-development/admin-app-quick-start/ai-app-development) rehberini inceleyebilirsiniz. ## Proje Yapısını İnceleme Proje oluşturulduktan sonra dizine geçin: ```bash cd my-first-app ``` ### Proje Dosya Yapısı ``` my-first-app/ ├── .cursor/ # Cursor IDE konfigürasyonu ├── .git/ # Git repository ├── .ruler/ # Ruler konfigürasyonu ├── @types/ # TypeScript tip tanımları ├── node_modules/ # Proje bağımlılıkları ├── prisma/ # Veritabanı şeması ve migrasyonlar ├── public/ # Statik dosyalar (resimler, favicon vb.) ├── src/ # Kaynak kodları │ ├── app/ # Next.js App Router │ │ ├── api/ # API rotaları │ │ │ ├── ikas/ # ikas API endpoint'leri │ │ │ ├── oauth/ # OAuth işlemleri │ │ │ └── webhook/ # Webhook handler'lar │ │ ├── authorize-store/ # Mağaza yetkilendirme │ │ ├── callback/ # Callback sayfaları │ │ ├── dashboard/ # Dashboard sayfaları │ │ └── hooks/ # Custom hooks │ ├── components/ # React bileşenleri │ │ ├── ui/ # UI bileşenleri (Shadcn/ui) │ │ ├── Loading/ # Loading bileşeni │ │ └── webhook-page/ # Webhook sayfası bileşenleri │ ├── globals/ # Global dosyalar │ ├── helpers/ # Yardımcı fonksiyonlar │ ├── lib/ # Kütüphaneler │ │ └── ikas-client/ # ikas API istemcisi │ │ └── generated/ # Otomatik üretilen kodlar │ └── models/ # Veri modelleri │ └── auth-token/ # Auth token modeli ├── .env.example # Çevre değişkenleri örneği ├── .gitignore # Git ignore dosyası ├── AGENTS.md # Ajan dokümantasyonu ├── README.md # Proje dokümantasyonu ├── components.json # Shadcn/ui konfigürasyonu ├── eslint.config.mjs # ESLint konfigürasyonu ├── ikas.config.json # ikas CLI konfigürasyonu ├── next.config.js # Next.js konfigürasyonu ├── package.json # Paket yöneticisi konfigürasyonu ├── pnpm-lock.yaml # Paket kilit dosyası ├── postcss.config.mjs # PostCSS konfigürasyonu └── tsconfig.json # TypeScript konfigürasyonu ``` ## Tech-stack `ikas app init` komutu ile oluşturulan starter projesinin tech-stack'i: **Frontend & Framework** - Next.js 15 App Router + React 19 - TypeScript 5 (strict mode) - Tailwind CSS v4 + shadcn/ui bileşenleri **Kimlik Doğrulama & API** - OAuth 2.0 ile ikas entegrasyonu - GraphQL Code Generation (@ikas/admin-api-client) - Iron Session (server-side session yönetimi) - JWT tabanlı kimlik doğrulama **Veritabanı & ORM** - Prisma ORM - SQLite (local development) - AuthToken model ile token yönetimi **Geliştirici Araçları** - ESLint + Prettier konfigürasyonu - Ruler AI agent konfigürasyonu - MCP sunucuları (shadcn, ikas) Token aldıktan sonra ikas GraphQL API'sini kullanarak mağaza verilerine erişebilirsiniz. Detaylı SDK kullanımı, GraphQL Playground ve code generation için [ikas SDK Kullanımı](/docs/app-development/ikas-sdk-kullanimi) rehberine göz atın. --- ## Başlangıç Projesi Özellikleri ### Proje Komutları Starter projesinde kullanabileceğiniz komutlar: | Komut | Açıklama | |-------|----------| | `ikas app dev` | Geliştirme sunucusunu başlatır | | `pnpm build` | Production build oluşturur | | `pnpm start` | Production sunucusunu çalıştırır | | `pnpm lint` | ESLint ile kod kontrolü | | `pnpm codegen` | GraphQL tiplerini üretir | | `pnpm build:watch` | TypeScript sürekli derleme | | `pnpm prisma:init` | İlk veritabanı kurulumu (generate + push) | | `pnpm prisma:migrate` | Veritabanı migrasyonlarını çalıştırır | | `pnpm prisma:studio` | Veritabanı görüntüleyicisini açar | | `pnpm prisma:generate` | Prisma client'ını üretir | | `pnpm apply:ai-rules` | Ruler AI kurallarını uygular | ### OAuth Workflow Starter projesi kapsamlı bir OAuth 2.0 akışı sunar: **1. Giriş Kontrolü** (`/`): Kullanıcı iframe içinde mi ve geçerli token var mı kontrol edilir **2. Mağaza Yetkilendirmesi** (`/authorize-store`): Cloudflare tunnel kurulduktan sonra `localhost:3000/authorize-store` sayfasında kullanıcı mağaza adını girer **3. OAuth Başlatma** (`/api/oauth/authorize/ikas`): ikas yetkilendirme URL'ine yönlendirme **4. Callback İşleme** (`/api/oauth/callback/ikas`): Token alışverişi ve veritabanına kaydetme **5. Dashboard Erişimi** (`/dashboard`): Kimlik doğrulanmış kullanıcı arayüzü ### API Endpoints Starter proje aşağıdaki API endpoint'leri içerir: | Endpoint | Method | Açıklama | |----------|--------|----------| | `/api/oauth/authorize/ikas` | GET | OAuth yetkilendirme sürecini başlatır | | `/api/oauth/callback/ikas` | GET | OAuth callback'ini işler ve token'ı kaydeder | | `/api/ikas/get-merchant` | GET | Mağaza bilgilerini getirir (JWT gerekli) | ### GraphQL Workflow Proje ikas Admin GraphQL API'si ile çalışmak için optimize edilmiştir: ```bash # GraphQL tiplerini üret pnpm codegen # Prisma veritabanını başlat pnpm prisma:init # Prisma Studio'yu aç (veritabanı görüntüleyici) pnpm prisma:studio ``` **1.** `src/lib/ikas-client/graphql-requests.ts` dosyasında GraphQL dokümanlarınızı tanımlayın **2.** `pnpm codegen` komutu ile tip tanımlarını oluşturun **3.** MCP sunucusu ile API operasyonlarını keşfedin **4.** `getIkas(token)` ile client oluşturun ve sorguları çalıştırın ### Environment Variables Geliştirme için gerekli environment variables `.env.local` dosyasında tanımlanır: - `NEXT_PUBLIC_GRAPH_API_URL`: ikas Admin GraphQL URL - `NEXT_PUBLIC_ADMIN_URL`: ikas Admin base URL - `NEXT_PUBLIC_CLIENT_ID`: OAuth Client ID (otomatik ayarlanır) - `CLIENT_SECRET`: OAuth Client Secret (otomatik ayarlanır) - `NEXT_PUBLIC_DEPLOY_URL`: Uygulama public URL'i - `SECRET_COOKIE_PASSWORD`: Iron-session için rastgele string --- ## Güvenlik Mimarisi Starter proje kapsamlı bir güvenlik mimarisi sunar: **Token Yönetimi** - OAuth 2.0 ile güvenli kimlik doğrulama - Access ve Refresh token'lar Prisma ile güvenli depolama - JWT ile kısa ömürlü browser-server iletişimi - Otomatik token yenileme mekanizması **Kimlik Doğrulama Akışı** - Server-side only API çağrıları (browser'dan direkt GraphQL yasak) - Iron-session ile güvenli server session yönetimi - AuthTokenManager ile veritabanı tabanlı token saklama - getUserFromRequest ile JWT doğrulaması **Veri Güvenliği** - Token'lar asla loglara yazılmaz - Client'a sensitive token'lar expose edilmez - onCheckToken ile otomatik token refresh - Strict TypeScript ile tip güvenliği --- ## Geliştirme Süreci Yeni özellik geliştirmek için önerilen adım adım süreç: **1. GraphQL Operasyon Keşfi** - ikas Admin API dokümantasyonunu incele - Gerekli query/mutation'ların şemasını öğren - API endpoint'lerinin parametrelerini ve response'larını analiz et **2. GraphQL Dokuman Ekleme** - `src/lib/ikas-client/graphql-requests.ts` dosyasına gql query ekle - `pnpm codegen` komutu ile TypeScript tiplerini oluştur **3. API Route Geliştirme** - `src/app/api/` altında yeni endpoint oluştur - `getUserFromRequest` ile JWT doğrulaması yap - `getIkas(token)` ile GraphQL client oluştur - `ikasClient.queries.yourQuery()` ile API çağrısı yap **4. Frontend Entegrasyon** - `ApiRequests` ile frontend-backend bridge kullan - `src/components/` altında UI bileşenleri oluştur - shadcn/ui bileşenlerini projeye entegre et **5. Test ve Doğrulama** - `pnpm lint` ile kod kontrolü - `pnpm build` ile production build test - Prisma Studio ile veritabanı kontrolü --- ## Geliştirme Standartları Starter projede uyulması gereken temel geliştirme kuralları: **GraphQL Kullanım Kuralları** - Inline GraphQL strings YASAK - sadece `graphql-requests.ts` kullan - Yeni operasyon eklemeden önce ikas API dokümantasyonunu incele - Her `graphql-requests.ts` değişikliğinde `pnpm codegen` çalıştır - Browser'dan direkt ikas API çağrısı YASAK - sadece server routes **Kod Organizasyonu** - API routes: `src/app/api/*` altında, JWT doğrulaması zorunlu - UI logic: `src/components/*` altında, business logic sayfalarda değil - `ApiRequests` ile frontend-backend bridge kullan - Strict TypeScript, `any` kullanma **Commit Format** - Conventional Commits formatı zorunlu - Format: `(): ` - Örnek: `feat(auth): add token refresh mechanism` AI agent'lar (Claude, Cursor, etc.) ile geliştirme yaparken uyulması gereken ek kurallar ve MCP konfigürasyonları için [AI ile App Oluşturma](/docs/app-development/admin-app-quick-start/ai-app-development) sayfasını inceleyin. --- ## Veritabanı Yönetimi Starter proje Prisma ORM ile SQLite veritabanı kullanır: **Prisma Schema (`prisma/schema.prisma`)** - SQLite provider (local development için) - AuthToken model ile OAuth token saklama - Otomatik createdAt/updatedAt alanları - Refresh token ve expiry date tracking **AuthToken Model Alanları** ```prisma model AuthToken { id String @id merchantId String authorizedAppId String? @unique accessToken String refreshToken String expiresIn Int expireDate DateTime } ``` **Veritabanı Komutları** - `pnpm prisma:init`: İlk kurulum (generate + push) - `pnpm prisma:migrate`: Migration oluştur ve uygula - `pnpm prisma:studio`: GUI veritabanı görüntüleyici - `pnpm prisma:generate`: Prisma client yenile --- ## Önemli Dosyalar Starter projede bulunan önemli konfigürasyon dosyaları: **`ikas.config.json`** ```json { "portMapping": { "default": 3000 }, "oauthRedirectPath": "/api/oauth/callback/ikas", "runCommand": "pnpm run dev" } ``` **`components.json` (shadcn/ui)** - Tailwind CSS konfigürasyonu - UI bileşen yolları ve stilleri - shadcn/ui otomatik setup **`.env.example`** - Gerekli çevre değişkenleri şablonu - ikas API URL'leri ve OAuth ayarları - Session güvenliği için SECRET_COOKIE_PASSWORD **`src/globals/config.ts`** - Çevre değişkenlerini TypeScript'e aktarma - OAuth scope konfigürasyonu - API endpoint yapılandırması