0.1.0 • Published 6 months ago

@asilla3dr/componentes v0.1.0

Weekly downloads
-
License
-
Repository
-
Last release
6 months ago

Creación de una Biblioteca de Componentes con Vue 3 y Vite

Esta documentación describe el proceso de creación de una biblioteca de componentes personalizada con Vue 3 y Vite. Documentación de la Librería de Componentes

Índice

  1. Configuración inicial del proyecto
  2. Estructura de carpetas
  3. Configuración para la biblioteca
  4. Creación de componentes
  5. Exportación de componentes
  6. Proceso de build
  7. Cómo usar la biblioteca
  8. Ejemplos de componentes
  9. Desarrollo local con npm link

1. Configuración inicial del proyecto

Comenzamos creando un nuevo proyecto Vue 3 con su CLI oficial:

npm create vue@latest vue3-libreria
cd vue3-libreria
npm install

2. Estructura de carpetas

Para mantener nuestros componentes organizados, utilizamos la siguiente estructura:

vue3-libreria/
├── src/
│   ├── components/
│   │   ├── Button/
│   │   │   ├── Button.vue
│   │   │   └── index.js
│   │   ├── Card/
│   │   │   ├── Card.vue
│   │   │   └── index.js
│   │   └── index.js
│   └── lib.js
├── vite.config.js
└── package.json

Cada componente tiene su propia carpeta para mantener una buena organización y facilitar la expansión futura.

3. Configuración para la biblioteca

Configuración del package.json

Modificamos el package.json para indicar que estamos construyendo una biblioteca:

{
  "name": "vue3-libreria",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "main": "./dist/vue3-libreria.umd.js",
  "module": "./dist/vue3-libreria.es.js",
  "exports": {
    ".": {
      "import": "./dist/vue3-libreria.es.js",
      "require": "./dist/vue3-libreria.umd.js"
    },
    "./style.css": "./dist/vue3-libreria.css"
  },
  "files": [
    "dist"
  ],
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "test:unit": "vitest"
  },
  "dependencies": {
    "vue": "^3.2.0",
  },
  "peerDependencies": {
    "vue": "^3.2.0"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^5.2.3",
    "@vue/test-utils": "^2.4.6",
    "jsdom": "^26.0.0",
    "sass": "^1.86.3",
    "vite": "^6.2.4",
    "vite-plugin-vue-devtools": "^7.7.2",
    "vitest": "^3.1.1"
  }
}

Configuración de Vite

Configuramos vite.config.js para construir nuestra biblioteca:

import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))  // Alias para facilitar las importaciones desde src
    }
  },
  build: {
    lib: {
      // Asegúrate de que el archivo de entrada esté bien configurado
      entry: fileURLToPath(new URL('./src/lib.js', import.meta.url)),  // Asegúrate de que este archivo existe
      name: 'Vue3Libreria',
      fileName: (format) => `vue3-libreria.${format}.js`  // Genera archivos como vue3-libreria.umd.js y vue3-libreria.es.js
    },
    rollupOptions: {
      external: ['vue'],  // Excluye Vue, ya que debe ser proporcionado por el proyecto que use la librería
      output: {
        globals: {
          vue: 'Vue'  // Asegura que Vue sea globalmente accesible cuando se use en el navegador
        },
        exports: 'named'  // Utiliza exportaciones nombradas para permitir importaciones selectivas
      }
    }
  }
})

4. Creación de componentes

Creamos componentes autocontenidos con estilos encapsulados usando la directiva scoped.

Cada componente incluye:

  • Template para la estructura HTML
  • Script para la lógica y propiedades
  • Estilos encapsulados con scoped

5. Exportación de componentes

Punto de entrada de la biblioteca (lib.js)

Creamos el archivo principal de nuestra biblioteca:

// src/lib.js
import * as components from './components'

// Función de instalación para Vue.use()
const install = (app) => {
  Object.entries(components).forEach(([componentName, component]) => {
    app.component(componentName, component)
  })
}

export default { install }

// Exportar componentes individualmente
export * from './components'

6. Proceso de build

Para compilar la biblioteca, ejecutamos:

npm run build

Esto generará los archivos en la carpeta dist/:

  • vue3-libreria.es.js - Versión ESM (para importaciones modernas)
  • vue3-libreria.umd.js - Versión UMD (para uso con etiquetas script)
  • vue3-libreria.css - Estilos compilados

7. Cómo usar la biblioteca

Para usar la biblioteca en un proyecto Vue, tienes dos opciones principales:

Opción 1: Registrar toda la biblioteca

// main.js
import { createApp } from 'vue'
import App from './App.vue'

// Importar la biblioteca completa
import Vue3Libreria from 'vue3-libreria'
// Importar los estilos (¡muy importante!)
import 'vue3-libreria/style.css'

const app = createApp(App)
// Registrar todos los componentes globalmente
app.use(Vue3Libreria)
app.mount('#app')

Opción 2: Importar componentes individuales

// main.js
import { createApp } from 'vue'
import App from './App.vue'

// Importar componentes específicos
import { Button, Card } from 'vue3-libreria'
// Importar los estilos (¡muy importante!)
import 'vue3-libreria/style.css'

const app = createApp(App)
// Registrar componentes individualmente
app.component('Button', Button)
app.component('Tarjeta', Card) // Puedes usar nombres diferentes si lo deseas
app.mount('#app')

8. Ejemplos de componentes

Usando el componente Button

<template>
  <div>
    <Button primary>Botón Principal</Button>
    <Button danger>Eliminar</Button>
    <Button size="large">Botón Grande</Button>
  </div>
</template>

Usando el componente Card

