# Kurulum
Package: @dataliva/livalib
Description: @dataliva/livalib'i bir React 19 projesine kurma ve yapılandırma rehberi.

`@dataliva/livalib`, DevExtreme çekirdeği üzerine kurulu, **ESM-only** bir React 19
bileşen kütüphanesidir. Dataliva'nın özel npm registry'sinden (`https://v.dataliva.com/`)
dağıtılır. Bu sayfa paketi sıfırdan bir projeye eklemeyi anlatır.

## Gereksinimler

| Bağımlılık | Sürüm |
|------|------|
| React / React DOM | `^19` |
| `devextreme` | `^25.2.3` (peer) |
| `devextreme-react` | `^25.2.3` (peer) |
| `@dataliva/livalib` | Mevcut Sürüm |

livalib, `devextreme` ve `devextreme-react`'i **peer dependency** olarak kabul eder —
bunları projenize kendiniz kurmanız gerekir.

## 1. Özel registry'yi yapılandırın

`@dataliva` paketleri npmjs.org'da değil, Dataliva registry'sindedir. Proje köküne
bir `.npmrc` ekleyin:

```ini
registry=https://registry.npmjs.org/

@dataliva:registry=https://v.dataliva.com/
//v.dataliva.com/:_authToken=${DATALIVA_NPM_TOKEN}

always-auth=true
```

`DATALIVA_NPM_TOKEN` ortam değişkenini, kurulumdan **önce** kabuğunuzda tanımlayın
(token'ı `.npmrc`'ye asla düz metin yazıp commit'lemeyin):

```bash
# macOS / Linux
export DATALIVA_NPM_TOKEN=xxxxxxxx-xxxx-xxxx

# Windows PowerShell
$env:DATALIVA_NPM_TOKEN = "xxxxxxxx-xxxx-xxxx"
```

## 2. Paketleri kurun

```bash
npm install @dataliva/livalib devextreme devextreme-react
```

## 3. CSS'leri doğru sırayla import edin

livalib bileşenleri, aktif **DevExtreme Fluent** temasıyla stillenir. Uygulama
girişinde önce DevExtreme tema CSS'ini, **sonra** livalib stillerini yükleyin.
Sıra önemlidir — livalib, DX temasının üzerine ince ayar yapar.

```tsx
// Uygulama giriş noktası (ör. main.tsx / layout.tsx)
import "devextreme/dist/css/dx.fluent.blue.light.css"; // 1) DevExtreme Fluent teması
import "@dataliva/livalib/index.css";                  // 2) livalib stilleri
```

Farklı bir tema (dark, soft blue vb.) için ilgili DX Fluent CSS dosyasını değiştirin.
Ayrıntılar için [Temalar](/livalib/theme-light) bölümüne bakın.

## 4. DevExtreme lisans anahtarını ayarlayın

DevExtreme ticari bir lisans gerektirir. Uygulama ilk render'dan **önce**, bir kez
`config({ licenseKey })` çağrısı yapın:

```tsx
import config from "devextreme/core/config";

config({ licenseKey: import.meta.env.VITE_DEVEXTREME_LICENSE_KEY });
```

Anahtarı bir ortam değişkeninde tutun; kaynak koda gömmeyin:

```ini
# .env
VITE_DEVEXTREME_LICENSE_KEY=xxxxxxxx
```

> **Next.js notu:** Vite yerine Next kullanıyorsanız `import.meta.env.VITE_*`
> yerine `process.env.NEXT_PUBLIC_DEVEXTREME_LICENSE_KEY` kullanın ve `config()`
> çağrısını bir `"use client"` bileşeninde yapın (bkz. aşağıdaki SSR notu).

## 5. Bildirim (toast) sağlayıcısını ekleyin

`Notifications` bileşeni, `notify()` çağrılarının render edileceği tek bir kök
kapsayıcıdır. Uygulama ağacının en üstüne bir kez yerleştirin:

```tsx
import { Notifications } from "@dataliva/livalib";

createRoot(document.getElementById("root")!).render(
  <>
    <Notifications position="bottom-right" />
    <App />
  </>
);
```

## Tam örnek — Vite `main.tsx`

```tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import config from "devextreme/core/config";

import "devextreme/dist/css/dx.fluent.blue.light.css";
import "@dataliva/livalib/index.css";

import { Notifications } from "@dataliva/livalib";
import App from "./App";

config({ licenseKey: import.meta.env.VITE_DEVEXTREME_LICENSE_KEY });

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <Notifications position="bottom-right" />
    <App />
  </StrictMode>
);
```

## İlk bileşeninizi kullanın

```tsx
import { LivaButton } from "@dataliva/livalib";

export default function Demo() {
  return <LivaButton text="Merhaba Livalib" type="success" />;
}
```

Buradan sonrası için soldaki menüden bir bileşen seçip canlı örnekleri ve
prop tablolarını inceleyebilirsiniz.

## SSR (Next.js) notları

livalib bileşenleri DevExtreme'e dayandığı için render sırasında `window` /
`document`'a erişir ve **sunucuda render edilemez**. Next.js App Router'da:

- Döküman/metin içeriğiniz sunucuda render edilebilir (SSR) — bu site de öyle
  çalışır, JS kapalıyken bile sayfa metni ve başlıklar görünür.
- livalib bileşenlerini **client island** olarak yalıtın: demoları `"use client"`
  dosyalarına koyun veya `next/dynamic(() => import(...), { ssr: false })` ile
  yükleyin.
- `next.config.ts` içinde şunları ekleyin:

```ts
const nextConfig = {
  transpilePackages: ["@dataliva/livalib", "devextreme", "devextreme-react"],
  turbopack: { resolveAlias: { "../moment": "moment" } },
};
```

`resolveAlias`, livalib'in bundle'ladığı moment locale dosyalarının UMD
`'../moment'` referansını gerçek `moment` paketine yönlendirir; olmazsa Turbopack
derleme hatası verir.

## Sorun giderme

| Belirti | Çözüm |
|------|------|
| `401 Unauthorized` (npm install) | `DATALIVA_NPM_TOKEN` tanımlı değil veya süresi dolmuş |
| Bileşenler stilsiz görünüyor | CSS import sırası yanlış — DX teması livalib'den **önce** gelmeli |
| Konsolda DevExtreme lisans uyarısı | `config({ licenseKey })` çağrısı eksik veya render'dan sonra |
| Next.js'te `window is not defined` | Bileşeni client island'a taşıyın (`"use client"` / `dynamic ssr:false`) |
| Turbopack `../moment` çözülemedi | `next.config.ts`'e `resolveAlias` ekleyin |