Configuración de un proyecto en Vite

En un principio, establecimos que existen muchas alternativas para crear una aplicación React y, en particular, recomendamos el uso de Vite (un entorno de desarrollo rápido para aplicaciones web modernas, también conocido como un bundler). Analizamos en menor medida la estructura de un proyecto Vite y cómo se configura, con la finalidad de centrarnos en los conceptos básicos de React.

Ahora, nos enfocaremos en la configuración de un proyecto, recomendando ciertas prácticas y herramientas que facilitan el desarrollo de aplicaciones web.

Compilación y empaquetado de archivos.
Variables de entorno.
Configuración de archivos estáticos (assets).
Build configuration y publicación de paquetes en npm.
Despliegue en entornos de producción.

Compilación y empaquetado de archivos

Hasta el momento, hemos trabajado en un entorno de desarrollo local mediante el uso de un servidor de desarrollo proporcionado por Vite. Para esto, empleamos el comando npm run dev que inicia un servidor local y compila los archivos de la aplicación en tiempo real.

Sin embargo, este comando es proporcionado por Vite y encapsula otras tareas que se realizan en segundo plano, como la compilación y empaquetado de los archivos de la aplicación. Para entender mejor este proceso, analizaremos la estructura del archivo package.json.

Archivo `package.json`

El archivo package.json es un archivo de configuración de un proyecto Node.js que contiene información sobre el proyecto, sus dependencias, scripts de ejecución y metadatos. En particular, Vite utiliza este archivo para definir los scripts de ejecución y las dependencias del proyecto.

1
{
2
    "name": "my-app",
3
    "version": "0.1.0",
4
    "scripts": {
5
        "dev": "vite",
6
        "build": "vite build",
7
        "serve": "vite preview"
8
    },
9
    "dependencies": {
10
        "react": "^17.0.2",
11
        "react-dom": "^17.0.2"
12
    },
13
    "devDependencies": {
14
        "vite": "^2.6.4"
15
    }
16
}

Nombre y versión del proyecto

El campo name define el nombre del proyecto y el campo version define la versión actual del proyecto. Estos campos son utilizados por npm para identificar el proyecto y sus dependencias. Hasta el momento, estos campos no han sido relevantes para el desarrollo de la aplicación, pero veremos que al momento de publicar un paquete en npm, estos campos son importantes.

Scripts de ejecución

El campo scripts define los comandos de ejecución que se pueden utilizar en el proyecto. En particular, Vite define tres comandos de ejecución:

dev: inicia un servidor de desarrollo local. Internamente, este comando ejecuta vite, el cual permite compilar y empaquetar los archivos de la aplicación en tiempo real. Al emplear este comando, se puede acceder a la aplicación en http://localhost:5173, el puerto por defecto de Vite. Sin mencionar que, al realizar cambios en los archivos de la aplicación, estos se reflejan en el navegador sin necesidad de recargar la página.
build: compila y empaqueta los archivos de la aplicación en modo de producción. Este comando genera una carpeta dist que contiene los archivos optimizados para producción.

Cuando nos referimos a optimizados, queremos decir que los archivos son minificados y agrupados para reducir el tamaño de la aplicación y mejorar su rendimiento.

Estos archivos son los que se deben desplegar en un servidor de producción.

Este comando se ejecuta mediante el comando npm run build, pero como se puede observar en el archivo package.json, el comando vite build es quien realiza la compilación y empaquetado de los archivos.
preview: inicia un servidor local para previsualizar la aplicación en modo de producción. Es decir, este comando inicia un servidor local que sirve los archivos de la carpeta dist generada por el comando build. No debemos confundir este comando con el comando dev, ya que este último inicia un servidor de desarrollo local y lo que se previsualiza se basa en los archivos de la carpeta src. Recuerda que el comando preview sólo se puede ejecutar después de haber ejecutado el comando build.
lint: ejecuta el linter de ESLint para analizar el código fuente de la aplicación y detectar posibles errores y malas prácticas. Este comando se ejecuta mediante el comando npm run lint y acepta diferentes opciones para personalizar el análisis del código fuente.

