Inicializar un proyecto Symfony con Webpack Encore Bundle, Sass y PostCSS

Symfony es un popular y poderoso marco de trabajo PHP que permite a los desarrolladores construir aplicaciones web escalables y de alto rendimiento. Por otro lado, Webpack es un empaquetador de módulos de JavaScript ampliamente utilizado que facilita la administración de dependencias y la optimización de recursos en aplicaciones web modernas. La integración de Webpack en un proyecto Symfony mejora significativamente el flujo de trabajo de desarrollo al proporcionar una solución eficiente y flexible para gestionar y compilar recursos frontend, como JavaScript, CSS y archivos de imagen.

En este artículo, exploraremos cómo inicializar un proyecto Symfony y configurarlo para utilizar el Webpack Bundle, un paquete que integra Webpack en Symfony.

Al final de este artículo, tendrás un sólido conocimiento de cómo configurar y utilizar el Webpack Bundle en un proyecto Symfony, lo que te permitirá mejorar la eficiencia y la estructura de tus aplicaciones web. Además, podrás aplicar estas técnicas en tus futuros proyectos Symfony para aprovechar al máximo las ventajas que ofrecen tanto Symfony como Webpack.

Para comenzar a inicializar un proyecto Symfony con Webpack Bundle, sigue estos pasos:

Crear un nuevo proyecto Symfony

Abre tu terminal o línea de comandos y ejecuta el siguiente comando para crear un nuevo proyecto Symfony utilizando Composer:

composer create-project symfony/skeleton my_project_directory

Reemplaza my_project_directory con el nombre que deseas para tu proyecto. Una vez finalizado, navega al directorio del proyecto:

cd my_project_directory

Instalar Symfony Webpack Encore Bundle

Webpack Encore es una biblioteca de JavaScript que simplifica la integración de Webpack en proyectos Symfony. Para instalar Webpack Encore y sus dependencias, ejecuta el siguiente comando en la raíz de tu proyecto:

composer require symfony/webpack-encore-bundle

Esto instalará el paquete necesario y actualizará tu archivo composer.json.

Instalar dependencias de Node.js

Encore utiliza Node.js y npm (o yarn) para administrar las dependencias de JavaScript y CSS. Asegúrate de tener Node.js y npm (o Yarn) instalados en tu sistema. Puedes verificar esto ejecutando los siguientes comandos:

node -v
npm -v

Si no tienes Node.js y npm instalados, descárgalos e instálalos desde el sitio web oficial de Node.js.

Una vez que tengas Node.js y npm instalados, ejecuta el siguiente comando en la raíz de tu proyecto para instalar las dependencias de Node.js:

npm install

Configurar Webpack Encore

Encore proporciona un archivo de configuración llamado webpack.config.js en la raíz de tu proyecto. Abre este archivo y modifícalo según tus necesidades. Aquí hay un ejemplo básico de configuración:

const Encore = require("@symfony/webpack-encore");

if (!Encore.isRuntimeEnvironmentConfigured()) {
  Encore.configureRuntimeEnvironment(process.env.NODE_ENV || "dev");
}

Encore.setOutputPath("public/build/")
  .setPublicPath("/build")

  .addEntry("app", "./assets/app.js")

  .splitEntryChunks()
  .enableSingleRuntimeChunk()
  .cleanupOutputBeforeBuild()
  .enableBuildNotifications()
  .enableSourceMaps(!Encore.isProduction())
  .enableVersioning(Encore.isProduction())

  .configureBabelPresetEnv((config) => {
    config.useBuiltIns = "usage";
    config.corejs = "3.23";
  });

module.exports = Encore.getWebpackConfig();

Compilar los recursos frontend

Para compilar tus recursos frontend (JavaScript, CSS, imágenes, etc.) con Webpack, ejecuta el siguiente comando en la raíz de tu proyecto:

npm run dev

Para monitorear los cambios en tus archivos fuente. Cada vez que guardes un cambio en tus archivos frontend (JavaScript, CSS, imágenes, etc.) con Webpack, ejecuta el siguiente comando en la raíz de tu proyecto: public/build.

npm run watch

Para compilar tus recursos frontend (JavaScript, CSS, imágenes, etc.) con Webpack para producción, ejecuta el siguiente comando en la raíz de tu proyecto:

npm run build

Integrar recursos en las plantillas Twig

