Este artículo se centra en resolver dos tareas fundamentales para hacer que un SDK basado en TypeScript sea usable, compartible y profesional: empaquetar el código para distribución y generar documentación API de forma automatizada. Utilizaremos Rollup para el empaquetado y TypeDoc para la documentación.

Configuración de empaquetado con Rollup

Rollup es una herramienta de empaquetado de módulos ideal para bibliotecas JavaScript/TypeScript, ya que produce paquetes limpios y eficientes con soporte nativo para tree shaking.

El siguiente archivo rollup.config.mjs define la configuración del empaquetado:

import { nodeResolve } from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import typescript from '@rollup/plugin-typescript';
import peerDepsExternal from 'rollup-plugin-peer-deps-external';
import copy from 'rollup-plugin-copy';
import { readFileSync } from 'fs';

const pkg = JSON.parse(readFileSync('./package.json', 'utf8'));
const libName = pkg.name;

export default {
  input: 'src/index.ts',
  output: [
    { file: `dist/${libName}.esm.js`, format: 'esm', sourcemap: true },
    { file: `dist/${libName}.cjs.js`, format: 'cjs', sourcemap: true },
    { file: `dist/${libName}.umd.js`, format: 'umd', name: 'GeoEnhance', sourcemap: true },
  ],
  plugins: [
    peerDepsExternal(),
    nodeResolve(),
    commonjs(),
    typescript({ tsconfig: './tsconfig.json' }),
    copy({ targets: [{ src: 'src/assets/**/*', dest: 'dist/assets' }] })
  ],
  external: (id) => id.startsWith('cesium')
};

Análisis de los formatos de salida

• ESM (.esm.js): Módulo estándar para entornos modernos (Vite, Rollup, Webpack 5+). Permite import.
• CJS (.cjs.js): Formado CommonJS para Node.js y bundlers más antiguos. Se usa con require.
• UMD (.umd.js): Compatible con el navegador mediante etiquetas <script>. Expone la biblioteca como una variable global.

Decsripción de los plugins

• peerDepsExternal(): Marca automáticamente las dependencias peerDependencies (como cesium) como externas para evitar incluirlas en el paquete.
• nodeResolve(): Permite a Rollup resolver módulos desde node_modules.
• commonjs(): Convierte módulos CommonJS a ES6 para su procesamiento.
• typescript(): Compila TypeScript a JavaScript y genera los archivos de declaración de tipos (.d.ts).
• copy(): Copia recursos estáticos necesarios al directorio de distribución.

La función external asegura que cesium no sea empaquetado, ya que es una dependencia pesada que debe ser proporcionada por el consumidor del SDK.

Generación automática de documentación API con TypeDoc

TypeDoc extrae la información de tipos y comentarios de JSDoc en tu código TypeScript para generar una documentación interactiva.

Configuración de TypeDoc (typedoc.json)

{
  "entryPoints": ["./src/index.ts"],
  "out": "docs",
  "name": "GeoEnhance SDK API Reference",
  "includeVersion": true,
  "plugin": ["typedoc-material-theme"],
  "excludePrivate": true,
  "excludeProtected": true,
  "readme": "README.md",
  "categorizeByGroup": true,
  "sort": ["source-order"],
  "exclude": ["**/node_modules/**", "**/examples/**"],
  "tsconfig": "./tsconfig.json"
}

Script de generación de documentación

Un script personalizado (scripts/gen-docs.js) orquesta la generación:

import { execSync } from 'child_process';
import { writeFileSync, mkdirSync, existsSync } from 'fs';
import path from 'path';

// Ejecutar TypeDoc para generar la documentación
console.log('Generando documentación API...');
execSync('npx typedoc', { stdio: 'inherit' });

// Crear página de redirección en el directorio raíz de docs
const docsRoot = path.resolve('docs');
const indexPath = path.join(docsRoot, 'index.html');

if (!existsSync(docsRoot)) {
  mkdirSync(docsRoot, { recursive: true });
}

const redirectHtml = `


  <meta content="0; url=./api/" http-equiv="refresh"></meta>
  <title>Redireccionando...</title>


  <p>Redireccionando a la <a href="./api/">documentación de la API</a>...</p>

`;

writeFileSync(indexPath, redirectHtml);
console.log('¡Documentación generada en ./docs!');

Ejecución

Añade el script a package.json:

{
  "scripts": {
    "build": "rollup -c rollup.config.mjs",
    "docs": "node scripts/gen-docs.js"
  }
}

Ejecuta npm run docs para generar la documentación. El resultado se encuentra en el directorio docs, con un archivo index.html principal que redirige a la documentación completa de la API.