Extensão do Webpack na cadeia de ferramentas da Estrutura do SharePoint

Artigo
06/29/2022

O Webpack é um empacotador de módulo JavaScript que usa arquivos JavaScript e suas dependências e gera um ou mais arquivos JavaScript para que você possa carregar diferentes trechos de código para diferentes cenários.

A cadeia de ferramentas de estrutura usa CommonJS para empacotamento. Isso permite que você defina módulos e onde deseja usá-los. A cadeia de ferramentas também usa SystemJS, um carregador de módulos universal, para carregar seus módulos. Isso ajuda a criar um escopo como Web Parts, garantindo que cada Web Part seja executada em seu próprio namespace.

Uma tarefa comum que você pode adicionar à cadeia de ferramentas da Estrutura do SharePoint é estender a configuração do Webpack com carregadores e plug-ins personalizados.

Usar carregadores Webpack

Existem muitos casos em que você gostaria de importar e usar um recurso não JavaScript durante o desenvolvimento, o que normalmente é feito com imagens ou modelos. Um carregador Webpack converte o recurso em algo que possa ser usado pelo seu aplicativo JavaScript ou fornece uma referência simples que seu aplicativo JavaScript possa entender.

Por exemplo, um modelo de markdown pode ser compilado e convertido em uma cadeia de texto, enquanto um recurso de imagem pode ser convertido em uma imagem Base64 embutida ou pode ser referenciado como um URL e copiado para seu diretório dist para implantação.

Há diversos carregadores úteis, vários dos quais já estão sendo usados pela configuração padrão do Webpack da Estrutura do SharePoint, como:

html-loader
json-loader
loader-load-themed-styles

Estender a configuração da estrutura Webpack com carregadores customizados é um processo direto documentado em Carregadores Webpack.

Exemplo: Usando o pacote de carregador de redução

Por exemplo, vamos usar o pacote markdown-loader. É um carregador que permite que você faça referência a um arquivo .md como uma cadeia de caracteres HTML.

É possível baixar a amostra completa em samples/js-extend-webpack.

Etapa 1: instalar o pacote

Faça referência ao markdown-loader no nosso projeto:

npm i --save markdown-loader

Etapa 2: configurar o Webpack

Agora que temos o pacote instalado, vamos definir a configuração do Webpack da Estrutura do SharePoint para incluir o markdown-loader.

Na documentação do carregador de redução, ele mostra como estender a configuração do Webpack para incluir o carregador:

{
  module: {
    rules: [
      {
        test: /\.md$/,
        use: [
          {
            loader: 'html-loader'
          },
          {
            loader: 'markdown-loader',
            options: {
              /* options for markdown-loader here */
            }
          }
        ]
      }
    ]
  }
}

Vamos dar uma olhada no que essa configuração está fazendo:

A matriz rules na configuração do Webpack define um conjunto de testes de caminho de arquivo e carregadores que devem ser usados quando um recurso que corresponda ao teste for encontrado. Nesse caso, a propriedade test verifica caminhos de arquivo que terminam com .md.
A matriz use descreve uma lista dos carregadores que são sequencialmente aplicados ao recurso. Eles são aplicados do último ao primeiro. Neste caso, o primeiro carregador a ser aplicado é o markdown-loader, e o último é o html-loader.
Quando vários carregadores são especificados, o resultado de cada carregador é associado ao próximo.

Usaremos essas informações para configurá-lo em nosso projeto.

Para adicionar esse carregador personalizado à configuração do Webpack da Estrutura do SharePoint, precisamos instruir a tarefa de compilação para configurar o Webpack. As tarefas de construção são definidas no gulpfile.js que está localizado na raiz do seu projeto.

Edite o gulpfile.js e adicione o seguinte código imediatamente antes de build.initialize(gulp);:

build.configureWebpack.mergeConfig({
  additionalConfiguration: (generatedConfiguration) => {
    generatedConfiguration.module.rules.push(
      {
        test: /\.md$/,
        use: [
          {
            loader: 'html-loader'
          },
          {
            loader: 'markdown-loader'
          }
        ]
      }
    );

    return generatedConfiguration;
  }
});

Vamos examinar o que esse trecho de código está fazendo:

O ConfigureWebpackTask (instanciado como build.configureWebpack) configura o Webpack para nós. Há várias configurações especiais que acontecem para compilar projetos SPFx, portanto, há alguma lógica não pessoal nesta tarefa.
O ConfigureWebpackTask leva a propriedade opcional additionalConfiguration. Queremos definir essa propriedade como uma função que captura a configuração gerada, realiza modificações nela e retorna a configuração atualizada. Esta função deve retornar uma configuração do Webpack para o conjunto de ferramentas, caso contrário, o Webpack não será configurado corretamente.
No corpo da função que definimos como additionalConfiguration, basta enviar uma nova regra para o conjunto de regras existentes na configuração. Observe que esta nova regra é semelhante ao exemplo no snippet de configuração na parte superior da Etapa 2.

Observação

Enquanto você for capaz de substituir completamente a configuração padrão do Webpack da cadeia de ferramentas usando essa abordagem, para obter o benefício máximo com o desempenho e a otimização, não é recomendável fazê-lo, a menos que indicado o contrário na documentação.

Etapa 3: atualizar seu código

Agora que configuramos o carregador, vamos atualizar nosso código e adicionar alguns arquivos para testar o cenário.

Crie um arquivo ./src/my-markdown.md com algum texto de markdown nele.

#Hello Markdown

*Markdown* is a simple markup format to write content.

You can also format text as **bold** or *italics* or ***bold italics***

Quando você cria o projeto, o markdown-loader do Webpack converte esse texto de markdown em uma cadeia de caracteres HTML.

Para usar esta cadeia de caracteres HTML em qualquer um de seus arquivos .ts de origem, adicione a seguinte require() linha na parte superior do arquivo após suas importações, por exemplo:
```
const markdownString: string = require<string>('./../../../../src/my-markdown.md');
```
O Webpack, por padrão, procura o arquivo na pasta lib, mas, por padrão, os arquivos .md não são copiados para a pasta lib, o que significa que precisamos criar um caminho relativo bastante longo. Podemos controlar essa configuração definindo um arquivo de configuração para instruir a cadeia de ferramentas a copiar md arquivos para a pasta lib.
Crie um arquivo ./config/copy-static-assets.json para instruir o sistema de build a copiar alguns arquivos adicionais do src para lib. Essa tarefa de build copia arquivos com extensões que a configuração padrão do Webpack de cadeia de ferramentas entende (como png e json), portanto, precisamos apenas instrui-la a copiar também arquivos md.
```
{
  "includeExtensions": [
    "md"
  ]
}
```
Agora, em vez de usar o caminho relativo, você pode usar o caminho do arquivo na sua instrução require, por exemplo:
```
const markdownString: string = require<string>('./../../readme.md');
```
Você então pode fazer referência a essa cadeia de caracteres em seu código, por exemplo:
```
public render(): void {
  this.domElement.innerHTML = markdownString;
}
```

Etapa 4: criar e testar seu código

Para criar e testar seu código, execute o seguinte comando em um console na raiz do diretório do projeto:

gulp serve

Confira também

Visão geral da Estrutura do SharePoint

Compartilhar via