Para utilizar los recursos compilados en tus plantillas Twig, modifica la plantilla base (por ejemplo, templates/base.html.twig) y agrega las etiquetas de enlace de Webpack Encore:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
        <title>{% block title %}Welcome!{% endblock %}</title>
        <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 128 128%22><text y=%221.2em%22 font-size=%2296%22>⚫️</text></svg>">
        {# Run `composer require symfony/webpack-encore-bundle` to start using Symfony UX #}
        {% block stylesheets %}
            {{ encore_entry_link_tags('app') }}
        {% endblock %}

        {% block javascripts %}
            {{ encore_entry_script_tags('app') }}
        {% endblock %}
    </head>
    <body>
        {% block body %}{% endblock %}
    </body>
</html>

La plantilla utiliza las funciones encore_entry_link_tags() y encore_entry_script_tags() para agregar automáticamente las etiquetas de enlace CSS y las etiquetas de script JavaScript en tu plantilla.

Ahora, todos los recursos frontend (CSS y JavaScript) que hayas definido en webpack.config.js estarán disponibles en tus plantillas Twig.

Crear la primera ruta y vista

En este paso, crearemos una nueva ruta en nuestra aplicación Symfony y una vista asociada llamada home.html.twig, que extenderá de base.html.twig.

Crea un nuevo controlador. En la carpeta src/Controller, crea un nuevo archivo llamado HomeController.php. Agrega el siguiente contenido al archivo:

// src/Controller/HomeController.php

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\Request;

class HomeController extends AbstractController
{
    /**
     * @Route("/", name="home_page")
     */
    public function index(Request $request): Response
    {
        return $this->render("home.html.twig");
    }
}

Esta clase define un controlador HomeController con una acción index() que renderiza la plantilla home.html.twig. La anotación @Route crea una nueva ruta en la URL raíz ("/") y le asigna el nombre "home_page".

Luego crea una nueva plantilla. En la carpeta templates, crea un nuevo archivo llamado home.html.twig. Agrega el siguiente contenido al archivo:

{% extends 'base.html.twig' %}

{% block title %}Home{% endblock %}

{% block body %}
    <h1>Hello world!</h1>
{% endblock %}

Esta plantilla extiende de base.html.twig y personaliza los bloques title y body para mostrar contenido específico de la página de inicio.

Configurar Sass

Webpack Encore te permite utilizar fácilmente preprocesadores como Sass, LESS y Stylus en tu proyecto Symfony. Para usar Sass, sigue estos pasos:

• Instala las dependencias necesarias para Sass. Ejecuta el siguiente comando en la raíz de tu proyecto:

npm install sass-loader@^13.0.0 sass --save-dev

• Actualiza tu archivo webpack.config.js. Agrega la siguiente línea dentro de la función Encore para habilitar Sass:

.enableSassLoader()

• Cambia tus archivos CSS a archivos Sass (.scss). Por ejemplo, renombra assets/css/styles.css a assets/css/styles.scss.

• Actualiza la importación de los estilos en assets/app.js, para hacer referencia al archivo .scss en lugar del archivo .css:

// assets/app.js

import "./styles/app.scss";

Ahora puedes utilizar la sintaxis Sass en tus archivos .scss y Encore los compilará automáticamente en CSS.

Configurar PostCSS Loader

En este paso, vamos a configurar postcss-loader para procesar y optimizar nuestros archivos CSS con PostCSS y sus complementos, como Autoprefixer.

Sigue estos pasos para configurar postcss-loader:

• Instala postcss-loader y autoprefixer como dependencia de desarrollo:

npm install postcss-loader autoprefixer --save-dev

• Crea un archivo de configuración de PostCSS llamado postcss.config.js en la raíz de tu proyecto con el siguiente contenido:

// postcss.config.js

module.exports = {
  plugins: {
    // include whatever plugins you want
    // but make sure you install these via yarn or npm!

    // add browserslist config to package.json (see below)
    autoprefixer: {},
  },
};

• Agrega browserslist a la configuración del package.json:

// package.json

  "browserslist": [
    "> 1%",
    "last 2 versions",
    "not dead"
  ]

• Abre tu archivo webpack.config.js y habilita postcss-loader utilizando el método enablePostCssLoader() proporcionado por Encore. Asegúrate de agregarlo después de configureBabel() y antes de cualquier otro loader de estilos (como enableSassLoader(), enableLessLoader() o enableStylusLoader()). Tu configuración debería verse así:

const Encore = require("@symfony/webpack-encore");

if (!Encore.isRuntimeEnvironmentConfigured()) {
  Encore.configureRuntimeEnvironment(process.env.NODE_ENV || "dev");
}

Encore.setOutputPath("public/build/")
  .setPublicPath("/build")

  .addEntry("app", "./assets/app.js")

  .splitEntryChunks()
  .enableSingleRuntimeChunk()
  .cleanupOutputBeforeBuild()
  .enableBuildNotifications()
  .enableSourceMaps(!Encore.isProduction())
  .enableVersioning(Encore.isProduction())

  .configureBabelPresetEnv((config) => {
    config.useBuiltIns = "usage";
    config.corejs = "3.23";
  })

  .enablePostCssLoader()
  .enableSassLoader();

module.exports = Encore.getWebpackConfig();

Con esta configuración, postcss-loader procesará tus archivos CSS utilizando los plugins de PostCSS especificados en tu archivo de configuración postcss.config.js. Esto permitirá aplicar automáticamente prefijos de navegadores y realizar otras optimizaciones en tus archivos CSS.

Con estos pasos, has inicializado un proyecto Symfony con Webpack Bundle y configurado los recursos frontend. Ahora puedes continuar desarrollando tu aplicación, sabiendo que tus recursos frontend están optimizados y bien organizados.

Esperamos que este artículo te haya sido útil para aprender cómo inicializar un proyecto Symfony con Webpack Bundle y configurar los recursos frontend de manera eficiente. A lo largo de este artículo, hemos cubierto cómo configurar Symfony, instalar Webpack Encore y gestionar diferentes aspectos de los recursos frontend, como la compilación de archivos de estilo, la optimización de imágenes y la configuración de Sass, PostCSS y Autoprefixer.

Gracias por tomarte el tiempo de leer este artículo y espero que te haya sido de gran ayuda en tu desarrollo web con Symfony. Si tienes alguna pregunta o encuentras algún problema, no dudes en dejar un comentario.

El código completo de este proyecto está disponible en Github. No dudes en clonar o bifurcar el repositorio y utilizarlo como punto de partida para tus propios proyectos Symfony. Si encuentras errores o tienes sugerencias para mejorar el proyecto, no dudes en enviar un "pull request" o abrir un "issue" en GitHub.

¡Buena suerte en tu aventura de desarrollo con Symfony y Webpack Bundle! Y, una vez más, gracias por leer.