player/PUBLISHING.md

Gitea Self-Hosted npm Registry'ye Yayınlama Kılavuzu

Bu kılavuz, @alper/video-player paketinin Gitea self-hosted npm registry'ye nasıl yayınlanacağını adım adım açıklar.

---

📋 Ön Gereksinimler

• ✅ Çalışan bir Gitea sunucusu
• ✅ Gitea hesabınıza erişim
• ✅ Node.js ve pnpm/npm kurulu
• ✅ Bu proje build edilmiş durumda

---

🔑 Adım 1: Gitea Access Token Oluşturma

1. Gitea web arayüzüne giriş yapın

   • Tarayıcınızda https://gitea.yourdomain.com adresine gidin
   • Kullanıcı adı ve şifrenizle giriş yapın

2. Settings sayfasına gidin

   • Sağ üst köşedeki profil resmine tıklayın
   • "Settings" seçeneğini seçin

3. Applications bölümüne gidin

   • Sol menüden "Applications" seçeneğini tıklayın

4. Yeni token oluşturun

   • "Generate New Token" butonuna tıklayın
   • Token Name: npm-publish-video-player (veya istediğiniz bir isim)
   • Permissions (Yetkiler):
     • ✅ write:package - Paket yükleme yetkisi
     • ✅ read:package - Paket okuma yetkisi (diğer projelerde kullanmak için)
   • "Generate Token" butonuna tıklayın

5. Token'ı kopyalayın

   • ⚠️ ÖNEMLİ: Token sadece bir kez gösterilir!
   • Token'ı güvenli bir yere kaydedin (örn: password manager)
   • Örnek token: 1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t

---

📝 Adım 2: package.json Dosyasını Düzenleme

package.json dosyasını açın ve aşağıdaki bilgileri kendi Gitea sunucunuza göre düzenleyin:

{
  "repository": {
    "type": "git",
    "url": "https://gitea.yourdomain.com/your-username/video-player.git"
  },
  "publishConfig": {
    "registry": "https://gitea.yourdomain.com/api/packages/your-username/npm/"
  }
}

Değiştirilmesi gerekenler:

• gitea.yourdomain.com → Gitea sunucunuzun domain'i
• your-username → Gitea kullanıcı adınız

Örnek:

{
  "repository": {
    "type": "git",
    "url": "https://git.example.com/alper/video-player.git"
  },
  "publishConfig": {
    "registry": "https://git.example.com/api/packages/alper/npm/"
  }
}

---

🔐 Adım 3: npm Login ile Kimlik Doğrulama

Terminal'de aşağıdaki komutu çalıştırın:

npm config set @alper:registry https://gitea.yourdomain.com/api/packages/your-username/npm/

npm login --scope=@alper --registry=https://gitea.yourdomain.com/api/packages/your-username/npm/

Değiştirin:

• gitea.yourdomain.com → Gitea domain'iniz
• your-username → Gitea kullanıcı adınız

Giriş bilgileri istenecek:

