Pular para o conteúdo

Processamento de recursos

Minificação

Blockstudio pode minimizar automaticamente todos os arquivos CSS e JS de um bloco.

Os arquivos compilados serão salvos na pasta _dist do bloco e enfileirados quando o bloco for usado. Quando o arquivo-fonte for atualizado, Blockstudio verifica se existe um arquivo compilado com aquele carimbo de data e hora; caso não exista, ele será criado.

A biblioteca minify é usada para esse fim.

A minificação pode ser ativada usando a configuração assets/minify:

PHP
add_filter('blockstudio/settings/assets/minify/css', function() {
  return true;
});

add_filter('blockstudio/settings/assets/minify/js', function() {
  return true;
});

SCSS

Se preferir escrever seus estilos em SCSS, você pode ativar o processamento de SCSS:

PHP
add_filter('blockstudio/settings/assets/process/scss', function() {
  return true;
});

Isso ativará o processamento de SCSS para arquivos .css.

Como alternativa, você pode usar a extensão .scss, e os estilos serão processados automaticamente mesmo quando a configuração acima não estiver true.

Caminhos de importação

Ao usar SCSS, é possível importar outros arquivos SCSS. As importações são relativas ao arquivo de origem.

CSS
@import "modules.scss";

Além disso, é possível definir caminhos de importação personalizados usando o filtro blockstudio/assets/process/scss/import_paths, permitindo importar arquivos de outros diretórios sem especificar a estrutura de pastas.

As importações podem omitir a extensão .scss e resolver parciais como _tokens.scss ou o _index.scss de um diretório.

PHP
add_filter('blockstudio/assets/process/scss/import_paths', function($paths) {
  $paths[] = get_template_directory() . '/scss';
  return $paths;
});

Prelúdio

Se quiser disponibilizar funções, variáveis, mixins ou utilitários compartilhados de Sass em todos os arquivos SCSS, você pode acrescentar um prelúdio global antes da compilação.

Isso é útil para frameworks como Bootstrap, nos quais talvez você queira acessar mixins compartilhados, como breakpoints, sem repetir importações em cada recurso do bloco.

PHP
add_filter('blockstudio/assets/process/scss/prelude', function($prelude, $path, $scss) {
  return '@import "functions";' . "\n"
    . '@import "variables";' . "\n"
    . '@import "mixins";';
}, 10, 3);

Em conjunto com blockstudio/assets/process/scss/import_paths, isso disponibiliza a superfície Sass referenciada em todos os arquivos compilados.

Os recursos dos blocos são recompilados quando o horário de modificação de uma dependência muda, incluindo arquivos importados por outras parciais. Blockstudio acompanha dependências locais de @import, @use e @forward, incluindo dependências do prelúdio e caminhos de importação configurados. Dependências compartilhadas são rastreadas uma única vez, e ciclos não podem entrar em loop durante a descoberta. Esses arquivos também são incluídos na lista de observação do cache em tempo de execução.

Por exemplo, editar mixins/_wysiwyg.scss recompila global-styles.scss quando ele importa scss/_wysiwyg.scss, que por sua vez importa esse mixin. As alterações não exigem modificar o arquivo de entrada. Módulos integrados de Sass e importações remotas são excluídos do grafo de dependências locais.

Módulos ES

Todos os scripts (em linha e padrão) em Blockstudio são carregados com type="module" aplicado por padrão. Isso permite usar a sintaxe de importação nos scripts dos seus blocos sem nenhuma configuração adicional.

Observação

Para saber mais sobre módulos ES, consulte a documentação da Web MDN.

Vamos imaginar o seguinte código dentro de um script.js:

JavaScript
import { h, render } from "https://esm.sh/preact@10.15.1";
import htm from "https://esm.sh/htm@3.1.1";
import confetti from "https://esm.sh/canvas-confetti@1.6.0";

const html = htm.bind(h);

function App(props) {
  confetti();
  return html`<h1>Hello ${props.name}!</h1>`;
}

render(
  html`<${App} name="Hello from Preact!" />`,
  document.querySelector("#element")
);

O exemplo acima criaria um componente usando Preact, importando todos os componentes e funções necessários de um CDN compatível com ESM, neste caso esm.sh. Embora essa abordagem não tenha nenhum problema, ela tem a desvantagem de exigir que os recursos necessários sejam solicitados de um site externo, com o risco de os scripts pararem de funcionar se o CDN ficar fora do ar.

Blockstudio inclui um recurso prático para baixar módulos ES para o bloco, eliminando a necessidade de CDNs ESM externas em produção.

Configuração

Para baixar um módulo para o diretório do bloco, use o prefixo npm: seguido do nome e da versão do pacote:

JavaScript
import { h, render } from "npm:preact@10.15.1";
import htm from "npm:htm@3.1.1";
import confetti from "npm:canvas-confetti@1.6.0";

Essa sintaxe segue a convenção de Deno para o npm especificador.

Observação

O prefixo legado blockstudio/ (e.g., blockstudio/preact@10.15.1) ainda é compatível com versões anteriores, mas recomendamos usar o prefixo npm: em projetos novos. Consulte o guia de migração para saber mais.

Blockstudio verificará automaticamente os arquivos .js alterados em busca de importações e os baixará para o diretório local do bloco. Os arquivos baixados serão colocados em uma pasta modules no diretório do bloco.

Ao salvar, o arquivo de script será reescrito para se adaptar ao módulo hospedado localmente:

JavaScript
import { h, render } from "./modules/preact/10.15.1.js";
import htm from "./modules/htm/10.15.1.js";
import confetti from "./modules/canvas-confetti/1.6.0.js";

No editor, a URL de CDN ainda será usada (Blockstudio usa esm.sh) ao visualizar e trabalhar no bloco.

Observações importantes

Versão

Normalmente, é possível usar módulos de CDNs sem o número da versão. Nesse caso, será sempre usada a versão mais recente. Como Blockstudio não salva nenhuma informação no banco de dados, é necessário especificar o número da versão ao usar módulos.

Mesmos módulos

Os módulos são restritos aos respectivos blocos. Mesmo que você use o mesmo módulo com o mesmo número de versão em vários blocos, Blockstudio ainda baixará o módulo solicitado para o bloco. Isso ocorre principalmente porque os blocos devem ser unidades independentes, que podem ser compartilhadas facilmente entre outras instalações ou sites.

Além disso, o mesmo módulo será solicitado duas vezes se ambos os blocos estiverem presentes em uma página. Esse problema pode ser resolvido usando script-inline.js em vez do arquivo script.js. Blockstudio reescreverá cada importação para apontar para o local da primeira ocorrência do módulo, caso o nome e o número da versão sejam iguais.

Carregador CSS

Também é possível importar arquivos CSS usando a mesma sintaxe acima.

JavaScript
import "npm:swiper@11.0.0/swiper.min.css";

O arquivo CSS será baixado para a pasta modules e enfileirado automaticamente quando o bloco for usado. Desde que a versão seja a mesma, apenas uma versão do arquivo CSS será enfileirada, mesmo que ele exista em vários blocos.