Guia Completo em Configurando um Ambiente de Desenvolvimento para Gutenberg

Este guia é para você que deseja escrever código para Gutenberg com sintaxes ES6, ESNext e JSX e precisa configurar webpack e babel para transformá-los em arquivos que você pode usar no editor Gutenberg. Veremos o que você precisa fazer, por que e como podemos usar e estender os padrões do WordPress e personalizá-los para atender às nossas necessidades.

Se você é novo em todos os conceitos de npm, webpcak e Babel, você deve ler a seção a seguir que visa explicar o básico de como essas ferramentas funcionam e como você as usa. No entanto, se você já fez isso antes e está familiarizado com o processo, talvez desenvolvendo com React, pule para a próxima seção onde realmente configuraremos as coisas.

Para iniciantes: npm, webpack e babel

Se você não tiver certeza de por que precisamos fazer tudo isso para escrever Javascript para Gutenberg, recomendo que você leia meu post que explora os fundamentos do desenvolvimento para Gutenberg – onde explico a diferença nas versões de Javascript e por que vale a pena.

Se você nunca fez isso antes, primeiro você precisará instalar o Node.js em seu computador. Clique no link, baixe e instale. Incluído no Node.js, você terá uma ferramenta que usaremos para definir a maior parte da configuração. Esta ferramenta é npm, que permite instalar bibliotecas Javascript e executar scripts através de linha de comando/terminal. Você pode usar alternativamente yarnse preferir, mas para este guia usaremos npm.

npm

Este guia não entrará em detalhes sobre todas as coisas que você pode fazer com npmo, mas explicará o conceito básico dele e as coisas que são relevantes para nossos propósitos. Usaremos npmpara duas coisas; para instalar as bibliotecas necessárias em nosso projeto e para executar comandos para construir (compilar) nossos arquivos Javascript.

Com npmvocê pode instalar qualquer pacote Javascript de código aberto público. Se fôssemos desenvolver com React (fora do WordPress), precisaríamos instalar bibliotecas React e bibliotecas webpack. O WordPress oferece toda uma gama de bibliotecas (principalmente para Gutenberg) que você pode instalar, mas estamos realmente interessados ​​em apenas uma: @wordpress/scripts– o que nos ajuda a simplificar nossa configuração.

Sempre que você instalar uma biblioteca, npmirá criar uma subpasta ” node_modules" onde estão armazenadas as bibliotecas instaladas. Você nunca precisará entrar nesta pasta ou alterar nada aqui, mas tenha em mente que esta pasta conterá facilmente (literalmente!) dezenas de milhares de Esta é uma pasta que você nunca deve colocar no git ou incluir em qualquer tema ou plugin finalizado. As bibliotecas são necessárias apenas durante o desenvolvimento.

Quando seu ambiente está configurado, você pode usar npmpara executar scripts definidos em seu package.jsonarquivo. Dependendo do projeto, você normalmente teria pelo menos dois scripts; um para construir os scripts e outro para iniciar o “modo de observação". No “modo de observação” npminicia um processo no terminal que espera e ouve as alterações feitas em qualquer arquivo e as compila em tempo de execução sempre que você clicar em salvar. Você pode estar familiarizado com esse conceito se já usou programas compiladores SCSS ou LESS antes. É muito mais eficiente executar um script “watch” em segundo plano que recompila toda vez que você salva, em vez de ir ao terminal e executar o comando build após cada alteração.

webpack e babel

Você pode desenvolver para Gutenberg sem fazer qualquer configuração de webpack ou babel. Como usamos as bibliotecas do WordPress, eles cuidarão disso para nós. No entanto, isso tem uma desvantagem – o padrão é um local e nome de arquivo fixos para seus arquivos de origem e de saída. Todo o seu desenvolvimento Javascript precisa ser escrito dentro de um arquivo, em project-folder/src/index.js, e a compilação sempre terminará em project-folder/build/index.js. Se você estiver bem com isso, você pode pular toda a parte sobre a configuração do webpack. No entanto, se você estiver desenvolvendo um tema ou plug-in com vários recursos do Gutenberg (blocos personalizados, filtros, etc.), talvez queira pelo menos um nome de arquivo e local de saída diferentes, além de permitir vários arquivos.

Se você usa o pacote do WordPress para lidar com a configuração (@wordpress/scripts), o Babel já está configurado. Mas você deve estar ciente de que o pacote do WordPress pode não incluir plugins que você queira usar. Existe, por exemplo, um pacote que permite usar as novas chamadas “funções de seta” (myFunction = (param) => { }), para definir funções sem a necessidade de vincular this. Se você realmente deseja usar esses recursos do ESNext, precisará configurar o Babel por conta própria em vez de usar os padrões do WordPress. Vou passar como abaixo.

O processo

O processo de desenvolvimento com o webpack, uma vez que tudo esteja configurado e instalado, é navegar até a pasta do seu projeto no terminal e iniciar o script “watch”. Ele permanecerá aberto e ouvirá as alterações feitas em seus arquivos JS. Sempre que você clicar em salvar em seus arquivos Javascript, o terminal exibirá informações (espero) de que recompilou o arquivo com sucesso. Se houver algum erro de compilação, ele aparecerá no terminal. Para interromper o processo de “observação”, pressione CTRL + C.

