Guía completa para configurar un entorno de desarrollo para Gutenberg

Esta guía es para usted que desea escribir código para Gutenberg con sintaxis ES6, ESNext y JSX, y necesita configurar webpack y babel para transformarlos en archivos que puede usar en el editor de Gutenberg. Veremos qué debe hacer, por qué y cómo podemos usar y ampliar los valores predeterminados de WordPress y personalizarlos para que se ajusten a nuestras necesidades.

Si es nuevo en todos los conceptos de npm, webpcak y Babel, debe leer la siguiente sección que tiene como objetivo explicar los conceptos básicos de cómo funcionan estas herramientas y cómo las usa. Sin embargo, si ha hecho esto antes y está familiarizado con el proceso, tal vez desarrollando con React, pase a la siguiente sección donde configuraremos las cosas.

Para principiantes: npm, webpack y babel

Si no está seguro de por qué necesitamos hacer todo esto para escribir Javascript para Gutenberg, le recomiendo que lea mi publicación que explora los conceptos básicos del desarrollo para Gutenberg, donde explico la diferencia en las versiones de Javascript y por qué vale la pena.

Si nunca antes ha hecho esto, primero deberá instalar Node.js en su computadora. Haga clic en el enlace, descárguelo e instálelo. Incluido en Node.js, obtendrá una herramienta que usaremos para establecer la mayor parte de la configuración. Esta herramienta es npm, que le permite instalar bibliotecas Javascript y ejecutar scripts a través de la línea de comandos/terminal. Puede usar alternativamente yarnsi lo prefiere, pero para esta guía usaremos npm.

npm

Esta guía no entrará en detalles sobre todas las cosas que puede hacer con npm, pero explicará el concepto básico y las cosas que son relevantes para nuestros propósitos. Lo usaremos npmpara dos cosas; para instalar las bibliotecas requeridas en nuestro proyecto y para ejecutar comandos para construir (compilar) nuestros archivos Javascript.

Con npmusted puede instalar cualquier paquete Javascript público de código abierto. Si tuviéramos que desarrollar con React (fuera de WordPress), necesitaríamos instalar bibliotecas React y bibliotecas webpack. WordPress ofrece una amplia gama de bibliotecas (principalmente para Gutenberg) que puede instalar, pero en realidad solo estamos interesados ​​en una: @wordpress/scripts– que nos ayuda a simplificar nuestra configuración.

Cada vez que instale una biblioteca, npmse creará una subcarpeta " node_modules" donde se almacenan las bibliotecas instaladas. Nunca necesitará ingresar a esta carpeta ni cambiar nada aquí, pero tenga en cuenta que esta carpeta contendrá fácilmente (¡literalmente!) decenas de miles de archivos. Esta es una carpeta que nunca debe asignar a git o incluir en cualquier tema o complemento terminado. Las bibliotecas solo se necesitan durante el desarrollo.

Cuando su entorno está configurado, puede usarlo npmpara ejecutar scripts definidos en su package.jsonarchivo. Dependiendo del proyecto, normalmente tendría al menos dos guiones; uno para construir los scripts y otro para iniciar el "modo de observación". En el "modo de observación", npminicia un proceso en la terminal que espera y escucha los cambios realizados en cualquier archivo, y los compila en tiempo de ejecución cada vez que presiona guardar. Es posible que esté familiarizado con este concepto si ha utilizado programas compiladores SCSS o LESS anteriormente. Es mucho más eficiente ejecutar un script de "vigilancia" en segundo plano que se vuelve a compilar cada vez que guarda, en lugar de ir a la terminal y ejecutar el comando de compilación después de cada cambio.

paquete web y babel

Puede obtenerlo desarrollando para Gutenberg sin hacer ningún paquete web o configuración de babel. Debido a que usamos las bibliotecas de WordPress, ellos lo manejarán por nosotros. Sin embargo, esto tiene un inconveniente: el valor predeterminado es una ubicación y un nombre de archivo fijos para los archivos de origen y de salida. Todo el desarrollo de Javascript debe escribirse dentro de un archivo, en project-folder/src/index.js, y la compilación siempre terminará en project-folder/build/index.js. Si está de acuerdo con esto, puede omitir toda la parte sobre la configuración del paquete web. Sin embargo, si está desarrollando un tema o complemento con varias características de Gutenberg (bloques personalizados, filtros, etc.), es posible que al menos desee un nombre de archivo de salida y una ubicación diferentes, además de permitir varios archivos.

