Tutorial de Express parte 2: Crear un sitio web esqueleto

Visión general

Este artículo muestra cómo crear un sitio web "esqueleto" usando la herramienta Generador de aplicaciones de Express, que luego puedes completar con rutas, vistas/plantillas y llamadas a base de datos específicas del sitio. En este caso, usaremos la herramienta para crear el framework de nuestro sitio web Local Library, al que más adelante le añadiremos todo el código restante que el sitio necesite. El proceso es extremadamente simple: solo requiere que invoques al generador en la línea de comandos con un nombre para el nuevo proyecto, especificando opcionalmente también el motor de plantillas del sitio y el generador de CSS.

Las siguientes secciones te muestran cómo invocar el generador de aplicaciones y ofrecen una breve explicación sobre las distintas opciones de vistas y CSS. También explicaremos cómo está estructurado el sitio web esqueleto. Al final, mostraremos cómo puedes ejecutar el sitio web para comprobar que funciona.

Usando el generador de aplicaciones

Ya deberías tener instalado el generador como parte de la configuración de un entorno de desarrollo de Node. Como recordatorio rápido, el paquete generador se instala a nivel de todo el sistema usando el gestor de paquetes npm, tal y como se muestra:

npm install express-generator -g

El generador tiene varias opciones, que puedes ver en la línea de comandos usando el comando --help (o -h):

> express --help

    Usage: express [options] [dir]

  Options:

        --version        output the version number
    -e, --ejs            add ejs engine support
        --pug            add pug engine support
        --hbs            add handlebars engine support
    -H, --hogan          add hogan.js engine support
    -v, --view <engine>  add view <engine> support (dust|ejs|hbs|hjs|jade|pug|twig|vash) (defaults to jade)
        --no-view        use static html instead of view engine
    -c, --css <engine>   add stylesheet <engine> support (less|stylus|compass|sass) (defaults to plain CSS)
        --git            add .gitignore
    -f, --force          force on non-empty directory
    -h, --help           output usage information

Puedes especificar express para crear un proyecto dentro del directorio actual usando el motor de vistas Jade y CSS plano (si especificas un nombre de directorio, el proyecto se creará en una subcarpeta con ese nombre).

express

También puedes elegir un motor de vistas (plantillas) usando --view y/o un motor de generación de CSS usando --css.

¿Qué motor de vistas debería usar?

El Generador de aplicaciones de Express te permite configurar varios motores de vistas/plantillas populares, entre ellos EJS, Hbs, Pug (Jade), Twig y Vash, aunque elige Jade por defecto si no especificas una opción de vista. El propio Express también admite de forma nativa un gran número de otros lenguajes de plantillas (aquí tienes la lista).

En términos generales, deberías elegir un motor de plantillas que ofrezca toda la funcionalidad que necesitas y que te permita ser productivo cuanto antes — o dicho de otro modo, de la misma forma en que eliges cualquier otro componente. Algunas cosas a tener en cuenta al comparar motores de plantillas:

• Tiempo hasta ser productivo: si tu equipo ya tiene experiencia con un lenguaje de plantillas, es probable que sea más productivo usando ese lenguaje. Si no, deberías considerar la curva de aprendizaje relativa de los motores de plantillas candidatos.
• Popularidad y actividad: revisa la popularidad del motor y si cuenta con una comunidad activa. Es importante poder obtener soporte cuando surjan problemas a lo largo de la vida del sitio web.
• Estilo: algunos motores de plantillas usan marcado específico para indicar el contenido insertado dentro del HTML "normal", mientras que otros construyen el HTML con una sintaxis distinta (por ejemplo, usando sangría y nombres de bloque).
• Rendimiento/tiempo de renderizado.
• Características: deberías considerar si los motores que evalúas ofrecen las siguientes características:
  • Herencia de diseño: te permite definir una plantilla base y luego "heredar" solo las partes que quieras que sean diferentes para una página en particular. Este enfoque suele ser mejor que construir plantillas incluyendo varios componentes obligatorios o partiendo de cero cada vez.
  • Soporte de "include": te permite construir plantillas incluyendo otras plantillas.
  • Sintaxis concisa para el control de variables y bucles.
  • Capacidad de filtrar valores de variables a nivel de plantilla, como convertir variables a mayúsculas o dar formato a un valor de fecha.
  • Capacidad de generar formatos de salida distintos a HTML, como JSON o XML.
  • Soporte para operaciones asíncronas y streaming.
  • Funciones del lado del cliente: si un motor de plantillas se puede usar en el cliente, esto permite la posibilidad de hacer todo o la mayor parte del renderizado del lado del cliente.