Configurando o ambiente

Eu suponho que você já tenha um WordPress local rodando em alguma pilha LAMP (programas como WampServer, XAMPP, Docker ou similares), e que você tenha um plugin ou tema pronto para começar a codificar seu Javascript.

Eu recomendo criar uma subpasta dedicada ao seu desenvolvimento Javascript, pois você pode acabar com vários arquivos e pastas de configuração. Isso facilita a separação de arquivos e pastas (por exemplo node_modules/) que você não deseja incluir em git commits ou compilações finais. Mas não há problema em usar seu tema principal ou pasta de plugins como pasta de projeto para desenvolvimento Javascript.

No terminal (terminal do Mac OS ou prompt de comando do Windows ambos funcionam bem), navegue até a pasta do projeto. Quanto a este tutorial, vou assumir que estamos em um tema e criamos uma subpasta vazia gutenberg-dev/como nossa pasta de projeto.

O primeiro passo é inicializar um projeto npm – que é basicamente apenas dizer npmpara gerar um package.jsonarquivo. Este package.jsonarquivo informa npmsobre quais pacotes são necessários e quais scripts estão disponíveis para execução. Digite isso no terminal;

npm init -y

Isso gera um package.jsonarquivo com conteúdo padrão na pasta do seu projeto.

Em seguida, instalaremos o pacote do WordPress que nos ajudará a reduzir a quantidade de configuração que precisaremos fazer. Execute este comando:

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

A tag --save-devestá informando npmque as bibliotecas fornecidas são necessárias apenas para desenvolvimento, e --save-exactestá certificando-se de npminstalar apenas uma versão, a mais recente.

Abra o package.jsonarquivo em seu editor. (npmtambém terá gerado um package-lock.jsonao instalar os pacotes, você pode simplesmente ignorar este arquivo, é nele package.jsonque você fará alterações). Ele deve ser preenchido com a configuração padrão, e você pode notar que a instalação do pacote que fizemos anteriormente adicionou uma entrada @wordpress/scriptsde uma determinada versão no devDependencies. À medida que você instalar mais pacotes, npmatualizará package.jsoncom entradas para cada pacote. Tudo o que precisamos nos preocupar neste arquivo é a scriptspropriedade, que são os scripts (comandos) que você pode usar npmpara executar. Atualize a propriedade scripts para isso (você pode remover o “teste” padrão):

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

Este trecho de código informa npmque temos dois scripts que podemos executar nesta pasta do projeto; “construir” e “começar”. Executamos um script com o comando npm run <scriptname>, no qual npmiremos pesquisar package.jsone executar o comando definido como seu valor. Usamos a ferramenta wp-scriptsque veio no pacote que instalamos agora para compilar nosso Javascript uma vez ("build") ou iniciar o modo “watch” / “listen” para compilar sempre que salvarmos as alterações ("start").

Isso também nos permite usar o webpack do WordPress e a configuração do Babel, para que não precisemos fazer isso sozinhos.

Na pasta do seu projeto crie uma subpasta chamada src/. Dentro desta pasta crie um index.jsarquivo.

Se você está bem com os padrões do webpack, agora está feito! Escreva seu código ES6 e JSX em index.jse diga npmpara compilá-los executando o comando build:

npm run build

ou inicie um processo de “observação” no terminal que escute as alterações feitas com este comando (use CTRL+C para interromper o processo de observação):

npm run start

A execução de qualquer um deles gerará uma build/subpasta no diretório do projeto com o resultado compilado em build/index.js.

Isso é tudo para a configuração de ambiente mais básica! Agora você está pronto para escrever Javascript ES6 para Gutenberg!

Se você deseja alterar o local e os nomes dos arquivos de origem ou de saída, continue lendo.

Configurando nomes e caminhos de arquivos de origem e saída

Se você, como eu, não estiver satisfeito com o nome e a estrutura do arquivo padrão – especialmente para o(s) arquivo(s) de saída, você precisa verificar a configuração do webpack. Normalmente, por exemplo, se você estivesse desenvolvendo para React fora do WordPress, você precisaria definir uma configuração completa de webpack com o plugin Babel. Felizmente, o WordPress cuida disso para nós e nos permite estender a configuração do próprio pacote de web do WordPress e ajustar apenas as partes que queremos alterar.

Na pasta do seu projeto (mesma pasta que package.json) crie um arquivo chamado webpack.config.jse abra-o em seu editor. Escreva o seguinte neste arquivo:

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'
    }
}

A primeira coisa que fazemos é buscar @wordpress/scriptsa configuração do webpack na variável defaultConfig. Dentro da configuração do webpack module.exports, a primeira coisa que fazemos é aplicar tudo defaultConfigusando o operador spread (...). Essas duas partes garantem que estendemos a configuração do webpack do WordPress, incluindo tudo dentro dele. Após o operador de spread podemos ajustar ou adicionar qualquer propriedade que desejamos alterar; no nosso caso, o local de origem e o local de saída.

