La forma más sencilla de crear su primer paquete NPM

Esta guía lo guiará a través del proceso más sencillo de creación y lanzamiento de su paquete NPM, de principio a fin, utilizando un micropaquete .

Hablemos un poco sobre el microbundle . Lo encuentro particularmente efectivo para bibliotecas simples porque no tienes que preocuparte por la configuración, lo que te permite concentrarte en desarrollar tu paquete.

Aquí hay una breve lista de sus características:

• Configuraciones integradas; todo lo que tienes que hacer es agregar un campo de "exportaciones" en package.json
• Compatibilidad con TypeScript lista para usar sin tsconfig.json
• Múltiples formatos de salida (CJS, UMD y ESM)
• Compresión Terser incorporada

Básicamente, microbundle se construye sobre rollup.js . Si tiene que crear bibliotecas más complejas de las que mencionaré en este artículo, podría considerar utilizar una configuración rollup.js pura.

Inicializando su paquete

Como ejemplo, creemos una biblioteca simple para sumar dos números, que exportará solo una función sum .

1. Cree una carpeta para el proyecto y ejecute npm init con los valores predeterminados para generar package.json

   
   

2. Crear index.ts en la carpeta src

    // src/index.ts export function sum(a: number, b: number) { return a + b; }

3. Instalar microbundle

   npm i -D microbundle

   
   

4. Actualice package.json con los siguientes valores:

    // package.json ... "type": "module", "source": "src/index.ts", // your source code "exports": { "types": "./dist/index.d.ts", // TypeScript declaration file "require": "./dist/index.cjs", // CommonJS entry point "default": "./dist/index.esm.js" // ES Module entry point }, "main": "./dist/index.cjs", // where to generate the CommonJS bundle "module": "./dist/index.esm.js", // where to generate the ESM bundle "unpkg": "./dist/index.umd.js", // where to generate the UMD bundle "types": "./dist/index.d.ts", // TypeScript declaration file for the package "scripts": { "build": "microbundle", // compiles "source" to "main", "module", "unpkg" "dev": "microbundle watch" // re-build when source files change } ...

5. Ejecute el script de compilación

   npm run build

   
   

   La salida debe contener exactamente los archivos que declaramos en package.json

   

Y listo, hicimos nuestro primer paquete. Echemos un vistazo a escenarios más complejos.

Agregar React a su biblioteca

Si desea llevar React a su biblioteca, aún puede usarlo microbundle , pero ahora su comando de compilación debería verse así:

 microbundle --jsx React.createElement --jsxFragment React.Fragment --jsxImportSource react --globals react/jsx-runtime=jsx

Agregue el comando a package.json en el script build para mayor comodidad en el futuro:

 // package.json ... "scripts": { "build": "microbundle --jsx React.createElement --jsxFragment React.Fragment --jsxImportSource react --globals react/jsx-runtime=jsx" } ...

Uso de Storybook para componentes de interfaz de usuario

Mientras crea una biblioteca de interfaz de usuario, es posible que necesite un espacio aislado donde pueda desarrollar, visualizar componentes y proporcionar componentes de demostración para su documentación.

Aquí viene el libro de cuentos . Es un entorno limitado con su propia interfaz y paquete convenientes, donde puede describir fácilmente varios estados de sus componentes. Cada captura del estado de su componente se denomina "historia".

Esta imagen, tomada de su documentación, muestra cómo se ve:

Instalar Storybook es bastante sencillo; simplemente ejecuta el comando dentro de tu biblioteca:

 npx storybook@latest init

Este comando instalará todas las dependencias necesarias para Storybook, agregará scripts para ejecutar y compilará Storybook en package.json , creará una carpeta .storybook con la configuración predeterminada y agregará algunos ejemplos de historias a la carpeta src/stories .

Integrando el estilo en su biblioteca

Puede agregar estilo de dos maneras: archivo CSS o CSS-in-JS. El archivo CSS permite una fácil personalización pero requiere una inclusión por separado, mientras que CSS-in-JS simplifica el estilo pero aumenta el tamaño del paquete.