Si usa el paquete de WordPress para manejar la configuración (@wordpress/scripts), Babel ya está configurado. Pero debe tener en cuenta que es posible que el paquete de WordPress no incluya complementos que desee usar. Hay, por ejemplo, un paquete que le permite usar las nuevas llamadas "funciones de flecha" (myFunction = (param) => { }), para definir funciones sin necesidad de vincular this. Si absolutamente desea utilizar estas funciones de ESNext, deberá configurar Babel usted mismo en lugar de utilizar los valores predeterminados de WordPress. Voy a explicar cómo a continuación.

El proceso

El proceso de desarrollo con webpack una vez que todo está configurado e instalado, es navegar a la carpeta de su proyecto en la terminal e iniciar el script "ver". Permanecerá abierto y escuchará los cambios realizados en sus archivos JS. Cada vez que presione guardar en sus archivos Javascript, el terminal generará información (con suerte) de que ha vuelto a compilar con éxito el archivo. Si hubo algún error de compilación, aparecerá en la terminal. Para detener el proceso de "ver", presione CTRL + C.

Configuración del entorno

Supongo que ya tiene un WordPress local ejecutándose en alguna pila LAMP (programas como WampServer, XAMPP, Docker o similares), y que tiene un complemento o un tema listo para comenzar a codificar su Javascript.

Recomiendo crear una subcarpeta dedicada para su desarrollo de Javascript, ya que podría terminar con varios archivos y carpetas de configuración. Esto facilita la separación de archivos y carpetas (por ejemplo node_modules/) que no desea incluir en las confirmaciones de git o las compilaciones finales. Pero está perfectamente bien usar su tema principal o carpeta de complementos como carpeta de proyecto para el desarrollo de Javascript.

En la terminal (la terminal de Mac OS o el símbolo del sistema de Windows funcionan bien), navegue hasta la carpeta de su proyecto. En cuanto a este tutorial, asumiré que estamos en un tema y hemos creado una subcarpeta vacía gutenberg-dev/como nuestra carpeta de proyecto.

El primer paso es inicializar un proyecto npm, que básicamente es simplemente indicar npmque se genere un package.jsonarchivo. Este package.jsonarchivo informa npmsobre qué paquetes se requieren y qué scripts están disponibles para ejecutar. Escriba esto en la terminal;

npm init -y

Esto genera un package.jsonarchivo con contenido predeterminado en la carpeta de su proyecto.

A continuación, instalaremos el paquete de WordPress que nos ayudará a reducir la cantidad de configuración que tendremos que hacer. Ejecute este comando:

npm install --save-dev --save-exact @wordpress/scripts

La etiqueta --save-devinforma npmque las bibliotecas dadas solo son necesarias para el desarrollo y --save-exactse asegura de que npmsolo instale una versión, la última.

Abre el package.jsonarchivo en tu editor. (npmtambién habrá generado un package-lock.jsonal instalar paquetes, puede simplemente ignorar este archivo, es en el package.jsonque hará cambios). Debe estar lleno con la configuración predeterminada, y es posible que observe que la instalación del paquete que hicimos anteriormente agregó una entrada @wordpress/scriptsde una determinada versión en devDependencies. A medida que instale más paquetes, npmse actualizará package.jsoncon entradas para cada paquete. Todo lo que debemos preocuparnos en este archivo es la scriptspropiedad, que son para scripts (comandos) que puede usar npmpara ejecutar. Actualice la propiedad de scripts en esto (puede eliminar la "prueba" predeterminada):

"scripts": {
    "build": "wp-scripts build",
    "start": "wp-scripts start"
},

