Creando un paquete para Svelte

Intro

La idea del siguiente post es hacer una versión rápida, practica y sencilla de como crear un paquete (package) para podes descargar vía npm en nuestro proyecto hecho con Svelte.

Hace poco finalice mi primer package y la verdad, aunque la información en la web es bastante, y muy completa, la idea es transmitir mi proceso de forma corta y sencilla, además de que no encontré demasiados post explicando como dejar funcionando el paquete para Svelte.

Recomiendo este post de Sergio Xalambrí, que explica varios pasos mas, con muy buen nivel de detalle (que no es la idea de este post, por ahora).

1. 🛠️ Pre requisitos

Antes que nada es requisito lo siguiente:

  1. Tener cuenta en GitHub
  2. Tener cuenta en npm
  3. Tener Node, npm y GIT instalados en su pc.

Listo esto, podemos seguir.

2. 💡 La idea

Antes de empezar nada, es bueno tener una idea de que se quiere hacer, para no perder tiempo ni pasos haciendo y deshaciendo el paquete. No importa que sea algo básico, piensen en algo que les sirva a ustedes primero, tanto para usar como para practicar, y que les gustaría subir.

Y no piensen si ya esta hecho o no, la mayoría de las cosas posiblemente estén hechas ya, solo búsquenle la vuelta para que tenga un valor agregado suyo.

3. 🏁 Iniciar el paquete

Ya pueden crear una carpeta en su pc, con el nombre del paquete (o el que les guste), y abrir su editor preferido.

En mi caso use Visual Studio Code, que ya tiene una terminal integrada, en caso que utilicen otro, deberán abrir la consola de Node y situarse en el directorio que crearon recién.

Ahora deben ejecutar npm init -y

Esto va a crear un archivo package.json para colocar información sobre el paquete, como nombre, autor, descripción, las dependencias que utiliza, la versión etc.

    {
      "name": "",
      "version": "1.0.0",
      "description": "",
      "main": "index.js",
      "scripts": {
        "test": "echo "Error: no test specified" && exit 1"
      },
      "keywords": [],
      "author": "",
      "license": "ISC"
    }

Pueden ir completando los campos como name, description, keywords, author y license

Ahora podemos instalar la dependencias que usara nuestro paquete. A tener en cuenta que es un código básico, esto quiere decir que instalaremos dependencias básicas.

Ejecuten en su terminal el siguiente comando

npm install -D rollup rollup-plugin-node-resolve rollup-plugin-svelte svelte

Esto instalara las dependencias básicas como devDependencies (-D), ósea que solo se utilizaran para el desarrollo.

El package.json agregara el siguiente campo:

    "devDependencies": {
        "rollup": "^1.28.0",
        "rollup-plugin-node-resolve": "^5.2.0",
        "rollup-plugin-svelte": "^5.1.1",
        "svelte": "^3.16.7"
    }

4. 📦 El paquete

Ahora vamos a crear un carpeta src en la raíz del directorio, y dentro un archivo index.js

Dentro de este archivo vamos a poner el siguiente código:

    import Name from './Name.svelte';

    export default Name;

Donde Name deberá ser el nombre que quieran darle al componente.

Y luego, crearemos también dentro de la carpeta src, un archivo Name.svelte donde Name debera ser el mismo que pusieron en el archivo index.js

Ya dentro del archivo .svelte, queda en ustedes construir el componente de la idea que se les ocurrió, acá solo actúa como una pagina .svelte normal, con los bloques script style y el html.

Pueden importar elementos de Svelte sin problemas.

package.json

Vamos a hacer unos cambios en este archivo, agregando lo siguiente:

    "main": "dist/index.js",
    "module": "dist/index.mjs",
    "svelte": "src/index.js",
    "scripts": {
        "build": "rollup -c",
        "dev": "rollup -c -w"
    },
  • En main vamos a establecer el output después de correr el script build (no hace falta crear el directorio /dist, se creara automáticamente)
  • En module vamos a definir lo mismo pero como salida un archivo .mjs, para que Node distinga entre módulos creados con CommonJS y ES6. Más info aca (en Ingles)
  • En svelte, vamos a definir la ruta de nuestro archivo index.js creado antes.
  • Y después vamos a definir los scripts (si están familiarizados con Svelte, ya los conocerán).

rollup.config.js

Vamos a crear otro archivo, pero esta vez a nivel raíz (donde esta la carpeta src, y el package.json), y vamos a llamarlo rollup.config.js

Si usaron Svelte antes, conocen ya este archivo.