Username: your-gitea-username
Password: 1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t  (Adım 1'de oluşturduğunuz token)
Email: your-email@example.com

Not: Password kısmına Gitea şifrenizi değil, token'ı girin!

Başarılı olursa şu mesajı görmelisiniz:

Logged in as your-username on https://gitea.yourdomain.com/api/packages/your-username/npm/.

---

🏗️ Adım 4: Library Build

Paketi yayınlamadan önce production build alın:

# TypeScript compile ve Vite build
pnpm run build:lib

Build başarılı olduysa:

• dist/ klasöründe şu dosyalar oluşacak:
  • ✅ video-player.js (ESM format)
  • ✅ video-player.umd.cjs (UMD format)
  • ✅ index.d.ts (TypeScript type definitions)
  • ✅ style.css (CSS dosyası)

Kontrol edin:

ls dist/
# veya Windows'ta:
dir dist\

---

📤 Adım 5: npm Publish

Artık paketi Gitea registry'ye yayınlayabilirsiniz:

npm publish

Başarılı olursa şu çıktıyı görmelisiniz:

npm notice
npm notice package: @alper/video-player@0.1.0
npm notice === Tarball Contents ===
npm notice 1.2kB  package.json
npm notice 8.5kB  dist/video-player.js
npm notice 7.8kB  dist/video-player.umd.cjs
npm notice 2.1kB  dist/index.d.ts
npm notice 3.4kB  dist/style.css
npm notice === Tarball Details ===
npm notice name:          @alper/video-player
npm notice version:       0.1.0
npm notice package size:  23.0 kB
npm notice unpacked size: 45.2 kB
npm notice total files:   5
+ @alper/video-player@0.1.0

---

✅ Adım 6: Yayını Doğrulama

Gitea Web Arayüzünde Kontrol

1. Gitea'ya giriş yapın
2. Üst menüden "Packages" seçeneğine tıklayın
3. @alper/video-player paketini görmelisiniz
4. Pakete tıklayarak detayları görüntüleyin

Komut Satırından Kontrol

npm view @alper/video-player --registry=https://gitea.yourdomain.com/api/packages/your-username/npm/

---

🔄 Adım 7: Güncelleme Yayınlama

Paket üzerinde değişiklik yaptığınızda yeni versiyon yayınlamak için:

1. Versiyonu Güncelle

# Patch version (0.1.0 → 0.1.1) - Bug fix
npm version patch

# Minor version (0.1.0 → 0.2.0) - Yeni özellik
npm version minor

# Major version (0.1.0 → 1.0.0) - Breaking change
npm version major

# Veya manuel olarak package.json'da version'ı değiştirin

2. Build Al

pnpm run build:lib

3. Yayınla

npm publish

4. Git'e Push Et (Opsiyonel)

git push && git push --tags

---

🚀 Diğer Projelerde Kullanma

Adım 1: Diğer Projenizde .npmrc Oluşturun

Projenizin root dizininde .npmrc dosyası oluşturun:

@alper:registry=https://gitea.yourdomain.com/api/packages/your-username/npm/
//gitea.yourdomain.com/api/packages/your-username/npm/:_authToken=${GITEA_TOKEN}

Adım 2: Environment Variable Ayarlayın

# Linux/Mac
export GITEA_TOKEN=1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t

# Windows (PowerShell)
$env:GITEA_TOKEN="1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t"

# Veya .env dosyasına ekleyin:
echo "GITEA_TOKEN=1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t" >> .env

Adım 3: Paketi Yükleyin

pnpm add @alper/video-player

Adım 4: Kullanın

import { VideoPlayer } from '@alper/video-player';
import '@alper/video-player/styles.css';

function App() {
  return <VideoPlayer src="/video.mp4" />;
}

Detaylı kullanım örnekleri için README-USAGE.md dosyasına bakın.

---

🐛 Sorun Giderme

1. "401 Unauthorized" Hatası

Sebep: Token yanlış veya süresi dolmuş

Çözüm:

# Tekrar login olun
npm login --scope=@alper --registry=https://gitea.yourdomain.com/api/packages/your-username/npm/

2. "403 Forbidden" Hatası

Sebep: Token'da write:package yetkisi yok

Çözüm:

• Gitea'da yeni token oluşturun (Adım 1)
• write:package yetkisini seçin
• Yeni token ile login olun

3. "Package already exists" Hatası

Sebep: Aynı versiyonu tekrar yayınlamaya çalışıyorsunuz

Çözüm:

# Versiyonu artırın
npm version patch
npm publish

4. "dist/ folder not found" Hatası

Sebep: Build alınmamış

Çözüm:

pnpm run build:lib
npm publish

5. ".npmrc not working" Sorunu

Sebep: Environment variable ayarlanmamış

Çözüm:

# Token'ı kontrol edin
echo $GITEA_TOKEN  # Linux/Mac
echo $env:GITEA_TOKEN  # Windows PowerShell

# Ayarlanmamışsa ayarlayın
export GITEA_TOKEN=your-token  # Linux/Mac

6. "Cannot find module" Hatası (Diğer Projelerde)

Sebep: .npmrc dosyası yok veya yanlış yapılandırılmış

Çözüm:

• .npmrc dosyasının proje root'unda olduğundan emin olun
• Registry URL'inin doğru olduğunu kontrol edin
• pnpm install veya npm install komutunu tekrar çalıştırın

---

📚 Faydalı Komutlar

# Hangi registry kullanılıyor?
npm config get @alper:registry

# Login durumunu kontrol et
npm whoami --registry=https://gitea.yourdomain.com/api/packages/your-username/npm/

# Paket bilgilerini görüntüle
npm view @alper/video-player

# Yüklü versiyonu kontrol et (diğer projelerde)
pnpm list @alper/video-player

# Tüm npm ayarlarını temizle (sorun yaşıyorsanız)
npm config delete @alper:registry

# Package-lock veya pnpm-lock dosyasını temizle
rm package-lock.json  # veya pnpm-lock.yaml
pnpm install

---

🔒 Güvenlik Notları

1. Token'ları asla git'e commit etmeyin

   • .npmrc dosyasını .gitignore'a ekleyin
   • Token'ları environment variable olarak kullanın

2. Token yetkilerini minimumda tutun

   • Sadece gerekli yetkileri verin (read:package, write:package)

3. Token'ları düzenli olarak yenileyin

   • Eski token'ları silin
   • Yeni token oluşturun ve güncelleyin

4. Production ortamda environment variables kullanın

   • .env dosyasını git'e eklemeyin
   • CI/CD sistemlerinde secret manager kullanın

---

✅ Checklist

Video Player Yayınlama:

• Gitea access token oluşturdum
• package.json'da repository ve publishConfig güncelledim
• npm login ile kimlik doğrulaması yaptım
• pnpm run build:lib ile build aldım
• npm publish ile yayınladım
• Gitea web arayüzünde paketi gördüm

Diğer Projelerde Kullanma:

• Projede .npmrc dosyası oluşturdum
• GITEA_TOKEN environment variable'ını ayarladım
• pnpm add @alper/video-player ile yükledim
• CSS dosyasını import ettim
• VideoPlayer component'ini kullandım

---

Başarılar! 🎉

Artık video player kütüphanenizi tüm projelerinizde kullanabilirsiniz.