• archivo css

  Cree un archivo CSS en el directorio src e impórtelo al archivo del componente raíz de reacción:

   // src/index.tsx import './styles.css'; export const MySuperComponent = () => { return ( <h1 className="title">Hi there!</h1> ) };

  
  

  Entonces, ejecutemos el comando de compilación nuevamente.

   npm run build

  
  

  Y su archivo styles.css importado se creará en la carpeta dist :

  

  ¡Excelente! Hemos obtenido un archivo CSS con los estilos necesarios. Sin embargo, esta solución presenta un ligero inconveniente. El archivo CSS debe agregarse por separado después de instalar el paquete.

  
  

  Por lo tanto, los usuarios de su biblioteca necesitarán usar un cargador CSS (por ejemplo, un cargador CSS para el paquete web) para manejar su archivo CSS, y su uso se verá así:

   import { MySuperComponent } from 'my-super-library'; import 'my-super-library/dist/styles.css'; export const App = () => { return ( <MySuperComponent /> ); }

  
  

• CSS en JS

  Puede utilizar bibliotecas como componentes con estilo para este propósito. Y se verá así:

   import styled from 'styled-components'; const Title = styled.h1` font-size: 30px; font-weight: bold; `; export const MySuperComponent = () => { return ( <Title>Hi there!</Title> ) };

  Con esta solución, los usuarios no necesitarán importar un archivo CSS ni agregar un cargador especial para su proyecto. Después de instalar la biblioteca, el componente tendrá su propio estilo. Sin embargo, esto aumentará el tamaño del paquete y hará que sea más difícil para los usuarios personalizar elementos utilizando selectores CSS.

Elige la opción que más te convenga. Prefiero usar el archivo CSS porque permite a los usuarios personalizar cualquier elemento con selectores CSS, no afecta el tamaño del paquete y funciona más rápido.

Desarrollo de un archivo README.md detallado

Un archivo README.md proporciona información sobre su biblioteca, cómo instalarla, su uso básico y las características que tiene. Este suele ser el primer archivo que los desarrolladores leen cuando encuentran su repositorio o paquete NPM, por lo que debe ser conciso e informativo.

Me gusta crear una estructura en el siguiente orden:

1. Título
2. Descripción del paquete súper breve
3. Insignias de estadísticas elegantes ( shields.io )
4. Si su biblioteca es un componente de la interfaz de usuario, incluya una captura de pantalla o proporcione un enlace de demostración en CodeSandbox
5. Lista de características
6. Guía de instalación
7. Fragmentos de código con uso.
8. Opciones y accesorios que su biblioteca acepta para configuración

Puede consultar ejemplos de archivos README.md de mis paquetes, como dot-path-value y react-nested-dropdown , para inspirarse.

Navegando por la gestión de dependencias

Esta es una parte importante porque si lo hace mal, los usuarios pueden enfrentar conflictos de versión u otros problemas y tendrán que eliminar su biblioteca. Entonces, echemos un vistazo a las principales diferencias entre los tipos de dependencia.

• Las "devDependencies" son solo para desarrollo y no se incluirán en su paquete. Por ejemplo, si tiene instalado el paquete microbundle , que los usuarios no necesitan usar, manténgalo en devDependencies y no aparecerá en el paquete.

• Las "dependencias" se instalarán junto con el paquete. Incluya las dependencias que su paquete necesita para funcionar en los proyectos de los usuarios. Tenga en cuenta que es posible que algunas dependencias, como "react", ya estén instaladas en el proyecto del usuario. Tener una "reacción" duplicada en su paquete podría aumentar el tamaño del paquete. Aquí es donde las "peerDependencies" resultan útiles.