Para este proyecto, usaremos el motor de plantillas Pug (anteriormente llamado "Jade"), ya que es uno de los lenguajes de plantillas más populares para Express/JavaScript y el generador lo admite de forma nativa.

¿Qué motor de hojas de estilo CSS debería usar?

El Generador de aplicaciones de Express te permite crear un proyecto configurado para usar los motores de hojas de estilo CSS más comunes: LESS, SASS y Stylus.

Al igual que con los motores de plantillas, deberías usar el motor de hojas de estilo que permita a tu equipo ser más productivo. Para este proyecto usaremos CSS puro (la opción por defecto), ya que nuestros requisitos de CSS no son lo bastante complejos como para justificar el uso de otra cosa.

¿Qué base de datos debería usar?

El código generado no usa ni incluye ninguna base de datos. Las aplicaciones Express pueden usar cualquier mecanismo de base de datos admitido por Node (Express en sí no define ningún comportamiento ni requisito adicional específico para la gestión de bases de datos).

Hablaremos de cómo integrar una base de datos en un artículo posterior.

Creación del proyecto

Para la aplicación de ejemplo Local Library que vamos a construir, crearemos un proyecto llamado express-locallibrary-tutorial usando la biblioteca de plantillas Pug y ningún motor de CSS.

Primero, navega hasta donde quieras crear el proyecto y luego ejecuta el Generador de aplicaciones de Express en la línea de comandos como se muestra:

express express-locallibrary-tutorial --view=pug

El generador creará (y mostrará) los archivos del proyecto.

   create : express-locallibrary-tutorial\
   create : express-locallibrary-tutorial\public\
   create : express-locallibrary-tutorial\public\javascripts\
   create : express-locallibrary-tutorial\public\images\
   create : express-locallibrary-tutorial\public\stylesheets\
   create : express-locallibrary-tutorial\public\stylesheets\style.css
   create : express-locallibrary-tutorial\routes\
   create : express-locallibrary-tutorial\routes\index.js
   create : express-locallibrary-tutorial\routes\users.js
   create : express-locallibrary-tutorial\views\
   create : express-locallibrary-tutorial\views\error.pug
   create : express-locallibrary-tutorial\views\index.pug
   create : express-locallibrary-tutorial\views\layout.pug
   create : express-locallibrary-tutorial\app.js
   create : express-locallibrary-tutorial\package.json
   create : express-locallibrary-tutorial\bin\
   create : express-locallibrary-tutorial\bin\www

   change directory:
     > cd express-locallibrary-tutorial

   install dependencies:
     > npm install

   run the app (Bash (Linux or macOS))
     > DEBUG=express-locallibrary-tutorial:* npm start

   run the app (PowerShell (Windows))
     > $env:DEBUG = "express-locallibrary-tutorial:*"; npm start

   run the app (Command Prompt (Windows)):
     > SET DEBUG=express-locallibrary-tutorial:* & npm start

Al final de la salida, el generador ofrece instrucciones sobre cómo instalar las dependencias (tal como se indica en el archivo package.json) y cómo ejecutar la aplicación en distintos sistemas operativos.

Ejecución del sitio web esqueleto

Llegados a este punto, tenemos un proyecto esqueleto completo. El sitio web todavía no hace gran cosa, pero merece la pena ejecutarlo para comprobar que funciona.

1. Primero, instala las dependencias (el comando install obtendrá todos los paquetes de dependencias listados en el archivo package.json del proyecto).

   bash

   cd express-locallibrary-tutorial
   npm install
   

2. Luego ejecuta la aplicación.

   • En el símbolo del sistema (CMD) de Windows, usa este comando:

     batch

     SET DEBUG=express-locallibrary-tutorial:* & npm start
     

   • En Windows PowerShell, usa este comando:

     powershell

     $env:DEBUG = "express-locallibrary-tutorial:*"; npm start
     

     Nota: Este tutorial no cubre los comandos de PowerShell (los comandos "Windows" indicados asumen que usas el símbolo del sistema de Windows).

   • En macOS o Linux, usa este comando:

     bash

     DEBUG=express-locallibrary-tutorial:* npm start
     

3. Luego carga http://localhost:3000/ en tu navegador para acceder a la aplicación.

Deberías ver una página en el navegador parecida a esta:

¡Felicidades! Ahora tienes una aplicación Express funcionando, a la que puedes acceder a través del puerto 3000.

