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:

```json
{
  "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:**
```json
{
  "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:

```bash
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:

```bash
# 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:**
```bash
ls dist/
# veya Windows'ta:
dir dist\
```

---

## 📤 Adım 5: npm Publish

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

```bash
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

```bash
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

```bash
# 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

```bash
pnpm run build:lib
```

### 3. Yayınla

```bash
npm publish
```

### 4. Git'e Push Et (Opsiyonel)

```bash
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:

```ini
@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

```bash
# 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

```bash
pnpm add @alper/video-player
```

### Adım 4: Kullanın

```tsx
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](./README-USAGE.md) dosyasına bakın.

---

## 🐛 Sorun Giderme

### 1. "401 Unauthorized" Hatası

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

**Çözüm:**
```bash
# 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:**
```bash
# Versiyonu artırın
npm version patch
npm publish
```

### 4. "dist/ folder not found" Hatası

**Sebep:** Build alınmamış

**Çözüm:**
```bash
pnpm run build:lib
npm publish
```

### 5. ".npmrc not working" Sorunu

**Sebep:** Environment variable ayarlanmamış

**Çözüm:**
```bash
# 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

```bash
# 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.