<template>
  <div>
    <Card 
      title="Tarjeta de ejemplo" 
      subtitle="Subtítulo opcional"
      variant="primary"
      shadow
      hover
    >
      <p>Este es el contenido principal de la tarjeta.</p>
      
      <template #footer>
        <div class="card-actions">
          <Button size="small">Aceptar</Button>
          <Button size="small" variant="danger">Cancelar</Button>
        </div>
      </template>
    </Card>
  </div>
</template>

9. Desarrollo local con npm link

Durante el desarrollo, es conveniente probar la biblioteca en un proyecto real sin necesidad de publicarla en npm. Para esto, utilizamos npm link:

Paso 1: Crear un enlace simbólico en la biblioteca

Primero, navega al directorio de tu biblioteca y crea un enlace simbólico global:

# En el directorio de tu biblioteca (vue3-libreria)
cd /ruta/a/vue3-libreria
npm link

Esto registra la biblioteca en el registro npm local.

Paso 2: Vincular la biblioteca en tu proyecto de prueba

Ahora, ve a tu proyecto donde quieres usar la biblioteca y crea un enlace a la misma:

# En el directorio de tu proyecto de prueba
cd /ruta/a/mi-proyecto
npm link vue3-libreria

Paso 3: Compilar la biblioteca en modo watch (opcional)

Para ver los cambios en tiempo real mientras desarrollas, puedes configurar un script en package.json de tu biblioteca:

"scripts": {
  "dev": "vite",
  "build": "vite build",
  "build:watch": "vite build --watch",
  "preview": "vite preview"
}

Y luego ejecutarlo:

npm run build:watch

Paso 4: Importar correctamente en tu proyecto

En tu proyecto de prueba, asegúrate de importar correctamente los componentes y los estilos:

// main.js
import { createApp } from 'vue'
import App from './App.vue'

// Importar componentes
import { Button, Card } from 'vue3-libreria'
// Importar estilos (¡crucial!)
import 'vue3-libreria/style.css'

const app = createApp(App)
app.component('Button', Button)
app.component('Tarjeta', Card)
app.mount('#app')

Paso 5: Desenlazar cuando ya no sea necesario

Cuando hayas terminado de desarrollar, puedes eliminar los enlaces:

# En tu proyecto de prueba
npm unlink vue3-libreria

# En el directorio de tu biblioteca
npm unlink

10. Publicación en Bitbucket e instalación desde repositorios

Preparación para publicación en Bitbucket

Cuando desarrolles una biblioteca que quieras compartir a través de Bitbucket, es esencial modificar el archivo .gitignore para incluir la carpeta dist/. Por defecto, las plantillas de Vue suelen ignorar esta carpeta, pero necesitamos incluirla para que otros puedan instalar la biblioteca directamente desde Bitbucket.

Modifica tu archivo .gitignore y asegúrate de quitar o comentar la línea que excluye dist:

# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
lerna-debug.log*

node_modules
.DS_Store
# dist  <- Elimina o comenta esta línea
dist-ssr
coverage
*.local

Crear un repositorio en Bitbucket y subir el código

# Inicializa git si aún no lo has hecho
git init

# Añade todos los archivos
git add .

# Haz el primer commit
git commit -m "Versión inicial de la biblioteca de componentes"

# Conecta con tu repositorio remoto (reemplaza la URL con la de tu repositorio)
git remote add origin https://asilla1@bitbucket.org/3dr-dev/componentes.git

# Sube los cambios
git push -u origin main

Instalación desde Bitbucket

Para instalar la biblioteca directamente desde Bitbucket en otro proyecto, usa:

# Para repositorios públicos
npm install git+https://asilla1@bitbucket.org/3dr-dev/componentes.git

Si el repositorio es privado y necesitas incluir las credenciales:

# Con usuario y contraseña
npm install git+https://asilla1:tu_contraseña@bitbucket.org/3dr-dev/componentes.git

# Alternativa usando SSH (más seguro)
npm install git+ssh://git@bitbucket.org/3dr-dev/componentes.git

Esto descargará la biblioteca desde Bitbucket e instalará los archivos según la configuración en tu package.json.

Importación y uso después de instalar desde Bitbucket

La importación funciona igual que con cualquier otra instalación:

// main.js
import { createApp } from 'vue'
import App from './App.vue'

// Importar componentes
import { Button, Card } from 'vue3-libreria'
// Importar estilos
import 'vue3-libreria/style.css'

const app = createApp(App)
app.component('Button', Button)
app.component('Tarjeta', Card)
app.mount('#app')

Solución de problemas comunes al instalar desde Bitbucket

Si encuentras errores al instalar desde Bitbucket, verifica:

  1. La carpeta dist/ está incluida en el repositorio: Asegúrate de que modificaste el .gitignore y subiste los archivos compilados.

  2. El package.json está correctamente configurado: Revisa los campos main, module y exports.

  3. No hay dependencia circular: Elimina cualquier auto-referencia en las dependencias como "vue3-libreria": "file:".

  4. La versión de Vue es compatible: Asegúrate de que las versiones de Vue sean compatibles entre la biblioteca y el proyecto que la usa.

  5. Problemas de autenticación: Si tienes problemas de acceso a un repositorio privado, considera usar SSH en lugar de HTTPS, o asegúrate de que tus credenciales sean correctas.

  6. Caracteres especiales en correos electrónicos: Si tu nombre de usuario es un correo electrónico (como asilla@3drender.es), es posible que necesites codificar el @ como %40:

    npm install git+https://asilla%403drender.es@bitbucket.org/3dr-dev/componentes.git
@asilla3dr/componentescomponentesvue
@asilla3dr/componentes
0.1.0

6 months ago