@randstad-uca/design-system

Publicación del Design System en NPM (ESM)

Esta guía explica paso a paso cómo compilar y publicar tu Design System hecho con Lit + Web Components + TypeScript en NPM, usando el formato ESM (ECMAScript Modules).

🔧 Requisitos previos

• Node.js y npm instalados
• Cuenta en npmjs.com
• Proyecto con componentes hechos en Lit
• Rollup instalado como bundler

📂 Estructura recomendada

my-design-system/
├── src/
│   ├── components/
│   │   └── terms-checkbox.ts
│   └── index.ts         # importa y registra todos los componentes
├── dist/                # carpeta generada al compilar
├── package.json
├── tsconfig.json
└── rollup.config.js

🔹 Paso 1: rollup.config.js (ESM solamente)

import resolve from '@rollup/plugin-node-resolve';
import typescript from '@rollup/plugin-typescript';
import { terser } from 'rollup-plugin-terser';

export default {
  input: 'src/index.ts',
  output: {
    dir: 'dist',
    format: 'esm',
    sourcemap: true,
    preserveModules: true,
    preserveModulesRoot: 'src'
  },
  plugins: [
    resolve(),
    typescript({ tsconfig: './tsconfig.json' }),
    terser()
  ]
};

✅ preserveModules: true mantiene la estructura de carpetas para importar componentes individualmente.

🔹 Paso 2: src/index.ts

import './components/terms-checkbox.ts';
// import otros componentes si es necesario

📆 Paso 3: package.json

{
  "name": "@pablosalut/design-system",
  "version": "1.0.0",
  "description": "Design system de Pablo con Lit y Web Components",
  "type": "module",
  "main": "dist/index.js",
  "module": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "build": "rollup -c"
  },
  "devDependencies": {
    "@rollup/plugin-node-resolve": "^15.0.1",
    "@rollup/plugin-typescript": "^11.0.0",
    "rollup": "^3.0.0",
    "rollup-plugin-terser": "^7.0.2",
    "typescript": "^5.0.0"
  },
  "keywords": ["design-system", "web-components", "lit", "esm"],
  "author": "Pablo Salut",
  "license": "MIT"
}

🚀 Publicación en NPM

🔓 Público

• Iniciar sesión:

npm login

• Compilar el design system:

npm run build

• Publicar el paquete:

npm publish --access public

🔐 Privado

Para publicar un paquete privado:

• Asegurate de tener un scope (por ejemplo, @randstad-uca/tu-paquete).

• Agregá en package.json:

"publishConfig": {
  "access": "restricted"
}

• Publicá con:

npm publish

🔐 Esto hará que tu paquete solo sea accesible para vos (o tu organización, si estás en un team de NPM).

📁 Uso en un proyecto Angular

Instalar:

npm install @pablosalut/design-system

Importar en main.ts:

import '@pablosalut/design-system';

✨ Tips adicionales

• Usá sourcemap: true para poder depurar componentes en proyectos consumidores
• Publicá nuevas versiones con npm version patch/minor/major
• Usá npm link si querés testear el paquete localmente antes de publicar

Si querés agregar también UMD para soporte con <script>, se puede extender esta config. Pero para Angular, ESM es suficiente y recomendado.

npm link en Windows

¿Qué es npm link?

npm link es un comando de npm que crea un enlace simbólico entre un paquete npm local y otro proyecto, permitiendo desarrollar librerías y probarlas sin necesidad de publicarlas en el registry.

¿Cómo usarlo?

1. En la carpeta del paquete que querés linkear:

cd ruta\de\mi-paquete
npm link

Esto crea un enlace global del paquete.

Para que se renueve el enlace luego de hacer cambios

npm unlink @randstad-uca/design-system
npm run build
npm link

Luego en el proyecto angular ejecutamos

rm -rf node_modules/@randstad-uca/design-system package-lock.json
rm -rf .angular/cache
npm link @randstad-uca/design-system

2. En la carpeta del proyecto donde lo vas a usar:

cd ruta\de\mi-proyecto
npm link nombre-del-paquete

Esto crea un enlace local apuntando al paquete linkeado globalmente.

Notas importantes:

• nombre-del-paquete es el que está en el package.json ("name": "nombre-del-paquete").
• Los cambios en tu paquete se reflejan automáticamente en el proyecto que lo usa.
• Si falla el npm link en Windows, abrí la consola como Administrador.

¿Cómo deshacer el link?

En el proyecto:

npm unlink nombre-del-paquete

Opcional: en el paquete:

npm unlink