Además de estos comandos, se pueden definir otros comandos de ejecución en el campo scripts del archivo package.json. Por ejemplo, se pueden definir comandos para ejecutar pruebas unitarias, pruebas de integración, análisis de código, y, en particular, comandos para desplegar la aplicación en un servidor de producción (como GitHub Pages, Netlify, Vercel, entre otros).

Variables de entorno

Las variables de entorno son una forma de configurar una aplicación en función del entorno en el que se ejecuta. Independientemente del lenguaje de programación, framework o librería que se utilice, es una práctica común y recomendada para separar la configuración de la aplicación de su código fuente.

En general, las variables de entorno se utilizan para almacenar información sensible, como claves de acceso, tokens de autenticación, URLs de servicios, entre otros. Además, estas mismas variables pueden tener valores diferentes en función del entorno de ejecución (desarrollo, pruebas, producción).

Para acceder a las variables de entorno en una aplicación React existen múltiples alternativas, pero siendo Vite nuestro entorno de desarrollo, queremos hacer énfasis en la forma en que este maneja las variables de entorno.

Vite y las variables de entorno

Vite expone las variables de entorno a través de un objeto global llamado import.meta.env, el cual es estáticamente reemplazado en tiempo de compilación. Este objeto contiene ciertas variables predefinidas:

import.meta.env.MODE (string): indica el modo de ejecución de la aplicación.
import.meta.env.BASE_URL (string): indica la URL base de la aplicación.
import.meta.env.PROD (boolean): indica si la aplicación se está ejecutando en modo de producción.
import.meta.env.DEV (boolean): siempre que la aplicación se esté ejecutando en modo de desarrollo (siempre es opuesto a PROD).
import.meta.env.SSR (boolean): indica si la aplicación se está ejecutando en un entorno de servidor.

Archivo `.env`

Vite utiliza la librería dotenv para cargar variables de entorno desde los archivos .env definidos en la raíz del proyecto.

.env: se carga en todos los casos.
.env.local: se carga en todos los casos, pero se ignora en el control de versiones (o al menos no se recomienda su inclusión).
.env.[mode]: se carga solo en el modo especificado.
.env.[mode].local: se carga solo en el modo especificado, pero se ignora en el control de versiones.

Las variables de entorno definidas en estos archivos se pueden acceder como cadenas de texto a través de import.meta.env.

Para evitar que las variables de entorno se filtren accidentalmente al cliente, solo se exponen las variables que comienzan con VITE_ al código procesado por Vite. Por ejemplo, si se define una variable VITE_DATA en el archivo .env, se puede acceder a ella en el código de la aplicación como import.meta.env.VITE_DATA. Por el contrario, si se define una variable DATA, esta no estará disponible en el código de la aplicación.

1
VITE_DATA=Hello, world!

De igual forma, se puede acceder al modo de ejecución de la aplicación a través de import.meta.env.MODE.

1
function App() {
2
    const data = import.meta.env.VITE_DATA;
3
    const mode = import.meta.env.MODE;
4
    return (
5
        <>
6
            <h1>Vite esta siendo ejecutado en modo {mode}</h1>
7
            <p>
8
                Usando datos de <strong>{data}</strong>
9
            </p>
10
        </>
11
    );
12
}

Modo de ejecución

Por defecto, el servidor dev se ejecuta en modo de desarrollo y el comando de “construcción” o compilación (build) se ejecuta en modo de producción. Esto significa que, cuando Vite compila la aplicación, se reemplazan las variables de entorno definidas en el archivo .env correspondiente al modo de ejecución (.env.production).

Como sabemos, el comando npm run build es solo un alias para vite build. Este último, admite un argumento --mode que permite especificar el modo de ejecución de la aplicación. Por ejemplo, si se desea compilar la aplicación en modo de producción, se puede ejecutar el comando vite build --mode production. De manera similar, se pueden definir otros modos de ejecución.

Aun así, veremos que los comando dev y build son los más utilizados en el desarrollo de aplicaciones web, ya que estos controlan el modo que deber ser utilizado en cada caso y, por ende, las variables de entorno que se deben cargar.