Este fragmento de código dice npmque tenemos dos scripts que podemos ejecutar en esta carpeta de proyecto; “construir" y “comenzar”. Ejecutamos un script con el comando npm run <scriptname>, en el que npmbuscará package.jsony ejecutará el comando definido como su valor. Usamos la herramienta wp-scriptsque viene en el paquete que instalamos hace un momento para compilar nuestro Javascript una vez ("build") o iniciar el modo "ver"/"escuchar" para compilar cada vez que guardamos los cambios ("start").

Esto también nos permite usar el paquete web de WordPress y la configuración de Babel, por lo que no tenemos que hacerlo nosotros mismos.

En la carpeta de su proyecto, cree una subcarpeta llamada src/. Dentro de esta carpeta crea un index.jsarchivo.

Si está de acuerdo con los valores predeterminados del paquete web, ¡ya ha terminado! Escriba su código ES6 y JSX en index.js, y dígale npmque los compile ejecutando el comando de compilación:

npm run build

o inicie un proceso de "observación" en la terminal que escuche los cambios realizados con este comando (utilice CTRL+C para detener el proceso de observación):

npm run start

Ejecutar cualquiera de estos generará una build/subcarpeta en su proyecto directamente con el resultado compilado en formato build/index.js.

¡Eso es todo para la configuración del entorno más básica! ¡Ya está listo para escribir Javascript ES6 para Gutenberg!

Si desea cambiar la ubicación y los nombres de archivo de sus archivos fuente o de salida, siga leyendo.

Configuración de rutas y nombres de archivos de origen y salida

Si usted, como yo, no está satisfecho con el nombre de archivo y la estructura predeterminados, especialmente para los archivos de salida, debe considerar la configuración del paquete web. Normalmente, por ejemplo, si estuviera desarrollando para React fuera de WordPress, necesitaría configurar una configuración de paquete web completo con el complemento Babel. Afortunadamente, WordPress se encarga de esto por nosotros y nos permite extender la configuración del propio paquete web de WordPress y ajustar solo las partes que queremos cambiar.

En la carpeta de su proyecto (la misma carpeta que package.json) cree un archivo llamado webpack.config.jsy ábralo en su editor. Escriba lo siguiente en este archivo:

const defaultConfig = require("@wordpress/scripts/config/webpack.config");
const path = require('path');
module.exports = {
    ...defaultConfig,
    entry: {
        'block-mynamespace-myblock': './src/block-mynamespace-myblock.js'
    },
    output: {
        path: path.join(__dirname, '../assets/js/gutenberg'),
        filename: '[name].js'
    }
}

Lo primero que hacemos es obtener @wordpress/scriptsla configuración del paquete web en la variable defaultConfig. Dentro de la configuración del paquete web module.exports, lo primero que hacemos es aplicar todo defaultConfigutilizando el operador de propagación (...). Estas dos partes se aseguran de que ampliemos la configuración del paquete web de WordPress al incluir todo lo que contiene. Después del operador de propagación podemos ajustar o agregar cualquier propiedad que deseemos cambiar; en nuestro caso, la ubicación de origen y la ubicación de salida.

La entrypropiedad define los archivos de origen, que es por defecto ./src/index.js. Cada entrada en entryla propiedad es un par clave+valor que el paquete web compilará (y observará). En el ejemplo anterior, he definido ‘ block-mynamespace-myblock‘ ubicado en src/block-mynamespace-myblock.jscomo un punto de entrada. Puede agregar tantos pares clave+valor aquí para cada archivo fuente que desee compilar.

La outputpropiedad decide la ubicación de los archivos compilados. En pathusted define la carpeta de destino para todos los archivos compilados. Estoy usando un asistente de ruta para poder navegar por los directorios correctamente en mi configuración. En el ejemplo anterior, le digo a webpack que todos los archivos compilados deberían terminar en mi theme-folder/assets/js/gutenberg/carpeta. Lo importante es usar ../para desplazarse hacia arriba en el árbol de directorios, fuera de la carpeta del proyecto y en otra carpeta donde quiero que estén todos los archivos Javascript de mi tema. Ajuste la ruta para que se ajuste a la estructura de su proyecto.

