Add npm registry configuration for Gitea
This commit is contained in:
hibna
+397
@@ -0,0 +1,397 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user