DEV Community: Jonathan Delgado

Simplifica la publicación en npm con este flujo de trabajo

Jonathan Delgado — Fri, 11 Oct 2024 16:00:19 +0000

Este es el stack perfecto para publicar tus librerías de JavaScript en npm sin esfuerzo. Esta guía quiere presentar un flujo de despliegue para pasar de código alojado en github a npm. Con el fin de evitar la mayoría de los errores humanos al mantener un flujo de trabajo claro y simple.

Contenido:

Por que npm
Paso 1: Crear nuestro token para publicar
- Opción 1: Crear token desde la WEB
- Opción 2: Crear token desde la terminal
Paso 2: Preparación del código para publicación
Paso 3: Empaquetar el código
- Puntos de entrada (Propiedad main)
- Múltiples puntos de entrada (Propiedad exports)
Paso 4 (Opcional): Probar código
Paso 5: Automatizar publicación
- Secretos
- Job release-please
- Job delivery-npm
Conclusion

Por que npm

(www.npmjs.com) este es un registry que usan por defecto node.js y bun para descargar dependencias de los proyectos cuando usamos npm add o bun add. Este registry es gratuito y si queremos compartir código entre la comunidad o nuestros proyectos es buena idea alojar este código aquí. Si bien permite guardar cualquier tipo de archivo, lo normal es guardar archivos escritos en JavaScript.

Además, es importante mencionar que este sitio tiene una serie de reglas al momento de publicar código:

Cada paquete debe tener al menos un archivo package.json con una propiedad name, version y description. También es buena idea agregar una propiedad license
Puede ser publicado un paquete privado o público. Sin embargo, de ser privado puede tener tiene un costo que puedes revisar aquí (npmjs.com/products)[https://www.npmjs.com/products].
Toda actualización de un paquete ya publicado debe tener una versión superior a la anterior.
No se pueden reemplazar paquetes ya publicados a no ser que tú seas el dueño de ese paquete
Todas las versiones deben seguir la convención semver

Debido a estas reglas que impiden publicar versiones antiguas, es importante considerar el uso de generadores de versiones, entre los que podemos encontrar sematic-release o release-please. Estas herramientas nos ofrecerán un número de versión que podremos usar en nuestro proyecto más adelante y 100% basado en el historial de commits.

Paso 1: Crear nuestro token para publicar

El primer paso antes de publicar nuestro paquete será el obtener un token para publicar paquetes en npm y para esto podemos optar por 2 caminos:

Opción 1: Crear token desde la WEB

Prefiera este método dentro de lo posible.

Vamos a ir al sitio https://www.npmjs.com/settings/jondotsoy/tokens

Opción 2: Crear token desde la terminal

Ejecuta el comando npm npm token create

Paso 2: Preparación del código para publicación

Bien, ya tenemos el token y ahora debemos pensar en el código que vamos a publicar.

Aquí te dejo unos consejos de seguridad:

Si requieres configuraciones puedes hacer que tu código lo lea desde las variables de ambientes (process.env)

No permitas cargar código desde tu librería sin un origen claro.

Debemos pensar bien en quién será el usuario librería o en otras palabras dónde será ejecutado el código, este puede ser un navegador, un entorno con NodeJS, BunJS o Deno. Si no tenemos claro el entorno podemos siempre asumir que será un entorno que ejecute soporte JavaScript TC39.

Lo más importante es tener siempre disponible el código JS antes de ser publicado.

Paso 3: Empaquetar el código

Siempre es buena idea probar el código antes de publicar y para esto npm nos ofrece el comando npm pack este nos ayudará a crear un paquete comprimido.

Cuando lo ejecutemos veremos por un lado el resultado del empaquetamiento y un archivo con extensión .tgz, este archivo nos servirá para probarlos más tarde.

El comando npm pack tiene un ciclo de vida que podemos aprovechar para compilar o preparar cualquier archivo si se necesita.

El comando npm pack ejecuta en orden los siguientes scripts prepack, prepare y postpack.

{
    ...
    "scripts": {
        "prepack": "Es ejecutado previo al empaquetamiento",
        "prepare": "Se ejecuta después de prepack y antes de empaquetar",
        "postpack": "Se ejecuta después de empaquetamiento (puede ser útil para limpiar archivos)"
    }
    ...
}

Puntos de entrada (Propiedad `main`)

Cuando importemos nuestro modulo ya sea con require o import el modulo necesita un script principal, esto lo definimos con la propiedad main del package.json. Con esta propiedad vamos a declarar que archivo debe cargar cuando el modulo sea importando.

{
    ...
    "main": "index.js",
    ...
}

require("sample-pack"); // cargará el archivo `node_modules/sample-pack/index.js`

Puedes revisar más a detalle esta propiedad en la documentación de npm https://docs.npmjs.com/cli/v10/configuring-npm/package-json#main

Múltiples puntos de entrada (Propiedad `exports`)

Adicionalmente a la script principal podemos definir sub rutas a nuestro modulo con la propiedad exports del package.json. La idea de exportar varios scripts es útil si queremos exportar varias utilidades y a su vez disminuir el tamaño del proyecto del cliente final.

{
    ...
    "exports": {
        ".": "./index.js",
        "./feature": "./lib/feature.js"
    }
    ...
}

Puedes revisar más a detalle esta propiedad en la documentación de npm https://docs.npmjs.com/cli/v10/configuring-npm/package-json#exports

Paso 4 (Opcional): Probar código

Yo realmente te recomiendo probar el paquete antes de seguir, es importante sobre todo para validar que los motores como nodejs puedan leer el paquete bien y si tienes definiciones de typescript también funcionen correctamente. Además que no es tan complejo, solo requerimos de un proyecto limpio o con el entorno que necesitamos.

El siguiente script crea una carpeta con un proyecto en bun limpio:

cd $TMPDIR
mkdir my-project
cd my-project

bun init . -y
# Si prefieres npm puedes usar `npm init -y`

Ahora necesitamos identificar el archivo tgz del paso 3 e instalar con el comando bun add .../sample-pack-1.0.0.tgz (En mi caso uso bun para la prueba pero se puede usar el mismo comando con npm npm add .../sample-pack-1.0.0.tgz).

Ahora solo nos hace falta ejecutar nuestras pruebas. Este tipo de pruebas las podemos llamar de integración y tras ejecutar el script index.ts podemos ver en la salida el mensaje hello world que es ejecutado en el módulo y ver el mensaje the variable is: ok que ejecutamos en el script que importa el módulo.

Paso 5: Automatizar publicación

Ahora que tenemos lista nuestra librería ya podemos publicar en npm, pero para esto lo automatizaremos y para esto vamos a escribir un workflow que nos permita hacer 2 tareas:

automatiza el versionamiento de la librería. Recordemos que no podemos publicar una librería en npm sin tener una declarada y debe ser superior a la publicada anteriormente
automatizar la publicación de la librería a npm

El script a continuación es una plantilla que podemos editar a nuestro gusto y esta plantilla tiene dos tareas para crear la versión y publicar los cambios en npm cuando estos estén listos.

name: Deploy Release

on:
  push:
    branches:
      - main

# Required by release-please to make a PR
permissions:
  contents: write
  pull-requests: write

jobs:
  release-please:
    runs-on: ubuntu-latest
    outputs:
      release_created: ${{ steps.release-please.outputs.release_created }}
    steps:
      - name: release
        id: release-please
        uses: googleapis/release-please-action@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

  # publish on npm
  delivery-npm:
    runs-on: ubuntu-latest
    if: needs.release-please.outputs.release_created
    needs:
      - release-please
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - uses: actions/setup-node@v4
        with:
          registry-url: "https://registry.npmjs.org"
      - run: bun install
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Expliquemos más a detalles cada paso de la plantilla:

Secretos

Como puedes ver en este archivo se usa el secreto NPM_TOKEN, debemos configurar aquí el token que obtuvimos en el paso 1 podemos crear este secreto ya sea desde la consola de github o con el comando gh secret set NPM_TOKEN, usemos el que nos sea más simple.

Job `release-please`

La tarea release-please usa la herramienta release-please para observar constantemente la rama main y según los commits proponer una nueva versión en un PR.

Durante esta etapa además podemos automatizar algunos procesos como generar algún otro archivo con la versión del package.json. por si nuestro proyecto lo requiere.

ℹ️ Si presentan algún problema en esta etapa sería bueno configurar tu proyecto de manera local con el comando release-please bootstrap

En la plantilla también podemos ver la variable de salida release_created es importante en la siguiente etapa, ya que con ella podemos decidir si publicar o no nuestra variable.

Job `delivery-npm`

Este job tiene como objetivo el publicar el código de nuestra librería a npm pero antes valida si la variable needs.release-please.outputs.release_created es true. Esto es porque esperamos a que termine de actualizar la versión en el paso anterior de otro modo tendríamos un error constantemente por parte de npm.

Un error común en este paso, es tener un token obsoleto; Podemos resolverlo si repetimos el Paso 1 y actualizar en github el secreto.

Conclusion

En definitiva, publicar tus librerías JavaScript en npm no tiene por qué ser una tarea tediosa. Siguiendo este flujo de trabajo, desde la generación de un token hasta la automatización del versionado y la publicación, podrás compartir tu código con la comunidad de manera eficiente y segura. Recuerda que cada paso, desde la preparación del código hasta las pruebas, es crucial para garantizar la calidad y la seguridad de tu librería. ¡Anímate a contribuir al ecosistema npm y a facilitar la vida de otros desarrolladores con tus creaciones!

Como conectarse a Google Cloud Shell desde Visual Studio Code

Jonathan Delgado — Wed, 02 Oct 2024 16:32:30 +0000

GCP es la cloud de Google y con esta tenemos una herramienta muy poderosa la cual es la cloud-shell esta herramienta es una maquina virtual que podemos acceder directamente desde la consola de GCP.

Sin embargo, dependiendo de la conexión o configuración, puedes experimentar problemas al usar esta herramienta desde la web.

Si normalmente te pasa este problema una vez no hay problema solo ejecuta nuevamente la consola web y ya esta, pero si se repite podemos conectarnos por SSH usando visual estudio code. La siguiente guía te explico en pocos pasos como hacerlo rápidamente.

1. Obtener configuraciones SSH

Para este paso debes estar logeado desde tu consola. Leer el siguiente guía (gcloud auth login)[https://cloud.google.com/sdk/gcloud/reference/auth/login]

En tu terminal ejecuta el siguiente comando gcloud cloud-shell ssh --dry-run este comando nos entregara toda la linea de comando SSH para conectarnos desde la terminal, estas configuraciones los usaremos para conectarnos desde nuestro editor.

de esta linea de comando para conectarse a SSH vamos a tener que recuperar el Host, Usuario, archivo de identificación y el Puerto.

De la salida mostrada podemos recuperar los siguientes valores

Host: 34.139.169.146
Usuario: student_00_68e0901ed4d8
Archivo de identificación: /Users/jon /.ssh/google_compute_engine
Puerto: 6000

2. Configurar perfil SSH

Ya con los valores recuperados, vamos a configurar nuestro archivo ~/ssh/config este archivo se encarga de configurar todos nuestras configuraciones para conectarnos a nuestra terminal cloud-shell por SSH.

Este archivo debe verse algo similar a:

3. Conectarnos desde Visual Studio Code

Por último, abre la terminal de comandos en Visual Studio Code y escribe connect to host.

Si esta opción no aparece puedes intentar instalar la extension Remote - SSH

Luego seleccionar el host de nuestra cloud-shell.

Y Listo 🚀

Ya estaríamos conectados a la cloud-shell sin problemas

Conclusion

Si necesitamos conectarnos a cloud-shell desde la consola web, adelante es muy potente y una muy buena opción para trabajar con los recursos de GCP rápidamente, sin embargo ya sea por comodidad por por latencia en la consola, podemos acceder a ella mediante la terminal SSH. Esta opción es ideal si estas quieres mantener un entorno agradable, mover archivos rápidamente entre tu equipo y Cloud Shell o simplemente quieres conectarte a resolver algún lab sin guardar muchos archivos en tu equipo local.

Como conectarse a Google Cloud Shell desde Visual Studio Code

Jonathan Delgado — Wed, 02 Oct 2024 16:31:31 +0000

Sin embargo, dependiendo de la conexión o configuración, puedes experimentar problemas al usar esta herramienta desde la web.

1. Obtener configuraciones SSH

Para este paso debes estar logeado desde tu consola. Leer el siguiente guía (gcloud auth login)[https://cloud.google.com/sdk/gcloud/reference/auth/login]

de esta linea de comando para conectarse a SSH vamos a tener que recuperar el Host, Usuario, archivo de identificación y el Puerto.

De la salida mostrada podemos recuperar los siguientes valores

Host: 34.139.169.146
Usuario: student_00_68e0901ed4d8
Archivo de identificación: /Users/jon /.ssh/google_compute_engine
Puerto: 6000

2. Configurar perfil SSH

Este archivo debe verse algo similar a:

3. Conectarnos desde Visual Studio Code

Por último, abre la terminal de comandos en Visual Studio Code y escribe connect to host.

Si esta opción no aparece puedes intentar instalar la extension Remote - SSH

Luego seleccionar el host de nuestra cloud-shell.

Y Listo 🚀

Ya estaríamos conectados a la cloud-shell sin problemas

Conclusion

Leer archivos ICS en Javascript con iCalendar.js

Jonathan Delgado — Tue, 28 Mar 2023 17:36:34 +0000

Si eres un desarrollador web, probablemente hayas trabajado con archivos ICS antes. Los archivos ICS son un formato estándar para intercambiar información de calendario entre diferentes aplicaciones. Puede ser bastante difícil trabajar con archivos ICS directamente, pero no te preocupes, ¡iCalendar.js está aquí para ayudarte!

iCalendar.js es una biblioteca de Javascript que facilita la lectura y escritura de archivos ICS. Con iCalendar.js, puedes analizar y manipular archivos ICS en tu proyecto de Javascript con facilidad. Y lo mejor de todo es que se puede descargar desde npm.im/icalendar.js con un simple comando npm add icalendar.js.

Aquí hay un ejemplo de cómo usar iCalendar.js para leer un archivo ICS:

import { ICalendar } from "icalendar.js";

const location = new URL("sample.ics", import.meta.url);
const payload = await readFile(location);
const icalendar = ICalendar.from(payload);

En este ejemplo, estamos importando la clase ICalendar de iCalendar.js. Luego, estamos leyendo un archivo ICS con el nombre "sample.ics" y almacenando su contenido en la variable payload. Finalmente, usamos el método from de ICalendar para analizar el contenido del archivo y crear un objeto ICalendar.

¡Y eso es todo! Ahora, puedes manipular los datos del calendario en el objeto ICalendar como lo desees.

En resumen, iCalendar.js es una herramienta invaluable para trabajar con archivos ICS en Javascript. Si estás trabajando en un proyecto que involucra archivos de calendario, no dudes en darle una oportunidad a iCalendar.js. Descárgalo hoy mismo y comienza a trabajar con archivos ICS de manera más fácil y eficiente.

DEV Community: Jonathan Delgado

Simplifica la publicación en npm con este flujo de trabajo

Por que npm

Paso 1: Crear nuestro token para publicar

Opción 1: Crear token desde la WEB

Opción 2: Crear token desde la terminal

Paso 2: Preparación del código para publicación

Paso 3: Empaquetar el código

Puntos de entrada (Propiedad main)

Múltiples puntos de entrada (Propiedad exports)

Paso 4 (Opcional): Probar código

Paso 5: Automatizar publicación

Secretos

Job release-please

Job delivery-npm

Conclusion

Como conectarse a Google Cloud Shell desde Visual Studio Code

1. Obtener configuraciones SSH

2. Configurar perfil SSH

3. Conectarnos desde Visual Studio Code

Conclusion

Como conectarse a Google Cloud Shell desde Visual Studio Code

1. Obtener configuraciones SSH

2. Configurar perfil SSH

3. Conectarnos desde Visual Studio Code

Conclusion

Leer archivos ICS en Javascript con iCalendar.js

Puntos de entrada (Propiedad `main`)

Múltiples puntos de entrada (Propiedad `exports`)

Job `release-please`

Job `delivery-npm`