• Las “peerDependencies” son dependencias que utiliza su paquete pero que no incluirán en su paquete. Su paquete utilizará la versión de la dependencia que el usuario tiene en su proyecto.

  
  

  Básicamente, debemos especificar una dependencia entre pares si estamos creando una biblioteca para su ecosistema. Por ejemplo, si está creando un componente de React, configure React como una dependencia de pares. Si desarrolla un componente de React con un calendario, agregue React y una biblioteca de cálculo de fechas (por ejemplo, date-fns) como peerDependencies.

  
  

  Si el usuario no tiene la dependencia de pares especificada en su proyecto, el comando npm install mostrará una advertencia, pero no instalará automáticamente la dependencia.

Sólo un pequeño ejemplo de cómo se ve:

 // package.json ... "dependencies": { // libraries which will be installed along with your library "clsx": "^1.2.1" // just library for className combining }, "peerDependencies": { // user should have these packages installed "react": "^16.8.0 || ^17.0.0 || ^18.0.0" // user should have react 16.8+ version }, "devDependencies": { // won't be in user's bundle, these libraries just for your developing needs "@types/react": "^18.2.33", "react": "^18.2.0", // in case if we are using storybook, we need actual react library to render our components there "microbundle": "^0.15.1", }, ...

Usando GitHub para su paquete

Si está publicando un paquete NPM, significa que será accesible públicamente (si tiene una cuenta gratuita). Para recopilar comentarios de los usuarios, puede crear un repositorio de GitHub para su código original. Las personas pueden crear problemas y comunicarse con usted sobre su paquete allí. ¡También puedes describir tus lanzamientos y obtener algunas estrellas!

Ciertamente puedes saltarte este paso, pero es una parte integral de la cultura del desarrollador y puede ser una valiosa contribución al código abierto.

Publicación y mantenimiento del paquete

Antes de poder publicar su paquete, es esencial asegurarse de que su archivo package.json esté configurado correctamente. Aquí hay algunos pasos importantes a seguir:

1. Nombra e intenta describir la funcionalidad principal de tu biblioteca. Por ejemplo:

    "name": "react-color-picker"

   
   

2. Agregue información del repositorio de GitHub (si existe):

    ... "homepage": "https://github.com/{your_repository}", "repository": { "type": "git", "url": "https://github.com/{your_repository}" }, "bugs": { "url": "https://github.com/{your_repository}/issues" }, ...

   
   

3. Configurar los files :

    ... "files": [ "dist", ], ...

   Debe especificar los archivos que se incluirán en node_modules cuando se instale su biblioteca. Normalmente, incluir la carpeta dist es suficiente.

   
   

4. Añadir keywords :

   Las palabras clave son una serie de cadenas que describen su paquete y NPM las utiliza para búsquedas y recomendaciones. Elija palabras relevantes para su paquete que anticipe que las personas utilizarán al realizar búsquedas. Creemos palabras clave para nuestra biblioteca sum :

    ... "keywords": ["typescript", "math", "sum", "numbers", "arithmetic", "calculator", "calculation"] ...

   Es importante especificar sus tecnologías porque los usuarios suelen buscar términos como "biblioteca mecanografiada para matemáticas" o "selector de calendario de reacción".

   
   

5. Cree una cuenta NPM si aún no lo ha hecho y ejecute npm login en su terminal; Siga las instrucciones para autenticar su cuenta. De forma predeterminada, la versión de su paquete será 1.0.0 ; puedes comprobarlo en el archivo package.json . Recomiendo cambiarlo a 0.0.1 .

   
   

6. Ejecute npm publish y ¡listo! Para actualizar la versión en el futuro, use el comando npm version patch para incrementar la versión y luego publique el paquete actualizado con npm publish .

Conclusión

Como puedes ver, ¡crear tu propia biblioteca es muy fácil! Básicamente, esto es todo lo que necesita para crear y mantener el paquete. Si tiene dificultades para limitar su biblioteca con microbundle , le recomiendo usar rollup.js con una configuración más específica.

Crear paquetes NPM y contribuir al código abierto es una experiencia valiosa y gratificante para desarrolladores de todos los niveles. Le permite compartir su código con la comunidad, adquirir mucha experiencia y crear un portafolio de su trabajo.