Instalación desde npm
Instala Gstock Web Components desde npm con el siguiente comando.
npm install @gstock/webcomponents
El paquete @gstock/webcomponents tiene ámbito privado en el registro npm. Necesitarás el archivo .npmrc para especificar un token y poder resolver la dependencia.
Ahora necesitas hacer que los archivos fuente estén disponibles para la aplicación. Una forma de hacer esto es crear una ruta en tu aplicación, por ejemplo llamada /gstock/webcomponents que sirva archivos estáticos desde node_modules/@gstock/webcomponents.
Una vez creada la ruta, agrega las siguientes etiquetas a tu página. Asegúrate de actualizar href y src para que apunten a la ruta que creaste.
<link rel="stylesheet" href="/gstock/webcomponents/dist/themes/gstock.css" />
<script type="module" src="/gstock/webcomponents/dist/gstock.js"></script>
Alternativamente, puedes usar un empaquetador.
Para mayor claridad, la documentación generalmente mostrará importaciones desde @gstock/webcomponents. Si no estás usando un resolutor de módulos o empaquetador, necesitarás ajustar estas rutas para que apunten a la carpeta donde se encuentra Gstock Web Components.
Configuración de la ruta base
Algunos componentes dependen de activos (iconos, imágenes, etc.), por lo que es necesario saber dónde se encuentran. Por conveniencia, intentará detectar automáticamente la ubicación correcta basándose en el script desde el que se cargó. Esto asume que los activos están ubicados junto a gstock.js o gstock-autoloader.js y “simplemente funcionará” para la mayoría de los escenarios.
Sin embargo, si estás seleccionando específicamente o empaquetando Gstock Web Components, necesitarás establecer la ruta base. Puedes hacer esto de dos maneras.
<!-- Opción 1: el atributo data-gstock -->
<script src="bundle.js" data-gstock="/path/to/gstock/dist"></script>
<!-- Opción 2: el método setBasePath() -->
<script src="bundle.js"></script>
<script type="module">
import { setBasePath } from '@gstock/webcomponents/dist/utils/base-path.js';
setBasePath('/path/to/gstock/dist');
</script>
Una manera fácil de asegurarse de que la ruta base está configurada correctamente es verificar si los iconos se están cargando.
Referencia de activos
La mayor parte de la magia detrás de los activos es manejada internamente por los componentes web, pero si necesitas hacer referencia a la ruta base por cualquier razón, el mismo módulo exporta una función llamada getBasePath(). Se puede pasar un argumento de cadena, lo que te permite obtener la ruta completa a cualquier activo.
<script type="module">
import { getBasePath, setBasePath } from '@gstock/webcomponents/dist/utils/base-path.js';
setBasePath('/path/to/assets');
// ...
// Obtener la ruta base, ej. /path/to/assets
const basePath = getBasePath();
// Obtener la ruta a un activo, ej. /path/to/assets/file.ext
const assetPath = getBasePath('file.ext');
</script>
Cherry-picking
La selección específica (Cherry-picking) se puede hacer desde npm. Este enfoque cargará solo los componentes que necesites desde el principio, limitando el número de archivos que el navegador tiene que descargar. La desventaja es que tienes que importar cada componente individual.
Aquí hay un ejemplo que carga solo el componente de botón. Nuevamente, si no estás usando un resolutor de módulos, necesitarás ajustar la ruta para que apunte a la carpeta donde se encuentra Gstock Web Components.
<link rel="stylesheet" href="/path/to/gstock/dist/themes/gstock.css" />
<script type="module" data-gstock="/path/to/gstock/dist">
import '@gstock/webcomponents/dist/components/button/button.js';
</script>
Puedes copiar y pegar el código para importar un componente desde la sección “Import” de la documentación del componente. Ten en cuenta que algunos componentes tienen dependencias que se importan automáticamente al hacer selección específica. Si un componente tiene dependencias, se incluirán en la sección “Dependencies” de su documentación.
Nunca selecciones componentes o utilidades específicamente desde gstock.js, ya que esto hará que el navegador cargue toda la biblioteca. En su lugar, selecciona componentes específicos como se muestra arriba.
Verás archivos llamados chunk.[hash].js en el directorio chunks. Nunca importes estos archivos directamente, ya que son generados y cambian de versión a versión.
Bundling
Gstock Web Components se distribuye como una colección de módulos ES estándar que todos los navegadores modernos pueden entender. Sin embargo, importar muchos módulos puede resultar en muchas peticiones HTTP y potencialmente tiempos de carga más largos. Usar un CDN puede aliviar esto, pero algunos usuarios pueden querer optimizar aún más sus importaciones con un paquete.
Para usar Gstock Web Components con un paquete, primero instala Gstock Web Components junto con tu empaquetador de elección.
npm install @gstock/webcomponents
Ahora es momento de configurar el empaquetador. Las configuraciones varían para cada herramienta, pero aquí hay algunos ejemplos que te ayudarán a comenzar.
Una vez que el empaquetador está configurado, podrás importar componentes y utilidades de Gstock Web Components.
import '@gstock/webcomponents/dist/themes/gstock.css';
import '@gstock/webcomponents/dist/components/button/button.js';
import '@gstock/webcomponents/dist/components/icon/icon.js';
import '@gstock/webcomponents/dist/components/input/input.js';
import { setBasePath } from '@gstock/webcomponents/dist/utils/base-path.js';
// Establece la ruta base a la carpeta donde copiaste los activos de Gstock Web Components
setBasePath('/path/to/gstock/dist');
// <gstock-button>, <gstock-icon>, <gstock-input> están listos para usar
Los módulos de componentes incluyen efectos secundarios para fines de registro. Debido a esto, importar directamente desde @gstock/webcomponents puede resultar en un tamaño de paquete más grande de lo necesario. Para una mejor optimización, siempre selecciona específicamente los componentes y utilidades desde sus respectivos archivos como se muestra arriba.
Cómo evitar el auto-registro de importaciones
Por defecto, las importaciones de componentes web se auto-registrarán. Esto puede no ser ideal en todos los casos. Para importar solo la clase del componente sin auto-registrar su etiqueta, podemos hacer lo siguiente:
- import GstockButton from '@gstock/webcomponents/dist/components/button/gstock-button.js';
+ import GstockButton from '@gstock/webcomponents/dist/components/button/GstockButton.js';
Observa cómo la importación comienza con Gstock*.js. Esta es la convención actual para indicar que la importación no se registra por sí misma.
Si bien puedes sobrescribir la clase o volver a registrar la clase gstock con un nombre de etiqueta diferente, si lo haces, muchos componentes no funcionarán como se espera.