Instalación de Bootstrap V5, NPM y PARCEL
Introducción
La guía oficial sobre cómo incluir y empaquetar el CSS y JavaScript de Bootstrap en un proyecto utilizando Parcel.
A diferencia de empaquetador Vite, PARCEL permite empacar archivos HTML, CSS Y JS sin pertenecer a una librería o framework de javascript (ReactJS, AngularJS,...) como lo es Bootstrap una librería de CSS, además también permite realizar sitios web MPA (Multi Page Application).
Esta documentación se realizó con base a la oficial entregada por Bootstrap en su página web Bootstrap and Parcel, todos los comando que se usaran en este tutorial son ejecutados en la terminal BASH de GIT.
Configuración Inicial
Se esta construyendo un proyecto Parcel con Bootstrap desde cero, por lo que hay algunos requisitos previos y pasos por adelantado antes de que se pueda empezar. Esta guía requiere que se tenga instalado Node.js y cierta familiaridad con el terminal.
Crear una Carpeta de Proyecto y Configurar npm
Se creará la carpeta
my-page e
inicializaremos npm con el argumento
-y para evitar que haga
todas las preguntas interactivas.
FOLDER_NAME="my-page"
mkdir "$FOLDER_NAME" && cd "$FOLDER_NAME"
npm init -y
Configuración del Espacio de Trabajo
Ya se ha creado la carpeta
my-page e inicializado
npm. Ahora también se creará la carpeta
src, la hoja de estilos y
el archivo JavaScript para completar la estructura del
proyecto. Ejecutar los siguiente comandos desde
my-page, o crear
manualmente la estructura de carpetas y archivos que se
muestra a continuación.
mkdir {src,src/js,src/scss}
touch src/index.html src/js/main.js src/scss/styles.scss
Instalación de Parcel
Sólo hay una dependencia de una única herramienta de
compilación. Parcel instalará automáticamente los
transformadores de lenguaje (como Sass) cuando los detecte. Se
Usa la bandera
--save-dev para indicar que
esta dependencia es sólo para uso de desarrollo y no para
producción.
npm install --save-dev parcel@latest
Se debe verificar la versión instalada de Parcel, debe ser 2.16
con el comando en consola npx parcel --version.
Instalación de Bootstrap
Ahora se puede instalar Bootstrap.También se instalará Popper ya que los desplegables, popovers y tooltips dependen de él para su posicionamiento. Si no se planea usar esos componentes, se puede omitir Popper aquí.
npm install --save bootstrap@latest @popperjs/core@latest
Ahora ya se tiene todas las dependencias necesarias instaladas y se puede poner manos a la obra para configurar Parcel e importar Bootstrap.
Configuración de Parcel
El archivo src/index.html se debe configurar así:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Bootstrap w/ Parcel</title>
<script type="module" src="./js/main.js"></script>
</head>
<body>
<div class="container py-4 px-3 mx-auto">
<h1>Hello, Bootstrap and Parcel!</h1>
<button class="btn site-button btn-primary">Primary button</button>
</div>
</body>
</html>
Parcel detectará automáticamente que se está usando Sass e instalará el plugin Sass Parcel para soportarlo, se puede instalar manualmente ejecutando manualmente el comando npm i --save-dev @parcel/transformer-sass.
en el archivo
package.json añadir
como funcionaran los scripts de PARCEL:
"scripts": {
"dev": "cd dist && rm -Rf * && cd .. && parcel --lazy --open http://localhost:1234/ --no-source-maps",
"start": "parcel serve",
"build": "cd dist && rm -Rf * && cd .. && parcel build --public-url ./ --no-source-maps",
"test": "echo \"Error: no test specified\" && exit 1"
},
Script "dev": "cd dist && rm -Rf * && cd .. && parcel --lazy --open http://localhost:1234/ --no-source-maps": inicia el servidor de desarrollo, para ver en tiempo real como se va construyendo la página
- cd dist && rm -Rf * && cd ..: desocupa el contenido de la carpeta dist/
- parcel: Ejecuta el modo de desarrollo.
- --lazy: Esta bandera le indica a PARCEL que sólo vaya construyendo las hojas web a medida que se necesiten, es útil para cuando el sitio tiene muchas hojas y no hace falta que todas estén presentes.
- --open http://localhost:1234/ : Abre una pestaña del navegador en la dirección http://localhost:1234/.
- --no-source-maps: Con esta bandera PARCEL no genera los archivos map
Script "start": "parcel serve": funciona parecido al script dev.
Script "build": "cd dist && rm -Rf * && cd .. && parcel build --public-url --no-source-maps": genera los archivos de despliegue o de producción./
- parcel build: ejecuta la generación de los archivos para producción.
- --public-url ./: Añade el prefijo "./" en las rutas absolutas a assets. Útil para despliegues en GitHub Pages.
También en este mismo archivo
package.json se debe intercambiar:
"main": "index.js",
por
"source": "src/index.html",
Ahora el punto de entrada es el archivo index.html.
Para asegurarse
que Parcel siempre genere archivos con el mismo nombre (como
index.js
en lugar de nombres hash), se debe utilizar la configuración
avanzada del archivo
.parcelrc:, así:
{
"extends": "@parcel/config-default",
"namers": [
"@parcel/namer-default"
]
}
Este archivo debe estar en el directorio del proyecto junto al
archivo package.json
Esta plantilla está configurada de forma tal que es innecesario realizar correcciones en las rutas absolutas de la(s) páginas web.
Desde ahora se puede iniciar Parcel, en la carpeta my-page en el terminal, ejecuta cualquiera de los dos scripts npm recién añadidos:
npm start
ó
npm run dev
Importación de BOOTSTRAP
Para la importación de Bootstrap en Parcel se requiere dos importaciones, una en el archivo styles.scss y otra en el main.js.
La importación del CSS de Bootstrap. Añade en el archivo src/scss/styles.scss el siguiente código para importar todo el Sass fuente de Bootstrap.
// Import all of Bootstrap's CSS
@import "bootstrap/scss/bootstrap";
La importación del JS de Bootstrap. Añade en el archivo src/js/main.js el siguiente código para importar todo el código fuente de Javascript de Bootstrap:
La importación de código CSS de usuario también se importa en este mismo archivo.
// Import all of Bootstrap's JS
import * as bootstrap from 'bootstrap'
// Import our custom CSS
import '../scss/styles.scss';
Ahora ya se puede generar una página web utilizando Bootstrap y Parcel.
Compilación del proyecto para Producción
Cuando se haya terminado y se quiera obtener la versión para producción se ejecuta el siguiente comando y los archivos se quedan disponibles en la carpeta dist.
npm run build
Es fundamental tener precaución con el código JavaScript
dentro de la etiqueta
<script>, ya que debe tratarse como un módulo.
Si no se hace así, las variables que se actualizan con la
compilación del código HTML pueden no reflejar esos cambios en
las instancias correspondientes en el código JavaScript.
Instalación de un Servidor Local
Qué Es un Servidor Local
Un servidor local es un entorno o programa que permite ejecutar y probar aplicaciones web directamente en el computador del usuario, sin necesidad de estar conectado a Internet ni depender de un servidor remoto.
En otras palabras, simula el funcionamiento de un servidor web real, pero dentro del equipo personal, lo que facilita el desarrollo, prueba y depuración de sitios o aplicaciones antes de publicarlos en línea.
Ejemplo Práctico
Cuando se desarrolla una página web con HTML, CSS, JavaScript, PHP o bases de datos, se puede usar un servidor local para que el navegador interprete correctamente el código y muestre el resultado como lo haría en Internet.
Necesidad de un Servidor Local para PrismJS
Un servidor local se utiliza porque, al intentar ejecutar una página web directamente desde el
archivo index.html almacenado en el computador del usuario (en modo
desarrollo), algunas bibliotecas de JavaScript pueden no funcionar correctamente. En particular,
PrismJS no aplica el formato esperado al código. Por esta razón, se
recurre a un servidor local, que permite simular el entorno de un servidor real y garantizar el
funcionamiento adecuado de todos los scripts y recursos del proyecto. En este caso, se utilizará el
paquete http-server de Node.js.
http-server (Node.js / npm)
http-server en el ecosistema Node.js es una herramienta sencilla
para servir archivos estáticos desde cualquier carpeta del sistema, ideal para pruebas locales o
despliegues ligeros.
A continuación se muestra su uso completo y detallado:
Instalación http-server
Puede instalarse globalmente o como dependencia de desarrollo:
Global:
npm install -g http-server
Local (para un proyecto):
npm install --save-dev http-server
Uso Básico
Dentro del directorio del proyecto (por ejemplo, donde está el archivo index.html):
http-server
Por defecto:
- Servirá los archivos del directorio actual.
- Usará el puerto 8080.
- Mostrará la URL de acceso, algo como:
Starting up http-server, serving ./ Available on: http://127.0.0.1:8080Luego se puede abrir esa dirección en el navegador.
Opciones más Comunes
| Opción | Descripción | Ejemplo |
|---|---|---|
-p <n> |
Define el puerto. | http-server -p 3000 |
-a <ip> |
Define la IP o interfaz de red. | http-server -a 0.0.0.0 |
-c <segundos> |
Tiempo de caché (por defecto 3600). -c-1 desactiva
cache. |
http-server -c-1 |
-o |
Abre el navegador automáticamente. | http-server -o |
-s |
Modo “single page app”: redirige todo a index.html.
|
http-server -s |
--cors |
Habilita CORS (útil para pruebas con APIs). | http-server --cors |
--ssl, --cert, --key |
Sirve contenido con HTTPS (requiere certificados). | http-server --ssl --cert cert.pem --key key.pem |
Ejemplo Completo de Uso de http-server
http-server ./dist -p 8081 -c-1 -o ó http-server ./dist
- Sirve la carpeta
dist - Usa el puerto
8081 - Desactiva el caché
- Abre el navegador automáticamente
Uso desde package.json
En un proyecto Node, se puede agregar un script:
Sintaxis básica:
{
"scripts": {
"start": "http-server ./dist -p 8080 -c-1",
"dev": "http-server ./dist -p 8080 -c-1"
}
}
A continuación, se ejecuta el comando correspondiente, según la opción seleccionada antes:
npm start ó node --run start
ó
npm run dev ó node --run dev
⚠️ Nota Importante
http-server no debe usarse en producción.
No ofrece seguridad avanzada, compresión, ni manejo eficiente de conexiones concurrentes.
Para entornos productivos, se recomienda Nginx, Caddy, o Express con configuración personalizada.
rimraf: Herramienta para Eliminar Carpetas y Archivos
rimraf es una herramienta de Node.js que elimina archivos y carpetas
de forma recursiva (borra todo el contenido interno). Es equivalente al comando rm -rf de Unix y se usa comúnmente para limpiar directorios de proyectos
como node_modules, dist o build.
Instalación de rimraf
npm install rimraf --save-dev
Uso básico en la terminal
npx rimraf dist
El ejemplo anterior elimina la carpeta dist y todo su
contenido. Si la carpeta no existe, no genera ningún error.
Uso en package.json
Puede agregarse dentro de los scripts para automatizar limpiezas antes de construir el proyecto:
"scripts": {
"dev": "http-server ./dist -p 8080 -c-1",
"start": "rimraf .parcel-cache dist && parcel serve",
"build": "rimraf .parcel-cache dist && parcel build --public-url ./ --no-source-maps",
"test": "echo \"Error: no test specified\" && exit 1"
},
Archivo package.json Final
Este es el archivo package.json que finalmente se debe usar con el
proyecto incluyendo el uso de del servidor local http-server y el
eliminador de carpetas y de archivos rimraf.
{
"name": "my-page",
"source": "src/index.html",
"version": "8.15.0",
"description": "",
"scripts": {
"dev": "http-server ./dist -p 8080 -c-1",
"start": "rimraf .parcel-cache dist && parcel serve",
"build": "rimraf .parcel-cache dist && parcel build --public-url ./ --no-source-maps",
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC",
"devDependencies": {
"@parcel/packager-raw-url": "^2.16.0",
"@parcel/transformer-sass": "^2.16.0",
"@parcel/transformer-webmanifest": "^2.16.0",
"parcel": "^2.16.0",
"rimraf": "^6.0.1",
"svgo": "^3.3.2"
},
"dependencies": {
"@popperjs/core": "^2.11.8",
"bootstrap": "^5.3.2",
"bootstrap-icons": "^1.11.3",
"prismjs": "^1.29.0"
}
}
Últimas Configuraciones del Proyecto
En el final de la configuración de la plantilla se instalan dos archivos muy importantes:
.gitignore: Archivo que le dice a Git qué NO subir al repositorio..gitattributes: Archivo que le indica a Git cómo manejar ciertos archivos.
Archivo .gitignore
El archivo .gitignore es un archivo de configuración de
Git que le indica qué archivos o carpetas NO deben ser incluidos en el control de versiones.
Con este archivo se evita subir al repositorio archivos que:
- No son necesarios para el proyecto.
- Son generados automáticamente.
- Contienen información sensible.
- Son específicos de la máquina local.
Ejemplo típico de un archivo .gitignore en un proyecto
node.js:
# Dependencias
node_modules/
# Archivos de construcción
dist/
build/
.parcel-cache/
# Variables de entorno
.env
.env.local
# Logs
*.log
npm-debug.log*
# Sistema operativo
.DS_Store
Thumbs.db
# IDEs
.vscode/
.idea/
*.swp
Este archivo es importante debido a:
-
Evita contaminar el repositorio:
node_modules/puede tener miles de archivos que se instalan connpm install. -
Protege información sensible: API keys, contraseñas en archivos
.env. - Reduce el tamaño del repo: No subes archivos generados que otros pueden crear localmente.
- Evita conflictos: Archivos de configuración personal del IDE no afectan a otros.
Cómo se usa:
- Crea el archivo
.gitignoreen la raíz de tu proyecto. - Lista los archivos/carpetas a ignorar.
- Git automáticamente los excluirá.
Archivo .gitattributes
El archivo .gitattributes es un archivo de configuración de
Git que define atributos específicos para archivos y carpetas en el repositorio.
Este archivo se usa para:
- Normalizar finales de línea (lo más común):
# Asegurar que todos usen LF en el repo * text=auto *.sh text eol=lf *.bat text eol=crlf - Marcar archivos como binarios:
# Archivos binarios *.png binary *.jpg binary *.pdf binary - Excluir archivos de exportaciones/archivos:
# Excluir de exportaciones (opcional) .gitattributes export-ignore .gitignore export-ignore tests/ export-ignore - Definir cómo se muestran los diffs:
*.json diff=json *.md diff=markdown *.min.js -diff - Configurar estrategias de fusión (merge strategies):
package-lock.json merge=ours yarn.lock merge=ours - Lenguaje para estadísticas de GitHub (Linguist):
*.js linguist-language=JavaScript docs/* linguist-documentation vendor/* linguist-vendored
Ejemplo típico de un archivo .gitattributes en un proyecto
node.js:
# Normalizar todos los archivos de texto a LF en el repositorio
* text=auto eol=lf
# Archivos de código siempre con LF
*.html text eol=lf
*.css text eol=lf
*.scss text eol=lf
*.js text eol=lf
*.jsx text eol=lf
*.ts text eol=lf
*.tsx text eol=lf
*.json text eol=lf
*.md text eol=lf
*.yaml text eol=lf
*.yml text eol=lf
# Scripts de shell siempre con LF
*.sh text eol=lf
*.bash text eol=lf
# Archivos especiales de Windows que sí necesitan CRLF
*.bat text eol=crlf
*.cmd text eol=crlf
*.ps1 text eol=crlf
# Archivos binarios
*.png binary
*.jpg binary
*.jpeg binary
*.gif binary
*.ico binary
*.pdf binary
*.zip binary
*.gz binary
*.tar binary
*.mp4 binary
*.mp3 binary
*.woff binary
*.woff2 binary
*.ttf binary
*.eot binary
# Excluir de exportaciones (opcional)
.gitattributes export-ignore
.gitignore export-ignore
.editorconfig export-ignore