# Publicar NexaReport para que otros lo usen

## Opciones de distribución

| Método | Para quién | Complejidad | URL ejemplo |
|--------|-----------|-------------|-------------|
| **npm registry** | Cualquiera con `pnpm install` | Baja | `ppnpm install nexabase-report` |
| **GitHub Releases** | Equipos internos, CI/CD | Baja | `npm i github:nexabase/nexabase-report` |
| **Verdaccio (privado)** | Empresa interna | Media | `ppnpm install nexabase-report --registry=https://npm.miempresa.com` |
| **CDN (unpkg/jsDelivr)** | Quick demo, prototipos | Baja | `<script src="https://unpkg.com/nexabase-report">` |

---

## 1. npm registry (recomendado)

### Prerequisitos
```bash
# Crear cuenta en npmjs.com (si no tienes)
npm adduser
# Username: tu-usuario-nexabase
# Password: ******
# Email: dev@nexabase.dev
```

### Preparar el paquete
```bash
# 1. Verificar que package.json esté correcto
#    - "private" debe ser false (ya lo está)
#    - version debe incrementarse
#    - "files" debe incluir dist/, docs/, examples/
#    - "exports" debe definir entry points

# 2. Build de producción
pnpm run build

# 3. Verificar qué se va a publicar
npm pack --dry-run
# Debe mostrar: dist/, docs/, examples/, README.md
```

### Publicar
```bash
# Publicar versión
ppnpm publish --access public

# O si usas scoped package (@nexabase/report):
ppnpm publish --access public
```

### Consumir
```bash
# En cualquier proyecto:
pnpm install nexabase-report
# o
pnpm install @nexabase/nexabase-report
```

### Actualizar versión
```bash
# patch: 0.1.0 → 0.1.1
pnpm version patch

# minor: 0.1.0 → 0.2.0
pnpm version minor

# major: 0.1.0 → 1.0.0
npm version major

# Luego publicar
pnpm publish
```

---

## 2. GitHub Releases

```bash
# Taggear versión
git tag v0.1.0
git push origin v0.1.0

# En GitHub → Releases → Draft new release → v0.1.0
# Adjuntar el .tgz generado por `npm pack`
```

Consumir desde otro proyecto:
```bash
pnpm install github:nexabase/nexabase-report#v0.1.0
```

---

## 3. Registry privado (Verdaccio)

Para empresas que no quieren publicar en npm público:

```bash
# Instalar Verdaccio
pnpm install -g verdaccio
verdaccio

# En .npmrc del proyecto consumidor:
# registry=https://npm.miempresa.com/

# Publicar
pnpm publish --registry=http://localhost:4873
```

---

## 4. CDN (sin instalación)

Una vez publicado en npm, automáticamente disponible en:

```html
<!-- jsDelivr (recomendado, latest tag) -->
<script src="https://cdn.jsdelivr.net/npm/nexabase-report/dist/nexabase-report.umd.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/nexabase-report/dist/style.css">

<!-- unpkg -->
<script src="https://unpkg.com/nexabase-report/dist/nexabase-report.umd.js"></script>

<!-- Uso -->
<script>
  NexaReport.registerNexaReport();
  const viewer = document.getElementById('miViewer');
  viewer.definition = { /* ... */ };
  viewer.data = [ /* ... */ ];
</script>
```

---

## Estructura del paquete publicado

```
nexabase-report-0.2.x.tgz
├── dist/
│   ├── nexabase-report.es.js      # ESM (import/export)
│   ├── nexabase-report.umd.js     # UMD (script tag)
│   ├── index.d.ts                 # Types principales
│   ├── types/report.d.ts          # Types del dominio
│   └── style.css                  # Estilos completos
├── docs/
│   ├── API_REST.md
│   ├── EXPORT_REGRESSION.md
│   ├── EXTERNAL_INTEGRATION.md
│   ├── PUBLISHING.md
│   ├── QA_PLAN.md
│   └── VIEWER_API.md
├── examples/
│   ├── report-factura.json
│   ├── report-productos.json
│   ├── report-master-detail-ordenes.json
│   ├── report-crosstab-categoria-mes.json
│   └── ... (11 ejemplos)
└── README.md
```

---

## Checklist antes de publicar

- [ ] `pnpm run build` pasa sin errores
- [ ] `package.json` tiene `"private": false` (o no tiene la clave)
- [ ] `version` incrementada correctamente
- [ ] `files` incluye `dist/`, `docs/`, `examples/`
- [ ] `exports` define todos los entry points
- [ ] `README.md` tiene instrucciones de uso
- [ ] `CHANGELOG.md` actualizado (opcional pero recomendado)
- [ ] `npm pack --dry-run` muestra solo los archivos correctos
- [ ] Licencia definida en `package.json`
- [ ] Dependencias `peerDependencies` si aplica (vue, @nexabase/sdk)

---

## peerDependencies

Actualmente Vue 3.5+ y @nexabase/sdk son dependencias directas (empaquetadas en el bundle). Si se desea externalizarlas para evitar duplicación en el proyecto consumidor, mover a `peerDependencies`:

```json
{
  "peerDependencies": {
    "vue": "^3.5.0",
    "@nexabase/sdk": "^2.12.0"
  },
  "peerDependenciesMeta": {
    "@nexabase/sdk": {
      "optional": true
    }
  }
}
```

---

## Flujo de CI/CD recomendado (GitHub Actions)

```yaml
# .github/workflows/publish.yml
name: Publish to npm
on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: https://registry.npmjs.org
      - run: npm ci
      - run: pnpm run build
      - run: ppnpm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
```

---

## Ejemplo completo de uso en proyecto externo

### Vue 3 + Vite

```bash
pnpm install nexabase-report @nexabase/sdk
```

```vue
<script setup>
import { ref, onMounted } from 'vue';
import { registerNexaReport } from 'nexabase-report';
import 'nexabase-report/style.css';

registerNexaReport();

const reportDef = ref(null);
const data = ref([]);

onMounted(async () => {
  // Cargar desde archivo JSON local
  const res = await fetch('/examples/report-productos.json');
  reportDef.value = await res.json();

  // Datos reales desde API
  const dataRes = await fetch('/api/productos');
  data.value = await dataRes.json();
});
</script>

<template>
  <nexa-viewer :definition="reportDef" :data="data" minimal />
</template>
```

### React

```jsx
import { useEffect, useRef } from 'react';
import { registerNexaReport } from 'nexabase-report';
import 'nexabase-report/style.css';

registerNexaReport();

function Reporte() {
  const viewerRef = useRef(null);

  useEffect(() => {
    fetch('/api/reports/123')
      .then(r => r.json())
      .then(report => {
        viewerRef.current.definition = report.definition;
        viewerRef.current.data = report.data;
      });
  }, []);

  return <nexa-viewer ref={viewerRef} />;
}
```

### HTML puro

```html
<!DOCTYPE html>
<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/nexabase-report/dist/nexabase-report.umd.js"></script>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/nexabase-report/dist/style.css">
</head>
<body>
  <nexa-viewer id="miReporte" minimal></nexa-viewer>

  <script>
    NexaReport.registerNexaReport();

    const viewer = document.getElementById('miReporte');

    fetch('/api/reports/123')
      .then(r => r.json())
      .then(report => {
        viewer.definition = report.definition;
        viewer.data = report.data;
      });
  </script>
</body>
</html>
```