SET DEBUG=express-locallibrary-tutorial:* & npm start

> express-locallibrary-tutorial@0.0.0 start D:\github\mdn\test\exprgen\express-locallibrary-tutorial
> node ./bin/www

  express-locallibrary-tutorial:server Listening on port 3000 +0ms
GET / 304 490.296 ms - -
GET /stylesheets/style.css 200 4.886 ms - 111

Habilitar el reinicio del servidor al modificar archivos

Actualmente, cualquier cambio que hagas en tu sitio web Express no se verá reflejado hasta que reinicies el servidor. Detener y reiniciar el servidor cada vez que haces un cambio se vuelve rápidamente irritante, así que merece la pena dedicar tiempo a automatizar el reinicio del servidor cuando sea necesario.

Una herramienta útil para este propósito es nodemon. Normalmente se instala de forma global (ya que es una "herramienta"), pero aquí la instalaremos y usaremos localmente como dependencia de desarrollo, de modo que cualquier desarrollador que trabaje con el proyecto la obtenga automáticamente al instalar la aplicación. Usa el siguiente comando en el directorio raíz del proyecto esqueleto:

npm install --save-dev nodemon

Si aun así prefieres instalar nodemon de forma global en tu máquina, y no solo en el archivo package.json de tu proyecto:

npm install -g nodemon

Si abres el archivo package.json de tu proyecto, ahora verás una nueva sección con esta dependencia:

{
  "devDependencies": {
    "nodemon": "^3.1.10"
  }
}

Como la herramienta no está instalada de forma global, no podemos ejecutarla desde la línea de comandos (a menos que la agreguemos al PATH). Sin embargo, podemos invocarla desde un script de npm, porque npm sabe qué paquetes están instalados. Busca la sección scripts de tu package.json. Al principio contendrá una sola línea, que comienza con "start". Actualízala añadiendo una coma al final de esa línea, e incorpora las líneas "devstart" y "serverstart":

• En Linux y macOS, la sección scripts quedará así:

  json

  {
    "scripts": {
      "start": "node ./bin/www",
      "devstart": "nodemon ./bin/www",
      "serverstart": "DEBUG=express-locallibrary-tutorial:* npm run devstart"
    }
  }
  

• En Windows, el valor de "serverstart" quedaría así en su lugar (si usas el símbolo del sistema):

  bash

  "serverstart": "SET DEBUG=express-locallibrary-tutorial:* & npm run devstart"
  

Ahora podemos iniciar el servidor casi exactamente igual que antes, pero usando el comando devstart.

El proyecto generado

Ahora vamos a echar un vistazo al proyecto que acabamos de crear. Iremos haciendo algunas pequeñas modificaciones a medida que avancemos.

Estructura de directorios

Ahora que has instalado las dependencias, el proyecto generado tiene la siguiente estructura de archivos (los archivos son los elementos sin el prefijo "/"). El archivo package.json define las dependencias de la aplicación y otra información. También define un script de inicio que invoca al punto de entrada de la aplicación, el archivo JavaScript /bin/www. Este configura parte del manejo de errores de la aplicación y luego carga app.js para hacer el resto del trabajo. Las rutas de la aplicación se guardan en módulos independientes dentro del directorio routes/. Las plantillas se guardan en el directorio /views.

express-locallibrary-tutorial
    app.js
    /bin
        www
    package.json
    package-lock.json
    /node_modules
        [unas 6700 subcarpetas y archivos]
    /public
        /images
        /javascripts
        /stylesheets
            style.css
    /routes
        index.js
        users.js
    /views
        error.pug
        index.pug
        layout.pug

Las siguientes secciones describen los archivos con un poco más de detalle.

package.json

El archivo package.json define las dependencias de la aplicación y otra información:

{
  "name": "express-locallibrary-tutorial",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "start": "node ./bin/www"
  },
  "dependencies": {
    "cookie-parser": "~1.4.4",
    "debug": "~2.6.9",
    "express": "~4.16.1",
    "http-errors": "~1.6.3",
    "morgan": "~1.9.1",
    "pug": "2.0.0-beta11"
  },
  "devDependencies": {
    "nodemon": "^3.1.10"
  }
}

La sección scripts primero define un script "start", que es el que invocamos al llamar a npm start para iniciar el servidor (este script fue añadido por el Generador de aplicaciones de Express). En la definición del script puedes ver que en realidad esto inicia el archivo JavaScript ./bin/www con node.