A entrypropriedade define os arquivos de origem, que por padrão são ./src/index.js. Cada entrada na entrypropriedade é um par chave + valor que o webpack compilará (e assistirá). No exemplo acima eu defini ‘ block-mynamespace-myblock‘ localizado src/block-mynamespace-myblock.jscomo um ponto de entrada. Você pode adicionar quantos pares de chave + valor aqui para cada arquivo de origem que deseja compilar.

A outputpropriedade decide a localização dos arquivos compilados. Em pathvocê define a pasta de destino para todos os arquivos compilados. Estou usando um auxiliar de caminho para poder navegar nos diretórios corretamente na minha configuração. No exemplo acima, estou dizendo ao webpack que todos os arquivos compilados devem terminar na minha theme-folder/assets/js/gutenberg/pasta. O importante é usar ../para percorrer a árvore de diretórios, sair da pasta do projeto e entrar em outra pasta onde quero que todos os arquivos Javascript do meu tema estejam. Ajuste o caminho para se adequar à estrutura do seu projeto.

Em segundo lugar, estou dizendo ao webpack que todos os nomes de arquivos devem ser nomeados como seus entrynomes de chave correspondentes. theme-folder/gutenberg-dev/src/block-mynamespace-myblock.jsEsta configuração do webpack compilará meu arquivo theme-folder/assets/js/gutenberg/block-mynamespace-myblock.js. Se eu adicionasse outro arquivo de origem como par chave + valor em entry, ele seria compilado na mesma pasta com a chave como seu nome de arquivo.

Faça os ajustes desejados em seu webpack.config.jsarquivo e salve. Execute novamente qualquer um dos npmcomandos de compilação para gerar arquivos em seus novos locais.

É isso! Agora você estendeu a configuração do webpack do WordPress e agora controla onde sua fonte e seus arquivos de saída devem ir.

No entanto, quero incluir uma última dica neste guia. A configuração padrão do WordPress para Babel pode estar faltando certos plugins Babel para certos novos recursos no ESNext. Por exemplo, com o padrão acima e os padrões do WordPress, você não poderá usar funções de seta em seu código. Se isso é importante para você, continue lendo.

Adicione suporte para as sintaxes ESNext mais recentes com o Babel

No momento da redação deste artigo, a configuração padrão do Babel do WordPress não tem suporte para “sintaxes experimentais”, que inclui, por exemplo, funções de seta. Para adicionar suporte para isso, você precisa fornecer seu arquivo de configuração do Babel, e ainda não encontrei uma maneira de estender a configuração do Babel do WordPress como fizemos com a configuração do webpack acima. Portanto, precisamos redefinir as predefinições do Babel, além de adicionar o plug-in “sintaxes experimentais”. Mas não se preocupe, é um arquivo muito pequeno.

O primeiro passo é instalar alguns pacotes que precisamos para as predefinições do Babel – precisamos instalar os mesmos definidos na configuração do Babel do WordPress. Execute este comando para instalar @babel/preset-enve @babel/preset-react, assim como o pacote em que estamos interessados; @babel/plugin-proposal-class-properties:

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

A segunda etapa é adicionar o arquivo de configuração do Babel. Na pasta do seu projeto, crie um arquivo chamado .babelrc(sem extensão de arquivo).

Nota para Windows: Se você estiver sentado em uma máquina Windows, não poderá criar arquivos sem extensões de arquivo. Para contornar isso, você pode criar este arquivo usando o terminal/prompt de comando. Execute este comando:

Este comando produzirá “hi” no arquivo .babelrcna pasta atual. Agora você pode abrir este arquivo em seu editor, remover o “oi” e adicionar o conteúdo real abaixo.

O seu .babelrcdeve ficar mais ou menos assim:

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

Definimos as mesmas predefinições que você normalmente faria em um projeto React, e o mesmo que o WordPress faz. O que estamos adicionando é a pluginspropriedade. Dentro do array de pluginsadicionamos o @babel/plugin-proposal-class-propertiesplugin Babel necessário para “sintaxes experimentais”, como funções de seta.

Conclusão

Tenha em mente que o WordPress pode mudar sua configuração a qualquer momento, isso é especialmente provável de acontecer porque o Gutenberg é relativamente novo. Como estendemos a configuração do WordPress, podemos em um ponto precisar atualizar nossa configuração novamente para atender às nossas necessidades. Talvez o WordPress decida incluir suporte para sintaxes experimentais para que não tenhamos que fazer toda a configuração do Babel.

Este não é de forma alguma um guia exaustivo para configurar o Webpack e o Babel, mas o resultado de muitas experiências e descobertas. Espero que isso tenha ajudado você a aprender como configurar seu próprio ambiente de desenvolvimento Gutenberg, e facilitou o suficiente para que isso não seja um grande obstáculo para começar a aprender ES6, ESNext, JSX e todas essas coisas boas benéficas para o desenvolvimento para Gutemberg!