A este archivo vamos a ejecutarlo cuando corramos el script build y vamos a pasarle algunas directivas de que hacer:

    import svelte from 'rollup-plugin-svelte';
    import resolve from 'rollup-plugin-node-resolve';

    const pkg = require('./package.json');

    export default {
        input: 'src/Name.svelte',
        output: [
            { file: pkg.module, 'format': 'es' },
            { file: pkg.main, 'format': 'umd', name: 'Name' }
        ],
        plugins: [
            svelte(),
            resolve()
        ],
    };
  • En las 2 primeras líneas, exportamos 2 de las dependencias que instalamos antes.
  • Después en la constante pkg, traemos el package.json
  • Y después le decimos que el input que ingresara es el archivo .svelte (otra vez cambiando Name por el nombre de su archivo), y que el output será pkg.module, ósea el valor module que pusimos antes en el package.json "module": "dist/index.mjs" y el valor main "main": "dist/index.js", cambiando también el valor 'Name' por el de su componente.
  • Y luego ejecutamos los 2 plugin.

5. 🧪 Testear localmente

Hay una forma para poder testear nuestro paquete de manera local, antes de subirlo a npm.

  1. Creamos una carpeta nueva en nuestra pc e instalamos Svelte.
  2. Desde la terminal, en el directorio de tu paquete, ejecutamos el comando npm link
  3. Desde la carpeta recién creada donde instalamos Svelte en el paso 1, abrimos una nueva terminal situada en ese directorio y ejecutamos el comando npm link /la-ruta/de/tu-paquete

Eso nos va a dejar testear localmente el paquete, y además si hacemos alguna modificación en el, no hace falta hacer un update o install cada vez, se actualiza solo.

6. 🚀 Publicar en npm

Después de todo esto, ya estamos listos para publicar el paquete y dejarlo disponible para instalar vía npm.

Es recomendable haber creado en el directorio raíz un archivo README.md con información acerca de nuestro paquete. Como instalarlo, como utilizarlo, configuraciones, etc.

Este es un buen ejemplo para que puedan usar.

Recuerden que el README.md será el mismo para npm que para el repositorio de GitHub.

Publicar

  1. Ejecutar en la terminal, en el directorio de nuestro paquete, el comando npm adduser, nos va a pedir las credenciales de nuestra cuenta.
  2. Luego ejecutar npm publish y listo!

IMPORTANTE: Cualquier cambio que hagamos en nuestro paquete, antes de poder ejecutar npm publish de nuevo, debemos cambiar la versión en nuestro package.json

    "version": "1.0.0"

7. 🚀 Publicar en GitHub

Para tener el paquete en nuestro repositorio de GitHub, vamos a hacer lo siguiente:

  1. Creamos un archivo .gitignore en el directorio raíz de nuestro paquete que incluya lo siguiente:
        # Directories
        node_modules/
        dist/

Esto evita que se publique la carpeta dist y la carpeta node_modules.

  1. En nuestra cuenta de GitHub, creamos un repositorio con el nombre de nuestro paquete, y ponemos que NO cree un archivo README.md
  2. Ejecutamos los siguientes comandos en nuestra terminal:
       git init
        git remote add origin https://github.com/tu-usuario/el-nombre-del-repositorio.git
        git add .
        git commit -m "First Commit"
        git push -u origin master

Esto va a subir nuestros archivos al repositorio (excepto los que pusimos en el archivo .gitignore)

🧐 Recomendaciones

Es bastante útil, una vez creado nuestro repositorio y publicado nuestro paquete, agregar las siguientes líneas en nuestro archivo package.json:

        "repository": {
            "type": "git",
            "url": "https://github.com/tu-usuario/el-nombre-del-repositorio"
        },
        "homepage": "",
        "bugs": {
            "url": "https://github.com/tu-usuario/el-nombre-del-repositorio/issues"
        }

Esto además añadirá en la pagina npm de nuestro paquete, los campos Homepage y Repository linkeando directamente al sitio de nuestro paquete y al repositorio de GitHub.

📕 Conclución

Se pueden hacer muchas mas cosas antes de publicar el paquete? Si, se pueden, como correr testeos, tener un archivo LICENSE, agregar scripts de prebuild y prepublish en el package.json, etc.

Si, se puede, pero la idea del post es que al menos sepan como arrancar, después queda en cada uno agregarle mas cosas al proceso.

Espero se haya entendido todo, si no pueden comentarlo abajo 😀

Saludos!

Photo by Clark Tibbs on Unsplash

No Comments Yet