Ya modificamos esta sección en Habilitar el reinicio del servidor al modificar archivos añadiendo los scripts devstart y serverstart. Estos se pueden usar para iniciar ese mismo archivo ./bin/www con nodemon en lugar de node (esta versión de los scripts es para Linux y macOS, como se explicó antes).

{
  "scripts": {
    "start": "node ./bin/www",
    "devstart": "nodemon ./bin/www",
    "serverstart": "DEBUG=express-locallibrary-tutorial:* npm run devstart"
  }
}

Las dependencias incluyen el paquete express y el paquete de nuestro motor de vistas elegido (pug). Además, contamos con los siguientes paquetes que son útiles en muchas aplicaciones web:

• cookie-parser: se usa para analizar el encabezado de la cookie y rellenar req.cookies (básicamente proporciona un método cómodo para acceder a la información de las cookies).
• debug: una pequeña utilidad de depuración para node, inspirada en la técnica de depuración del núcleo de node.
• morgan: un middleware de registro de solicitudes HTTP para node.
• http-errors: crea errores HTTP donde sea necesario (para el manejo de errores de express).

Las versiones predeterminadas del proyecto generado están un poco desactualizadas. Reemplaza la sección dependencies de tu archivo package.json con el siguiente texto, que especifica las versiones más recientes de estas bibliotecas en el momento de escribir esto:

{
  "dependencies": {
    "cookie-parser": "^1.4.7",
    "debug": "^4.4.1",
    "express": "^5.1.0",
    "http-errors": "~2.0.0",
    "morgan": "^1.10.0",
    "pug": "3.0.3"
  }
}

Luego, actualiza tus dependencias instaladas usando el comando:

npm install

npm update --save

El archivo www

El archivo /bin/www es el punto de entrada de la aplicación. Lo primero que hace es usar require() para importar el punto de entrada "real" de la aplicación (app.js, en la raíz del proyecto), que configura y devuelve el objeto de la aplicación express(). require() es la forma CommonJS de importar código JavaScript, JSON y otros archivos al archivo actual. Aquí especificamos el módulo app.js usando una ruta relativa y omitimos la extensión de archivo opcional (.js).

#!/usr/bin/env node

/**
 * Dependencias del módulo.
 */

const app = require("../app");

El resto del código de este archivo configura un servidor HTTP de node con app en un puerto específico (definido en una variable de entorno, o 3000 si la variable no está definida), y comienza a escuchar y a reportar los errores y conexiones del servidor. Por ahora no necesitas saber nada más sobre este código (todo lo que hay en este archivo es código "repetitivo" o boilerplate), pero siéntete libre de revisarlo si te interesa.

app.js

Este archivo crea un objeto de aplicación express (llamado app, por convención), configura la aplicación con varias opciones y middleware, y luego exporta la aplicación desde el módulo. El siguiente código muestra solo las partes del archivo que crean y exportan el objeto app:

const express = require("express");

const app = express();
// …
module.exports = app;

De vuelta en el archivo de punto de entrada www visto antes, es este objeto module.exports el que se proporciona al llamador cuando se importa este archivo.

Vamos a repasar el archivo app.js en detalle. Primero, importamos al archivo algunas bibliotecas de node útiles usando require(), entre ellas http-errors, express, morgan y cookie-parser, que descargamos antes para nuestra aplicación usando npm; y path, que es una biblioteca central de Node para analizar rutas de archivos y directorios.

const createError = require("http-errors");
const express = require("express");
const path = require("path");
const cookieParser = require("cookie-parser");
const logger = require("morgan");

Luego usamos require() para importar módulos de nuestro directorio de rutas. Estos módulos/archivos contienen código para gestionar conjuntos particulares de "rutas" (rutas de URL) relacionadas. Cuando extendamos la aplicación esqueleto, por ejemplo para listar todos los libros de la biblioteca, añadiremos un nuevo archivo para gestionar las rutas relacionadas con los libros.

const indexRouter = require("./routes/index");
const usersRouter = require("./routes/users");

A continuación, creamos el objeto app usando nuestro módulo express importado, y luego lo usamos para configurar el motor de vistas (plantillas). Configurar el motor consta de dos partes. Primero, establecemos el valor "views" para especificar la carpeta donde se guardarán las plantillas (en este caso, la subcarpeta /views). Luego, establecemos el valor "view engine" para especificar la biblioteca de plantillas (en este caso, "pug").

const app = express();

// configuración del motor de vistas
app.set("views", path.join(__dirname, "views"));
app.set("view engine", "pug");

