Nuvaka › Geliştirici belgeleri

Nuvaka Apps geliştirici belgeleri

Nuvaka General App'e kendi uygulamanı ekle: HTML, CSS ve JavaScript ile bir arayüz, istersen arka planda çalışan bir betik ve kullanıcının izin verdiği ölçüde Nuvaka verisi (notlar, bulut dosyaları, pano havuzu, mail…). Kullanıcılar uzantını uygulamada Uygulamalar › Mağaza'dan kurar.

Nuvaka Apps nedir#

• Paket: uzantı bir .nvx dosyasıdır (ZIP). Kökünde nuvaka.json manifesti bulunur. Kimlik <kullanıcı-adın>.<ad> biçimindedir, ör. tarikgkhsn.faturaci; yayınlandıktan sonra değişmez.
• Arayüz: kum havuzlu bir çerçevede (iframe) açılan HTML sayfası. Manifestteki her pages öğesi Uygulamalar menüsünde yayıncı başlığının altında görünür. Uygulama çerçevenin üstünde her zaman bir bilgi çubuğu gösterir (ad, sürüm, güven rozeti, yayıncı, İzinler, Durdur).
• Arka plan: isteğe bağlı, tek dosyalık bir JavaScript modülü. QuickJS motorunda, uzantı başına ayrı çalışır; zamanlama (every 15m, daily 09:00…) ve olaylarla (app.started, notes.changed…) tetiklenir.
• nuvaka nesnesi: uygulama her çerçeveye ve arka plana global nuvaka nesnesini kendisi ekler; kütüphane kurmadan kullanırsın. @nuvaka/extension-sdk paketi yalnız TypeScript tipleri, tipli hata sınıfları ve testler için sahte bir nuvaka verir.
• İzinler: uzantı yalnız manifestte istediği ve kullanıcının verdiği izinleri kullanabilir. Mail, bağlantı şifreleri ve Nuvaka dosyalarına yazma gibi kritik izinler her kullanımda ayrıca sorulur. Bkz. Kavramlar.
• Veri: her uzantının sunucuda kendi anahtar-değer deposu vardır (izin gerekmez, kota en çok 100 MB). Depo cihazlar arası eşitlenir ve her yazma okunan sürümü taşır (MVCC).
• Platform: uzantılar şimdilik masaüstü uygulamasında (Windows, Linux, macOS) çalışır.

10 dakikada ilk uzantı#

Gerekenler: Node.js 20 ya da üstü, e-postası doğrulanmış bir Nuvaka hesabı ve masaüstü uygulaması.

1. İskeleti oluştur

   npm create @nuvaka/extension merhaba -- --username kullanici-adin --ui --background
   cd merhaba
   npm install

   --username Nuvaka kullanıcı adındır; kimlik kullanici-adin.merhaba olur. Oluşan dosyalar: nuvaka.json, icon.svg, index.html, app.js, style.css, background.js, test/extension.test.js, package.json. --ui ya da --background vermezsen ikisi birden gelir.

2. Denetle

   npx nuvaka-ext lint

   Sunucunun yükleme sırasında uyguladığı kuralların aynısı: manifest şeması, dosya türleri, yasak kod kalıpları, kodda kullanılan nuvaka.* ad alanlarıyla izinlerin uyumu. Ayrıntı: Güvenlik kuralları.

3. Uygulamada dene

   Uygulamada Profil sayfasının Profil sekmesinde, Geliştirici başlığı altındaki Geliştirici modu kutusunu işaretle. Sonra Uygulamalar › Uygulamaları yönet › Klasörden yükle ile uzantı klasörünü seç. Klasör imzasız ve yalnız bu cihazda çalışır; sürümü dev görünür ve manifestteki tüm izinler verilmiş sayılır. Değişiklikten sonra listedeki Yeniden yükle düğmesini kullan.

   npx nuvaka-ext dev

   dev komutu klasörü izler ve her değişiklikte lint çalıştırır. Uygulamayı kaynaktan (debug derleme) çalıştırıyorsan klasörü açılışta yükleyen NUVAKA_EXT_DEV_DIR komutunu da yazar.

   Sunucu uçları kurulum ister

   Klasörden yüklenen uzantıda yerel yetenekler (arayüz, net, files, yerel pano, ui.notify) çalışır. Depolama, notlar, pano havuzu, push gibi sunucu uçları ise uzantı hesabında kurulu değilse çalışmaz: bunları denemek için bir sürüm yayınlayıp kur.

4. Geliştirici token'ı al ve giriş yap

   Profil › Geliştirici › Geliştirici token'ları bölümünden bir token üret (nvd_ ile başlar, bir kez gösterilir, 1 yıl geçerlidir).

   npx nuvaka-ext login --token nvd_xxxxxxxx
   npx nuvaka-ext whoami

5. (Önerilir) Yayıncı imza anahtarı

   npx nuvaka-ext keys create

   Çıktıdaki genel anahtarı Profil › Geliştirici › Yayıncı imza anahtarları bölümüne ekle. Bundan sonra her yükleme imzalı olmak zorundadır; token çalınsa bile anahtar olmadan sürüm yayınlanamaz.

6. Yayınla

   npx nuvaka-ext publish --changelog "İlk sürüm"

   Sonuç published, review ya da rejected olur. Yayıncının ilk uzantısı incelemeye düşer; onaylanınca Mağaza'da görünür. Bkz. Yayınlama ve inceleme.

7. Kur

   Uygulamada Uygulamalar › Mağaza'da uzantını bul ve kur. Kurulum hesabının tüm cihazlarına eşitlenir.

İlk kod#

Arayüzde nuvaka.ready kabuk bağlanınca çözülür ve bağlamı (page, locale, theme) verir. Çerçevede localStorage yoktur; kalıcı veri için nuvaka.storage kullanılır.

// app.js (arayüz)
const out = document.getElementById('count')

nuvaka.ready.then(async () => {
  const r = await nuvaka.storage.get('count')      // { value, version } | null
  out.textContent = r ? r.value : 0
})

document.getElementById('inc').onclick = async () => {
  // Oku → değiştir → okunan sürümle yaz; başka cihaz araya girerse güncel değerle yeniden dener
  const r = await nuvaka.storage.update('count', (n) => (n || 0) + 1)
  out.textContent = r.value
}

// Başka cihaz ya da arka plan yazdı (yalnız daha yeni sürümler gelir)
nuvaka.storage.onChanged((key, c) => { if (key === 'count' && !c.deleted) out.textContent = c.value })

// background.js (arka plan, QuickJS; tek dosya, import yok)
nuvaka.on('schedule', async ({ schedule, at }) => {
  await nuvaka.ui.notify('Merhaba', `Zamanlanmış görev çalıştı (${schedule})`)
})

Belgeler#

Sürümler#

Bu belgeler API v1 içindir; manifestte "apiVersion": 1 yazılır. Kırıcı bir değişiklik yeni bir API sürümüyle gelir. @nuvaka/extension-cli ve @nuvaka/extension-sdk paketlerinin ana sürümü desteklediği API sürümüdür (1.x = API v1).

Nuvaka Apps API v1 · son güncelleme 2026-09-27