Configurar un servidor de desarrollo local con esbuild te permite trabajar tu aplicación React con recarga en tiempo real, variables de entorno y bundling optimizado. Aquí aprenderás a crear el archivo de configuración, resolver los errores típicos y dejar tu proyecto listo para desplegar.

¿Cómo crear el archivo esbuild.config.js?

El primer paso es centralizar la configuración del bundler en un archivo dedicado. Crea un nuevo archivo llamado esbuild.config.js en la raíz del proyecto e importa esbuild-serve, la dependencia que instalaste previamente y que habilita el servidor local con observación de cambios.

Dentro de este archivo pasas un objeto de configuración con las propiedades clave del proceso de empaquetado:

• entryPoints: array de strings que indica el punto de entrada, en este caso index.tsx.
• bundle: en true para unir todos los módulos en un solo archivo.
• minify: en true para reducir el tamaño del código.
• sourceMap: en true para facilitar el debugging.
• outfile: la ruta de salida, por ejemplo dist/bundle.js.

js import server from 'esbuild-serve';

server({ entryPoints: ['index.tsx'], bundle: true, minify: true, sourceMap: true, outfile: 'dist/bundle.js', define: { 'process.env.NODE_ENV': '"development"', 'process.env.DEBUG': 'false' } }, { port: 3005, root: '.' });

¿Para qué sirve la propiedad define en esbuild? Te permite inyectar variables de entorno en tiempo de compilación, como process.env.NODE_ENV o process.env.DEBUG, para que tu código sepa si corre en desarrollo o producción.

¿Cómo defines el puerto y la raíz del servidor?

El segundo argumento que recibe esbuild-serve es un objeto con la configuración del servidor. Allí indicas el port, por ejemplo 3005, y la propiedad root apuntando a la estructura raíz del proyecto. Con esto el servidor sabe desde dónde servir los archivos estáticos y en qué puerto escuchar [03:10].

¿Cómo ejecutar esbuild desde el package.json?

Para que el comando npm run start use esta nueva configuración, debes ajustar los scripts. Reemplaza la instrucción anterior de esbuild por una que ejecute el archivo recién creado y active la bandera de observación de cambios.

En el package.json, el script start debe apuntar a node esbuild.config.js con el flag de watch para que detecte modificaciones en tiempo real.

¿Por qué aparece el error sobre módulos en package.json?

Al ejecutar el comando por primera vez es muy probable que veas un error que pide definir el tipo como módulo. Los errores son tus aliados: te dicen exactamente qué falta. La solución es agregar la propiedad type con el valor module en el package.json, lo que habilita la sintaxis de import/export ES Modules que estamos usando.

{ "type": "module" }

¿Qué significa type module en package.json? Le indica a Node.js que interprete los archivos .js del proyecto como módulos ECMAScript en lugar de CommonJS, permitiéndote usar import y export nativamente.

¿Cómo evitar errores de tipeo al importar dependencias?

Un detalle fácil de pasar por alto es la coherencia entre el nombre con el que importas una dependencia y el nombre con el que la invocas después. Si haces import server from 'esbuild-serve' pero luego llamas a otra variable, el código fallará aunque Visual Studio Code a veces resuelva la referencia automáticamente.

La recomendación es validar siempre el código antes de correrlo y mantener el mismo identificador en la importación y en la ejecución. Aunque haya un error ortográfico, ambos lados deben coincidir para que funcione sin inconvenientes.

Una vez ajustada la configuración, vuelve a la terminal, ejecuta npm run start y verás cómo el servicio levanta sin problemas. Abre tu navegador en localhost:3005 y tu aplicación React estará corriendo en el entorno de desarrollo local [05:30].

¿Cómo desplegar tu proyecto React con gh-pages?

Con el ambiente de desarrollo funcionando, el siguiente paso es publicar tu trabajo. El reto es subir el proyecto a GitHub Pages usando la dependencia gh-pages, que automatiza la publicación de los archivos compilados.

El flujo es directo y tiene cuatro pasos claros:

1. Instalar gh-pages como dependencia de desarrollo.
2. Agregar el comando de deploy a la sección scripts del package.json.
3. Subir todos tus cambios al repositorio remoto.
4. Ejecutar el comando de deploy y esperar unos minutos a que la página web esté disponible.

Si ya tienes experiencia con React, este es el momento de modificar componentes, mejorar estilos y mostrar una versión personalizada. Y si estás empezando, cambia textos, prueba cosas y observa cómo el servidor refleja cada modificación al instante.

Déjame en los comentarios el enlace a tu proyecto desplegado para revisarlo. ¿Qué cambios le hiciste a tu primera implementación con esbuild?