En segundo lugar, le digo a webpack que todos los nombres de archivo deben nombrarse como sus entrynombres de clave correspondientes. Esta configuración de paquete web compilará mi theme-folder/gutenberg-dev/src/block-mynamespace-myblock.jsarchivo theme-folder/assets/js/gutenberg/block-mynamespace-myblock.js. Si tuviera que agregar otro archivo fuente como par clave+valor en entry, se compilaría en la misma carpeta con la clave como nombre de archivo.

Realice los ajustes deseados en su webpack.config.jsarchivo y guárdelo. Vuelva a ejecutar cualquiera de los npmcomandos de compilación para generar archivos en sus nuevas ubicaciones.

¡Eso es todo! Ahora ha ampliado la configuración del paquete web de WordPress y ahora controla dónde deben ir su fuente y sus archivos de salida.

Sin embargo, quiero incluir un último consejo en esta guía. La configuración predeterminada de WordPress para Babel podría carecer de ciertos complementos de Babel para ciertas características nuevas en ESNext. Por ejemplo, con el valor predeterminado anterior y los valores predeterminados de WordPress, no podrá usar funciones de flecha en su código. Si esto te importa, sigue leyendo.

Agregue soporte para las sintaxis ESNext más nuevas con Babel

Al momento de escribir esto, la configuración predeterminada de Babel de WordPress no tiene soporte para "sintaxis experimentales", que incluye, por ejemplo, funciones de flecha. Para agregar soporte para esto, debe proporcionar su archivo de configuración de Babel, y hasta el momento no he encontrado una manera de extender la configuración de Babel de WordPress como lo hicimos con la configuración del paquete web anterior. Por lo tanto, debemos redefinir los ajustes preestablecidos de Babel y agregar el complemento de "sintaxis experimentales". Pero no te preocupes, es un archivo muy pequeño.

El primer paso es instalar algunos paquetes que necesitamos para los ajustes preestablecidos de Babel; necesitamos instalar los mismos definidos en la configuración de Babel de WordPress. Ejecute este comando para instalar @babel/preset-envy @babel/preset-react, así como el paquete que nos interesa; @babel/plugin-proposal-class-properties:

npm install --save-dev @babel/preset-env @babel/preset-react @babel/plugin-proposal-class-properties

El segundo paso es agregar el archivo de configuración de Babel. En la carpeta de su proyecto, cree un archivo llamado .babelrc(sin extensión de archivo).

Nota para Windows: si está sentado en una máquina con Windows, no puede crear archivos sin extensiones de archivo. Para evitar esto, puede crear este archivo usando terminal/Símbolo del sistema. Ejecute este comando:

Este comando generará "hola" en el archivo .babelrcde la carpeta actual. Ahora puede abrir este archivo en su editor, eliminar el "hola" y agregar el contenido real a continuación.

Debería .babelrcverse algo como esto:

{
    "presets": ["@babel/preset-env", "@babel/preset-react"],
    "plugins": [
        [
            "@babel/plugin-proposal-class-properties"
        ]
    ]
}

Definimos los mismos ajustes preestablecidos que normalmente haría en un proyecto de React, y lo mismo que hace WordPress. Lo que estamos agregando es la pluginspropiedad. Dentro de la matriz de pluginsañadimos el @babel/plugin-proposal-class-propertiescomplemento de Babel necesario para las "sintaxis experimentales", como las funciones de flecha.

Conclusión

Tenga en cuenta que WordPress puede cambiar su configuración en cualquier momento, esto es especialmente probable porque Gutenberg es bastante nuevo. Debido a que ampliamos la configuración de WordPress, es posible que en algún momento necesitemos actualizar nuestra configuración nuevamente para satisfacer nuestras necesidades. Quizás WordPress decida incluir soporte para sintaxis experimentales para que no tengamos que hacer toda la configuración de Babel.

Esta no es de ninguna manera una guía exhaustiva para configurar Webpack y Babel, sino el resultado de una gran cantidad de experimentos y desciframientos. Espero que esto le haya ayudado a aprender a configurar su propio entorno de desarrollo de Gutenberg, y lo haya hecho lo suficientemente fácil para que no sea un obstáculo tan grande para comenzar a aprender ES6, ESNext, JSX y todas esas cosas buenas beneficiosas para desarrollar para Gutenberg!