El siguiente conjunto de funciones llama a app.use() para añadir a la cadena de manejo de solicitudes las bibliotecas de middleware que importamos antes. Por ejemplo, express.json() y express.urlencoded() son necesarias para rellenar req.body con los campos del formulario. Después de estas bibliotecas, también usamos el middleware express.static, que hace que Express sirva todos los archivos estáticos del directorio /public en la raíz del proyecto.

app.use(logger("dev"));
app.use(express.json());
app.use(express.urlencoded({ extended: false }));
app.use(cookieParser());

app.use(express.static(path.join(__dirname, "public")));

Ahora que ya está configurado el resto del middleware, añadimos a la cadena de manejo de solicitudes nuestro código de manejo de rutas (importado previamente). El código importado definirá rutas particulares para las distintas partes del sitio:

app.use("/", indexRouter);
app.use("/users", usersRouter);

El último middleware del archivo añade métodos de manejo para errores y respuestas HTTP 404.

// captura el error 404 y lo reenvía al manejador de errores
app.use((req, res, next) => {
  next(createError(404));
});

// manejador de errores
app.use((err, req, res, next) => {
  // establece las variables locales; solo se proporciona el error en desarrollo
  res.locals.message = err.message;
  res.locals.error = req.app.get("env") === "development" ? err : {};

  // renderiza la página de error
  res.status(err.status || 500);
  res.render("error");
});

El objeto de la aplicación Express (app) ya está completamente configurado. El último paso es añadirlo a las exportaciones del módulo (esto es lo que permite que /bin/www pueda importarlo).

module.exports = app;

Rutas

A continuación se muestra el archivo de rutas /routes/users.js (los archivos de rutas comparten una estructura similar, así que no hace falta mostrar también index.js). Primero, carga el módulo express y lo usa para obtener un objeto express.Router. Luego especifica una ruta en ese objeto y, por último, exporta el enrutador desde el módulo (esto es lo que permite importar el archivo en app.js).

const express = require("express");

const router = express.Router();

/* Lista de usuarios (GET). */
router.get("/", (req, res, next) => {
  res.send("respond with a resource");
});

module.exports = router;

La ruta define un callback que se invocará cada vez que se detecte una solicitud HTTP GET con el patrón correcto. El patrón de coincidencia es la ruta especificada al importar el módulo ("/users") más lo que se defina en este archivo ("/"). En otras palabras, esta ruta se usará cuando se reciba una URL /users/.

Algo interesante en el código anterior es que la función callback tiene el tercer argumento next, por lo que es una función de middleware en lugar de un simple callback de ruta. Aunque el código actualmente no usa el argumento next, puede resultar útil en el futuro si quieres añadir varios manejadores de ruta a la ruta '/'.

Vistas (plantillas)

Las vistas (plantillas) se guardan en el directorio /views (tal como se especifica en app.js) y tienen la extensión de archivo .pug. El método Response.render() se usa para renderizar una plantilla especificada junto con los valores de las variables con nombre pasadas en un objeto, y luego enviar el resultado como respuesta. En el siguiente código de /routes/index.js puedes ver cómo esa ruta renderiza una respuesta usando la plantilla "index" y pasando la variable de plantilla "title".

/* GET home page. */
router.get("/", (req, res, next) => {
  res.render("index", { title: "Express" });
});

A continuación se muestra la plantilla correspondiente a la ruta anterior (index.pug). Hablaremos más sobre la sintaxis más adelante. Por ahora, todo lo que necesitas saber es que la variable title (con el valor 'Express') se inserta donde se especifica en la plantilla.

extends layout

block content
  h1= title
  p Welcome to #{title}

Ponte a prueba

Crea una nueva ruta en /routes/users.js que muestre el texto "Eres tan genial" en la URL /users/cool/. Pruébala ejecutando el servidor y visitando http://localhost:3000/users/cool/ en tu navegador.

Resumen

Ya has creado un proyecto de sitio web esqueleto para Local Library y has comprobado que funciona usando node. Lo más importante es que también entiendes cómo está estructurado el proyecto, así que tienes una buena idea de dónde tendremos que hacer cambios para añadir rutas y vistas a nuestra biblioteca local.

A continuación, empezaremos a modificar el esqueleto para que funcione como el sitio web de la biblioteca.

Véase también

• Express application generator (documentación de Express)
• Using template engines with Express (documentación de Express)

• Anterior
• Overview: Express Web Framework (Node.js/JavaScript)
• Siguiente