flurix-developer/wiki/03-npm-package-guide.md

Generador de documentación desde comentarios en JS/TS/PY usando Python

# Guía para Crear y Publicar Paquetes NPM

## Índice
1. [Preparación del Entorno](#preparación-del-entorno)
2. [Estructura del Proyecto](#estructura-del-proyecto)
3. [Configuración del Paquete](#configuración-del-paquete)
4. [Desarrollo](#desarrollo)
5. [Pruebas](#pruebas)
6. [Publicación](#publicación)
7. [Mantenimiento](#mantenimiento)

## Preparación del Entorno

### Requisitos Previos
- Node.js instalado (versión LTS recomendada)
- Cuenta en npm (registro en [npmjs.com](https://www.npmjs.com))
- Git instalado
- Editor de código (VS Code recomendado)

### Configuración Inicial
```bash
# Verificar versiones instaladas
node --version
npm --version

# Configurar npm (si es primera vez)
npm login
npm config set init-author-name "Tu Nombre"
npm config set init-author-email "tu@email.com"
npm config set init-license "MIT"
```

## Estructura del Proyecto

### Estructura Básica Recomendada
```
mi-paquete/
├── src/                    # Código fuente
│   ├── index.js           # Punto de entrada principal
│   └── utils/             # Utilidades y helpers
├── tests/                 # Pruebas unitarias
├── examples/              # Ejemplos de uso
├── .gitignore            # Archivos ignorados por git
├── .npmignore            # Archivos ignorados por npm
├── package.json          # Configuración del paquete
├── README.md             # Documentación principal
└── LICENSE               # Licencia del proyecto
```

### Archivos de Configuración

#### .gitignore
```gitignore
node_modules/
.DS_Store
coverage/
.env
*.log
```

#### .npmignore
```gitignore
tests/
examples/
.git/
.github/
coverage/
.env
*.log
```

## Configuración del Paquete

### Inicialización
```bash
# Crear directorio del proyecto
mkdir mi-paquete
cd mi-paquete

# Inicializar proyecto npm
npm init
```

### package.json Básico
```json
{
  "name": "mi-paquete",
  "version": "1.0.0",
  "description": "Descripción de mi paquete",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsc",
    "test": "jest",
    "lint": "eslint src/**/*.ts",
    "prepare": "npm run build"
  },
  "keywords": ["keyword1", "keyword2"],
  "author": "Tu Nombre",
  "license": "MIT",
  "devDependencies": {
    "@types/node": "^16.0.0",
    "typescript": "^4.5.0",
    "jest": "^27.0.0",
    "@types/jest": "^27.0.0",
    "ts-jest": "^27.0.0"
  }
}
```

## Desarrollo

### Configuración de TypeScript
```json
// tsconfig.json
{
  "compilerOptions": {
    "target": "es2018",
    "module": "commonjs",
    "declaration": true,
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "tests"]
}
```

### Estructura de Código
```typescript
// src/index.ts
export interface Config {
  // Define la interfaz de configuración
}

export class MiClase {
  constructor(private config: Config) {}

  public metodo(): void {
    // Implementación
  }
}
```

## Pruebas

### Configuración de Jest
```javascript
// jest.config.js
module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  testMatch: ['**/tests/**/*.test.ts'],
  collectCoverage: true,
  coverageDirectory: 'coverage'
};
```

### Ejemplo de Prueba
```typescript
// tests/index.test.ts
import { MiClase } from '../src';

describe('MiClase', () => {
  it('debería funcionar correctamente', () => {
    const instancia = new MiClase({});
    expect(instancia.metodo()).toBeDefined();
  });
});
```

### Ejecutar Pruebas
```bash
# Ejecutar pruebas
npm test

# Ejecutar pruebas con cobertura
npm test -- --coverage
```

## Publicación

### Preparación para Publicación
1. Actualizar versión en package.json
2. Asegurar que todas las pruebas pasan
3. Verificar que la documentación está actualizada
4. Revisar que .npmignore está configurado correctamente

### Comandos de Publicación
```bash
# Verificar estado del paquete
npm pack

# Publicar versión
npm publish

# Publicar versión beta
npm publish --tag beta
```

### Control de Versiones
```bash
# Actualizar versión patch (1.0.0 -> 1.0.1)
npm version patch

# Actualizar versión minor (1.0.0 -> 1.1.0)
npm version minor

# Actualizar versión major (1.0.0 -> 2.0.0)
npm version major
```

## Mantenimiento

### Buenas Prácticas
1. Mantener documentación actualizada
2. Responder issues y pull requests
3. Mantener dependencias actualizadas
4. Seguir semver para versiones

### Actualización de Dependencias
```bash
# Verificar dependencias desactualizadas
npm outdated

# Actualizar dependencias
npm update

# Actualizar a última versión
npm install package@latest
```

### Monitoreo
```bash
# Ver estadísticas del paquete
npm stats

# Ver dependencias
npm ls
```

## Diagrama de Flujo de Publicación

```mermaid
graph TD
    A[Desarrollo] --> B[Pruebas]
    B --> C{¿Pasan las pruebas?}
    C -->|No| A
    C -->|Sí| D[Actualizar Versión]
    D --> E[Publicar]
    E --> F[Verificar Publicación]
    F --> G[Monitorear]
```

## Recursos Adicionales

- [Documentación oficial de npm](https://docs.npmjs.com/)
- [Guía de TypeScript](https://www.typescriptlang.org/docs/)
- [Documentación de Jest](https://jestjs.io/docs/getting-started)
- [Semantic Versioning](https://semver.org/)